marketing: FRE-199 third pair of informational pages (drafts) + pitch narrowed to the no-figure shape

Pair 3 (internal target Thu 2026-11-12, six days early):
- agent-worktree-contention — 'How do you manage worktrees when your agents
  end up waiting on each other?' (backlog 1xlz2bs, Scan 6 #4); git worktree +
  Docker Compose project-name docs fetched and read 2026-11-05.
- agent-keeps-asking — 'Why does your coding agent keep stopping to ask you
  questions?' (handback cluster: 1xlfqmo, 1xk0ghj, 1xlxw0q); permission +
  hooks claims re-verified live 2026-11-05 against code.claude.com; the
  1xlfqmo poster's measurement figures deliberately not cited.

Pitch narrowed per CTO reopening verdict: trial→paid placeholder deleted
(FRE-202 cohort too young; ratio waits for FRE-197), second breakage chosen
(NOOK-815 uninvoked suite), any count named as activations, downloads never
quoted.

marketing/README.md

@@ -22,3 +22,12 @@ a human reviews and moves it to `approved/` → the human publishes from `approv
 under their own account → the artifact (or a pointer) lands in `posted/`.
 
 Nothing in `drafts/` or `pending/` is ever publishable, by anyone, by any means.
+
+## The weekly read
+
+`bun --env-file=.env scripts/weekly-metrics.ts` (or `bun run metrics:weekly`)
+rewrites `metrics/weekly.md` from the live databases: the staged funnel, the
+campaign breakdown (`getAnalyticsSummary.topCampaigns`' grouping), and the one
+stage that moved. It needs `TURSO_DB_URL`, `TURSO_DB_TOKEN`, `NOOK_DB_URL` and
+`NOOK_DB_TOKEN` — no other production secret. The file is generated; never
+hand-edit it. The numbers are engineering's; the interpretation is the CMO's.

marketing/approved/agent-done-signal/copy.md

@@ -0,0 +1,92 @@
+# How do you know when your coding agent is done?
+
+> **Status: approved — sponsor fact-check passed 2026-11-05** (FRE-199 fact-check
+> card, verdict: "Approve both — move to approved/"). Not published; a human
+> places it on nook.freno.me from `approved/`.
+> This page never names a product of ours and never names a competitor.
+> Internal target: first page of the FRE-199 pair, Thu 2026-11-06.
+> CTO review 2026-11-05: changes requested and applied — the `osascript`
+> example is attributed to the hooks guide, not the hooks reference; pair-1
+> citations standardised to code.claude.com.
+
+Often, you don't — not from the terminal alone. A coding agent's turn can end in
+silence: the prompt returns, the cursor blinks, and a finished turn looks exactly
+like one that stalled, is still running, or is waiting on you. The fix is to stop
+trusting silence and wire the two moments that matter — *the turn ended* and *the
+agent needs you* — to something you will actually see.
+
+## Why silence is the failure mode
+
+A terminal coding agent ends a turn by printing a prompt. If you are in another
+window, another room, or running several agents at once, nothing in that output
+distinguishes "finished" from "blocked on a permission prompt" from "dead". The
+task being done and you finding out are two different events, and the second one
+has no default signal.
+
+Practitioners keep rediscovering this. One operator running a self-hosted queue
+of autonomous agent sessions described sessions that "finished their work but
+never sent the done signal, and held their slots for hours" — their fix was to
+derive "done" from git state plus an idle transcript instead of trusting the
+agent's own signal. A public service post about a code-review plugin described
+the mirror image: a green checkmark and "No findings" when the review had not
+run at all. An empty result and a successful result rendered identically.
+
+That is the trap in one sentence: **zero looks exactly like success.**
+
+## What the turn-ending signal actually is
+
+Claude Code gives you two hooks that bracket the moments worth surfacing:
+
+- **`Stop`** fires when the agent finishes responding — the end of a turn.
+- **`Notification`** fires when Claude Code sends a notification. A permission
+  prompt is one of these: the hook's payload carries a `notification_type` of
+  `permission_prompt` and a message like "Claude needs your permission".
+- **`StopFailure`** fires instead of `Stop` when the turn ends on an API error —
+  rate limits, authentication problems, and the like.
+
+All three can run a command of your choosing. The hooks reference documents the
+events; the hooks guide includes a desktop-notification example built on
+macOS's `osascript`.
+
+## What to check or do
+
+1. **Wire turn-end to a notification you will actually notice.** A `Stop` hook
+   that calls `osascript -e 'display notification …'` (or your terminal's
+   notification escape) turns the silent prompt-return into a visible event.
+   A terminal bell is not this — it is mute the moment you switch windows.
+2. **Route permission waits separately from completions.** The `Notification`
+   hook's payload tells you which kind it is. A permission wait means the agent
+   is *blocked on you*; treating it as "done" hides the one state that costs the
+   most time.
+3. **Don't trust the exit signal alone.** Check the artifacts: `git status`,
+   `git log`, whether the transcript has gone idle. The queue operator's rule
+   generalises — a "done" that has to name what it is waiting on is a "done"
+   you can act on.
+4. **Surface the failure path too.** A turn that ends on an API error fires
+   `StopFailure`, not `Stop` — an alert wired to the wrong one misses exactly
+   the runs that need attention.
+
+One next step: take the agent command you run most often and give its end-of-turn
+a notification you would notice from across the room. That single wire closes the
+most expensive silence in the workflow.
+
+---
+
+## Fact-check table (not part of the page)
+
+Every technical claim above, with its primary source. Claims about Claude Code's
+behaviour come from its own documentation, re-read 2026-11-05.
+
+| # | Claim in the page | Source |
+|---|---|---|
+| 1 | `Stop` fires when the agent finishes responding (end of a turn); hook cadence is "per turn: UserPromptSubmit, Stop, StopFailure" | Claude Code hooks reference — https://code.claude.com/docs/en/hooks |
+| 2 | `Notification` fires "when Claude Code sends a notification"; example payload carries `notification_type: "permission_prompt"`, message "Claude needs your permission" | same hooks reference (Notification event section) |
+| 3 | `StopFailure` "runs instead of Stop when the turn ends due to an API error" (rate limits, authentication) | same hooks reference (StopFailure section) |
+| 4 | Hooks run a command of your choosing; a desktop-notification example using `osascript` is in the hooks guide | Claude Code hooks guide — https://code.claude.com/docs/en/hooks-guide (desktop-notification example) |
+| 5 | Operator anecdote: sessions that finished work but never signalled done, holding slots for hours; fix = derive done from git + idle transcript | r/ClaudeCode thread 1xjb3j0 ("Are you running a self-hosted queue of autonomous Claude Code sessions?", 2026-10-31), quoted in `drafts/listening.md` Scan 4 addendum. Quoted as one operator's described practice, not a measurement. |
+| 6 | PSA anecdote: code-review plugin showed green check + "No findings" without running | r/ClaudeCode 1xmnz2c (2026-11-03), logged in `drafts/listening.md` Scan 6. |
+| 7 | "Zero looks exactly like success" | Verbatim buyer phrasing, three independent instances (1xm09fs, 1xmnz2c, plus HN repeats) in `drafts/listening.md` Scans 5–8. Used as the problem's name, attributed to no one. |
+
+**Ban compliance:** no product of ours named · no competitor named · no
+superlatives · no benchmark numbers · no invented testimonials (anecdotes are
+real threads, described without handles) · no price · no roadmap dates.

marketing/approved/agent-done-signal/rationale.md

@@ -0,0 +1,72 @@
+# Rationale — "How do you know when your coding agent is done?"
+
+FRE-199 item 1, page 1 of the first pair. Drafted 2026-11-05 by CMO.
+
+## The phrase
+
+Primary: **"how do you know when your coding agent is done"** (variants: "agent
+finished silently", "claude code waiting for permission" overlaps on the
+blocked-half; this page owns the *done*-half).
+
+Chosen by the FRE-199 selection rule: strongest buying intent we can answer
+honestly without naming a product. It is on the standing phrase list
+(`drafts/listening.md` §The phrase list: "how do I know when my agent is done").
+
+## Why this phrase won the slot
+
+- **Recurrence with independence.** The "zero looks exactly like success"
+  pattern appears in at least four separate sources across Scans 5–9: 1xm09fs,
+  the code-review PSA (1xmnz2c), and two HN commenters (fhub, sadilek), plus
+  the queue operator's done-signal workaround (1xjb3j0). Four independent
+  formulations of one pain in seven days is the strongest recurrence the
+  backlog shows.
+- **Buying intent.** The people describing it are running agents unattended
+  right now and are losing time to the gap — they are past curiosity.
+- **Answerable honestly, generically.** The mechanism (Stop / Notification /
+  StopFailure hooks) is documented in the agent's own reference; every claim in
+  the page traces to it. Nothing about our product is needed to answer it.
+- **Wedge-aligned.** "An agent blocked is the most expensive kind of idle" —
+  the done-half of that sentence (idle you never learn about) is this page.
+
+## Evidence trail
+
+| Thread | Date | What it showed |
+|---|---|---|
+| r/ClaudeCode 1xjb3j0 — "self-hosted queue of autonomous Claude Code sessions" | 2026-10-31 | Sessions "finished their work but never sent the done signal, and held their slots for hours"; operator derives done from git + idle transcript; "a waiting one has to name what it's waiting on" |
+| r/ClaudeCode 1xm09fs | 2026-11-02 | First "zero looks exactly like success" instance (verbatim buyer phrasing) |
+| r/ClaudeCode 1xmnz2c — code-review plugin PSA | 2026-11-03 | Green check + "No findings" when the review never ran; third independent instance |
+| HN comments (fhub, sadilek) | 2026-11-04/05 | Human-attention concurrency ceiling quantified twice more |
+
+All rows live in `drafts/listening.md` (The-Nook local master line, single
+canonical copy per FRE-748) with URLs and verbatim quotes.
+
+## Gates before this page ships
+
+1. **Sponsor fact-check** of the claims table in `copy.md` (owner: Michael
+   Freno). Page moves `pending/` → `approved/` on his read, per the marketing
+   tree's hard rule.
+2. **CTO eyes on the agent-behaviour claims** — all four are sourced to the
+   Claude Code hooks reference re-read 2026-11-05, but anything asserted about
+   an agent's behaviour is CTO-verifyable, and the FRE-199 plan routes it to
+   him.
+3. **Publish path:** `pending/` → `approved/` → a human places it on
+   nook.freno.me (blog route). Nothing posts itself.
+
+## Ban compliance (FRE-199 + positioning.md rule 1)
+
+- The Nook: not named. The notch, the island, the companion: not mentioned.
+- Competitors (notch apps, agent monitors, Remote Control–style tools): not
+  named. Remote Control is not mentioned either — the page answers the done-half
+  without touching the away-from-desk half.
+- Claude Code is named only as the subject whose documented behaviour the page
+  explains, with its own docs as the source — the same status the listening
+  phrase list already gives it. It is the agent, not a competitor.
+- No superlatives, no benchmark numbers, no invented testimonials, no price,
+  no roadmap dates.
+
+## Cadence note
+
+This page and `agent-waiting-on-permission/` are the first pair. The queue
+behind them (multiple-agents tracking, invisible-permission cluster) holds well
+above the three-candidate floor, so the two-a-week cadence holds without
+inventing phrases.

marketing/approved/agent-parallel-tracking/copy.md

@@ -0,0 +1,113 @@
+# How do you keep track of multiple coding agents?
+
+> **Status: approved — sponsor fact-check passed 2026-11-05** (FRE-199 pair 2
+> fact-check card, verdict: "Approve both — move to approved/"). Not published;
+> a human places it on nook.freno.me from `approved/`. Internal target:
+> Mon 2026-11-09, met four days early. This page never names a product of ours
+> and never names a competitor.
+
+The honest answer: not by watching them. Run three agents and the watching
+already fails — the session you are not reading is the one that finished, or
+the one sitting on a question, and both states look identical from the outside.
+The fix is not more windows; it is giving each agent a way to announce its own
+state, so checking becomes something that happens to you instead of something
+you have to remember.
+
+## Why attention is the limit
+
+Parallel agents are cheap to start and expensive to supervise. Every running
+session can stop and wait for you — a permission prompt, a question, a finished
+turn — and from your side of the screen those are invisible until you go look.
+Operators who run agents at scale keep describing the same wall in different
+words. One practitioner running dozens of parallel threads a day put it as the
+limit moving "from tokens to my attention"; another, asked how many sessions
+they could run, got the answer from their own comment section: not compute —
+you. A developer who ran agents unattended for a month summarised the failure
+as silence: "the six hours of silence was the real problem, not the dialog
+itself." And the most common collision is the simplest — two agents waiting on
+you while you are deep in the third, and one of them idle so long you lost the
+thread of what you asked it to do.
+
+None of that is a speed problem. It is a visibility problem: *which* of your
+agents needs you, and *how do you find out without touring every window?*
+
+## What a per-agent signal actually is
+
+A terminal coding agent has no shared dashboard by default — each session is
+its own process, its own window. But its state changes are events, and events
+can be wired outward. Claude Code documents the pieces:
+
+- **Every state you care about fires an event.** `Stop` fires when Claude
+  finishes responding — the end of a turn. `Notification` fires when Claude
+  Code sends a notification, and the notification's type tells you which kind
+  of waiting it is: a `permission_prompt`, an `idle_prompt`, `agent_needs_input`,
+  or `agent_completed`. `SessionStart` and `SessionEnd` bracket the whole
+  session.
+- **The event names the session it came from.** Every hook payload carries a
+  `session_id`, so one handler can serve every window and still know which
+  agent fired.
+- **A hook is just a command you choose.** The events are configured in the
+  settings files and run whatever command you point them at — append to a log
+  file, update a status line, send a desktop notification that names the
+  project.
+- **The status line can carry per-session state.** Claude Code's status line
+  is a customizable bar driven by a script you write; it receives session data
+  on every render, and the docs name "work across multiple sessions and need
+  to distinguish them" as a reason it exists.
+
+The pattern in all four: stop touring windows and make each agent's
+running / waiting / finished state observable where you already are.
+
+## What to check or do
+
+1. **Name the states before naming the tools.** For your workflow the states
+   are usually three — running, waiting on you, finished — and the expensive
+   one is always "waiting on you". A tracking setup that cannot distinguish a
+   permission wait from a completion will quietly hide the state that costs
+   the most.
+2. **Wire the waiting events first.** A `Notification` hook matched on
+   `permission_prompt` and `agent_needs_input` catches the blocked cases; the
+   payload's `session_id` lets one handler label each alert with the project
+   it came from.
+3. **Route completions separately.** `Stop` means the turn ended — not that
+   the work was right, and not that nothing is blocked elsewhere. Treating
+   "finished" and "needs you" as one notification is how a waiting agent gets
+   buried under a pile of done messages.
+4. **Make the state visible without switching windows.** A per-session status
+   line, a log file the hook appends to, or a desktop notification that names
+   the project all work — the test is whether you can answer "does anything
+   need me?" without leaving the window you are in.
+5. **Expect the ceiling to be yours.** Operators consistently find the
+   bottleneck before the machines do. The number of agents you can run is the
+   number whose waiting state reaches you reliably — not the number your
+   terminal can host.
+
+One next step: run two agents side by side and wire only their permission-wait
+events to a notification that names the project. The first time the second
+agent's prompt reaches you before you happen to check its window is the whole
+argument.
+
+---
+
+## Fact-check table (not part of the page)
+
+Every technical claim above, with its primary source. Claims about Claude
+Code's behaviour come from its own documentation, re-read 2026-11-05.
+
+| # | Claim in the page | Source |
+|---|---|---|
+| 1 | `Stop` fires when Claude finishes responding; `SessionStart`/`SessionEnd` are per-session events | Claude Code hooks reference — https://code.claude.com/docs/en/hooks (hook events table; "per session: SessionStart and SessionEnd; per turn: UserPromptSubmit, Stop, and StopFailure") |
+| 2 | `Notification` fires when Claude Code sends a notification; matcher supports notification types including `permission_prompt`, `idle_prompt`, `agent_needs_input`, `agent_completed` | same hooks reference (matcher table: "Notification | notification type") |
+| 3 | Every hook payload carries `session_id`, the current session identifier | same hooks reference (Common input fields: `session_id` — "Current session identifier") |
+| 4 | Hooks are configured in the settings files and run a command of your choosing | same hooks reference (configuration and command-hook examples) |
+| 5 | The status line is a customizable bar driven by a script, receives JSON session data, and the docs name "work across multiple sessions and need to distinguish them" as a use | Claude Code status line doc — https://code.claude.com/docs/en/statusline |
+| 6 | "The limit moved from tokens to my attention" / "fifty a day add up to something I could feel by Friday" | r/ClaudeCode 1xh5cum (2026-10-27, "Four months of 50+ parallel agent threads a day"), logged in `drafts/listening.md` Scan 3. Practitioner's own account, not a measurement. |
+| 7 | "How many sessions before you become the bottleneck" — the thread went to compute; the attention half stayed on the table | r/ClaudeCode 1xdjb2g (2026-10-23, 72 comments), logged in `drafts/listening.md` Scan 1. |
+| 8 | "The six hours of silence was the real problem, not the dialog itself" | r/ClaudeCode 1xipsk0 (2026-10-29, "~40 Claude Code agents unattended for a month"), quoted by the OP in-thread, logged in `drafts/listening.md` Scan 2. |
+| 9 | Two agents waiting while the human is in the third; idle so long the thread of the task was lost; "most of my idle time came from agents waiting on a permission prompt while I was in another window" | r/ClaudeAI 1xmzp2n (2026-11-03, "How do you keep track of multiple coding agents running in parallel?"), two independent commenters, logged in `drafts/listening.md` Scan 9. |
+| 10 | "You're the bottleneck agents were meant to eliminate" — approvals routing through one person | r/ClaudeCode 1xk0ghj (2026-10-31, "multiple agents working on multiple projects"), commenter's words, logged in `drafts/listening.md` Scan 4. |
+
+**Ban compliance:** no product of ours named · no competitor named (herdr,
+tmux, dashboards: none named — the page answers generically) · no handles · no
+superlatives · no benchmark numbers · no invented testimonials (anecdotes are
+real threads, described without handles) · no price · no roadmap dates.

marketing/approved/agent-parallel-tracking/rationale.md

@@ -0,0 +1,71 @@
+# Rationale — "How do you keep track of multiple coding agents?"
+
+FRE-199 item 1, page 1 of the second pair. Drafted 2026-11-05 by CMO (internal
+target Mon 2026-11-09, beaten by four days — the backlog held, so drafting
+early cost nothing).
+
+## The phrase
+
+Primary: **"how do you keep track of multiple coding agents running in
+parallel"** (variants: "how many sessions before you become the bottleneck",
+"which agent is waiting", "agent tracking dashboard").
+
+## Why this phrase won the slot
+
+- **Strongest recurrence in the backlog.** Seven independent threads across
+  nine scans state the multi-agent attention problem in their own words — more
+  than any other cluster after the pair-1 phrases. It is the natural next page:
+  the pair-1 pages answer *one* agent's silence (done-signal) and *one*
+  permission wait (waiting-on-permission); this is the fleet-scale version of
+  the same pain, and the buyers are already at fleet scale.
+- **Buying intent.** Every quoting operator is running multiple agents *now*
+  and losing time to supervision, not exploring.
+- **Answerable honestly, generically.** The mechanism (per-session hook events
+  with `session_id`, typed notifications, the status line) is documented in the
+  agent's own reference; every claim traces to it. No product needed.
+- **Distinct from pair 1.** Done-signal owns "one agent, is it finished";
+  waiting-on-permission owns "one agent, why is it blocked". This page owns
+  "several agents, which one needs me" — the phrase, the evidence, and the
+  mechanism (typed Notification matchers, `session_id`, status line) do not
+  overlap pair 1's.
+
+## Evidence trail
+
+| Thread | Date | What it showed |
+|---|---|---|
+| r/ClaudeAI 1xmzp2n — "How do you keep track of multiple coding agents running in parallel?" | 2026-11-03 | The exact question as a fresh thread: "How do you notice when one is waiting, done, or stuck?"; two commenters independently: agents "sat waiting on a permission prompt while I was deep in the third", idle "long enough that I lost the thread of what I had asked it to do" |
+| r/ClaudeCode 1xh5cum — "Four months of 50+ parallel agent threads a day" | 2026-10-27 | "The limit moved from tokens to my attention"; "fifty a day add up to something I could feel by Friday" |
+| r/ClaudeCode 1xdjb2g — "How many sessions can you run before you become the bottleneck?" | 2026-10-23 | 72 comments; the thread went to compute and left the attention half open |
+| r/ClaudeCode 1xipsk0 — "~40 Claude Code agents unattended for a month" | 2026-10-29 | "The six hours of silence was the real problem, not the dialog itself" |
+| r/ClaudeCode 1xk0ghj — "multiple agents working on multiple projects" | 2026-10-31 | "If every decision routes through you, you're the bottleneck agents were meant to eliminate" |
+| Hacker News 50298436 (herdr launch) | 2026-10-30 | A 30-year tmux user's stated switch reason: "visual indication which agent is working and which is waiting for an input" — used in rationale only; the page does not name any tool |
+
+All rows live in `drafts/listening.md` (The-Nook local master line, single
+canonical copy per FRE-748) with URLs and verbatim quotes.
+
+## Gates before this page ships
+
+1. **Sponsor fact-check** of the claims table in `copy.md` (owner: Michael
+   Freno). Page moves `drafts/` → `pending/` → `approved/` on his read, per
+   the marketing tree's hard rule.
+2. **CTO eyes on the agent-behaviour claims** — five doc-sourced claims
+   (hooks reference ×4, statusline doc ×1), all re-read 2026-11-05. Routed to
+   the CTO per the FRE-199 plan.
+3. **Publish path:** `approved/` → a human places it on nook.freno.me.
+   Nothing posts itself.
+
+## Ban compliance (FRE-199 + positioning.md rule 1)
+
+- The Nook: not named. The notch, the island, the companion: not mentioned.
+- Competitors: not named. The herdr evidence is rationale-only; the page's
+  "what to check" recommends no tool at all — states and wiring, not products.
+- Claude Code is named only as the subject whose documented behaviour the page
+  explains, with its own docs as the source — same status as pair 1.
+- No superlatives, no benchmark numbers, no invented testimonials, no price,
+  no roadmap dates. Anecdotes are real threads, described without handles.
+
+## Cadence note
+
+Second pair. Queue behind it: the run-without-asking cluster (same pair), the
+fan-control phrase, and the invisible-permission variants — above the
+three-candidate floor. Two a week holds.

marketing/approved/agent-run-without-asking/copy.md

@@ -0,0 +1,102 @@
+# Should you let your coding agent run without asking permission?
+
+> **Status: approved — sponsor fact-check passed 2026-11-05** (FRE-199 pair 2
+> fact-check card, verdict: "Approve both — move to approved/"). Not published;
+> a human places it on nook.freno.me from `approved/`. Internal target:
+> Mon 2026-11-09, met four days early. This page never names a product of ours
+> and never names a competitor.
+> CTO review 2026-11-05: changes requested and applied — the `Bash(git commit *)`
+> allowed / `Bash(git push *)` denied example removed (the docs' own
+> "What a Bash rule doesn't match" table shows a Bash rule does not stop every
+> invocation); the precedence claim stands.
+
+You can — and the honest answer is that "should" is not one decision but two:
+what you are letting it do, and what happens when it does the wrong thing.
+Every operator who runs agents unattended converges on the same split — a free
+hand on what git can undo, a confirmation on what it can't — and the agent's
+own permission modes exist to draw that line somewhere you choose, not
+somewhere a flag chooses for you.
+
+## The mechanism: a spectrum, not a switch
+
+Claude Code's permission modes form a ladder from "ask for everything" to "ask
+for almost nothing", and each rung has a documented meaning:
+
+- **`default`** prompts on the first use of each tool.
+- **`acceptEdits`** auto-accepts file edits and common filesystem commands
+  (`mkdir`, `touch`, `mv`, `cp`) inside the working directory.
+- **`plan`** reads files and runs read-only shell commands but does not edit
+  your source files — the agent explores, you approve the plan.
+- **`auto`** runs without routine prompts; before actions such as shell
+  commands and network requests run, a background classifier checks that they
+  align with your request.
+- **`bypassPermissions`** skips permission prompts, except for actions no mode
+  auto-approves.
+
+Two documented facts should shape where you stop on that ladder. First, the
+docs' own warning on the top rung: in `bypassPermissions` mode Claude Code
+skips prompts — including for writes to protected paths such as `.git` — and
+the mode belongs "in isolated environments like containers or VMs where Claude
+Code can't cause damage". Second, enforcement is real, not advisory: the docs
+state plainly that "permission rules are enforced by Claude Code, not by the
+model" — a `CLAUDE.md` instruction asking nicely for permission changes
+nothing.
+
+## What to check or do
+
+1. **Decide by blast radius, not by annoyance.** The question "how do I get
+   fewer prompts?" tempts a jump to the top of the ladder. The better
+   question: which of this agent's actions would be *undoable* if wrong? Edits
+   inside a git worktree are; `rm -rf` on the wrong path, a pushed commit, and
+   a message sent to a third party are not.
+2. **Move down the ladder one rung at a time.** `acceptEdits` in a worktree
+   covers most of the prompt volume with the undo still in reach. If you
+   consider `auto` or `bypassPermissions`, the docs' own container-or-VM
+   condition is the bar: isolation first, autonomy second.
+3. **Write the rules instead of trusting the mode.** Rules are evaluated in
+   order — deny, then ask, then allow — and the first match wins, so a broad
+   deny holds even against a narrower allow. (What a Bash rule cannot do is
+   match every way the same binary gets invoked — see the next step.)
+4. **Know what the rules do not cover.** A Bash rule matches the command text
+   Claude writes, and the docs are explicit that this "isn't a security
+   boundary around the program" — the same binary invoked by another path is
+   not matched. For filesystem and network enforcement that does not depend
+   on command text, the docs point at sandboxing.
+5. **Use hooks as the programmable layer.** A `PreToolUse` hook sees every
+   tool call before it runs and can return a `deny` decision — the reference
+   builds one that blocks `rm -rf`. A silent hook does not approve anything;
+   the call just continues through the normal permission flow.
+6. **Leave the failure path a way to reach you.** An unattended run that hits
+   a prompt nobody sees stops silently — that is the failure mode of unattended
+   work, not of permissions. Whatever mode you pick, wire the
+   "waiting on you" event somewhere you will actually notice.
+
+One next step: write down the three actions your agent takes that you could
+not undo, and put them in `deny` or `ask` rules today. Whatever mode you run
+above them, those three now require a human — which is the whole point of the
+ladder.
+
+---
+
+## Fact-check table (not part of the page)
+
+Every technical claim above, with its primary source. Claims about Claude
+Code's behaviour come from its own documentation, re-read 2026-11-05.
+
+| # | Claim in the page | Source |
+|---|---|---|
+| 1 | Mode meanings: `default` prompts on first use; `acceptEdits` auto-accepts file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`) in the working directory; `plan` reads files and runs read-only shell commands but doesn't edit source; `auto` runs without routine prompts with a background classifier checking alignment; `bypassPermissions` skips prompts except actions no mode auto-approves | Claude Code permissions doc — https://code.claude.com/docs/en/permissions (Permission modes table) |
+| 2 | Docs' warning: in `bypassPermissions` mode Claude Code skips prompts including for writes to protected paths such as `.git`; "Only use this mode in isolated environments like containers or VMs where Claude Code can't cause damage" | same permissions doc (warning under the modes table) |
+| 3 | "Permission rules are enforced by Claude Code, not by the model" | same permissions doc (note under Manage permissions) |
+| 4 | Rules evaluated in order deny → ask → allow; first match wins; a broad deny holds against a narrower allow | same permissions doc (Manage permissions) |
+| 5 | A Bash rule matches the command text Claude writes and "isn't a security boundary around the program" (`Bash(curl *)` doesn't stop `/usr/bin/curl …`); for filesystem/network enforcement independent of command text the docs point at sandboxing | same permissions doc (What a Bash rule doesn't match) |
+| 6 | A `PreToolUse` hook fires before a tool call executes, can block it, and can return a `permissionDecision` of `"deny"`; the reference builds a hook that blocks `rm -rf`; a silent hook does not approve — the call continues through the normal permission flow | Claude Code hooks reference — https://code.claude.com/docs/en/hooks (PreToolUse decision control walkthrough) |
+| 7 | Undo-split practice ("free hand on what git can undo, confirmation on what it can't") | r/ClaudeCode 1xkoz06 (2026-10-31), commenter's described practice, logged in `drafts/listening.md` Scan 3 addendum; also r/ClaudeCode 1xexhwf commenters (VM, worktrees, blast-radius split). Described as operator practice, not a rule. |
+| 8 | An unattended run that hits a prompt nobody sees stops silently | r/ClaudeCode 1xipsk0 (2026-10-29), commenter: "A run started from launchd or a background service can hit a prompt that no one will ever see", logged in `drafts/listening.md` Scan 2. |
+| 9 | The trust asymmetry: comfortable with a model writing code, "considerably less comfortable giving an autonomous agent broad access to my development environment" | r/ClaudeCode 1xk8imc (2026-10-31, "Has anyone built a safe, autonomous coding workflow…?", 43 comments), OP's words, logged in `drafts/listening.md` Scan 4. |
+| 10 | The operator's own safety menu: "committing before every run? containers? `--dangerously-skip-permissions` and hoping?" | r/ClaudeAI 1xk277d (2026-10-31, "How often has a coding agent done something you had to undo?"), OP's words, logged in `drafts/listening.md` Scan 4. Quoted as the question's shape, not as guidance. |
+
+**Ban compliance:** no product of ours named · no competitor named · no
+handles · no superlatives · no benchmark numbers · no invented testimonials ·
+no price · no roadmap dates. The docs' container/VM warning is quoted as the
+agent's own documentation, not as our policy.

marketing/approved/agent-run-without-asking/rationale.md

@@ -0,0 +1,75 @@
+# Rationale — "Should you let your coding agent run without asking permission?"
+
+FRE-199 item 1, page 2 of the second pair. Drafted 2026-11-05 by CMO (internal
+target Mon 2026-11-09, beaten by four days).
+
+## The phrase
+
+Primary: **"do you let your coding agent run without asking permission"**
+(variants: "safe autonomous coding workflow", "approve every step or skip
+permissions", "is dangerously-skip-permissions safe").
+
+On the standing phrase list (`drafts/listening.md` §The phrase list: "do you
+let claude code run without asking").
+
+## Why this phrase won the slot
+
+- **Recurrence with independence.** Four separate threads state the autonomy
+  question from four angles: the direct one (1xexhwf, 24 comments), the trust
+  asymmetry (1xk8imc, 43 comments), the safety menu (1xk277d), and the
+  remove-permissions ask (1xfe6eh — Desktop, recorded, not answered). The
+  cluster has run continuously since Scan 1.
+- **Buying intent.** These are people configuring or rejecting autonomy right
+  now — the objection vocabulary came straight out of this cluster
+  ("--dangerously-skip-permissions and hoping").
+- **Answerable honestly, generically.** The mode ladder, the docs' own
+  container/VM warning, the enforcement note, and `PreToolUse` deny are all
+  documented; every claim traces to the agent's docs. No product needed.
+- **Distinct from pair 1's permission page.** `agent-waiting-on-permission`
+  answers "why is it *blocked* and why didn't I know" — the visibility of a
+  single stuck prompt. This page answers "should I *grant* autonomy and how do
+  I bound it" — the mode ladder, rule precedence, sandboxing, and hooks as
+  enforcement. Shared vocabulary (modes, rules) exists because the docs are
+  one system; the question, the claims, and the advice do not overlap.
+
+## Evidence trail
+
+| Thread | Date | What it showed |
+|---|---|---|
+| r/ClaudeCode 1xexhwf — "Do you let Claude Code run without asking, or approve every step?" | 2026-10-25 | The direct question, 24 comments; the thread became a safety argument (VM, worktrees, empty-variable `rm -rf`) — that argument *is* the page's subject |
+| r/ClaudeCode 1xk8imc — "Has anyone built a safe, autonomous coding workflow…?" | 2026-10-31 | "Comfortable having another model work on code. Considerably less comfortable giving an autonomous agent broad access to my development environment" — the trust asymmetry, 43 comments |
+| r/ClaudeAI 1xk277d — "How often has a coding agent done something you had to undo?" | 2026-10-31 | "What you do to stay safe today: committing before every run? containers? `--dangerously-skip-permissions` and hoping?" — the operator's own menu |
+| r/ClaudeCode 1xipsk0 — "~40 agents unattended for a month" | 2026-10-29 | "A run started from launchd or a background service can hit a prompt that no one will ever see" — the unattended failure path |
+| r/ClaudeCode 1xkoz06 | 2026-10-31 | The undo-split practice (also cited on pair 1; real thread, described without handles) |
+| r/ClaudeAI 1xfe6eh — "How can I remove Claude's need to ask me for permission…" | 2026-10-30 | Recorded, not used: Claude Desktop computer-use, not Code — a mention there would be noise. Shows the phrase's reach |
+
+All rows live in `drafts/listening.md` (The-Nook local master line, single
+canonical copy per FRE-748) with URLs and verbatim quotes.
+
+## Gates before this page ships
+
+1. **Sponsor fact-check** of the claims table in `copy.md` (owner: Michael
+   Freno). Page moves `drafts/` → `pending/` → `approved/` on his read.
+2. **CTO eyes on the agent-behaviour claims** — six doc-sourced claims
+   (permissions doc ×5, hooks reference ×1), all re-read 2026-11-05. Routed to
+   the CTO per the FRE-199 plan.
+3. **Publish path:** `approved/` → a human places it on nook.freno.me.
+   Nothing posts itself.
+
+## Ban compliance (FRE-199 + positioning.md rule 1)
+
+- The Nook: not named. The notch, the island, the companion: not mentioned.
+- Competitors: not named. Sandboxing and hooks are described as the agent's
+  own documented mechanisms, not as anyone's product.
+- Claude Code is named only as the subject whose documented behaviour the page
+  explains, with its own docs as the source — same status as pair 1.
+- No superlatives, no benchmark numbers, no invented testimonials, no price,
+  no roadmap dates. Anecdotes are real threads, described without handles.
+
+## Cadence note
+
+Second pair. Queue behind it: the fan-control phrase ("mac fan control
+claude", standing phrase list), the invisible-permission variants
+(dontallow/TCC cluster), and the notification-reliability thread (1xm6frp,
+held back for overlap with done-signal). Above the three-candidate floor; two
+a week holds.

marketing/approved/agent-waiting-on-permission/copy.md

@@ -0,0 +1,86 @@
+# Why is my coding agent sitting on a permission prompt?
+
+> **Status: approved — sponsor fact-check passed 2026-11-05** (FRE-199 fact-check
+> card, verdict: "Approve both — move to approved/"). Not published; a human
+> places it on nook.freno.me from `approved/`.
+> This page never names a product of ours and never names a competitor.
+> Internal target: second page of the FRE-199 pair, Fri 2026-11-07.
+> CTO review 2026-11-05: changes requested and applied — rule precedence
+> corrected to deny / ask / allow (body previously read allow / ask / deny,
+> contradicting the fact-check table and the source); pair-1 citations
+> standardised to code.claude.com.
+
+Because it tried to do something its permission settings don't allow, and the
+default is to wait — indefinitely and quietly — for you. The prompt is not the
+expensive part; the hour you spent not knowing it was waiting is. The way out is
+not to approve faster, it's to make the prompts rare and the waiting visible.
+
+## The mechanism
+
+Claude Code's permission system decides, per tool call, whether to run, refuse,
+or stop and ask. In its `default` mode, it prompts for permission on the first
+use of each tool. Modes are set with `defaultMode` in the settings files, and a
+session's rules come from deny / ask / allow lists evaluated in that order —
+the first match wins.
+
+You can see the whole rule set at any time with `/permissions`, which lists
+every permission rule and the settings file each one came from. Rules can name
+a specific use — `Bash(npm run build)` matches exactly that command — or a
+wildcard, like `Bash(git log *)`.
+
+So the prompt you came back to an hour later is not a malfunction. It is the
+system working as configured, on a call your rules never covered — and the
+"waiting" state being invisible is what turned ten seconds of approval into a
+lost hour.
+
+## What to check or do
+
+1. **Read the prompt before automating it away.** It names the tool and the
+   input. The right response to "it keeps asking" is usually a rule, not a
+   wider mode.
+2. **Allowlist the undoable, prompt on the irreversible.** Reads, tests, and
+   status commands are safe to allow — `git` is the undo for edits. Anything
+   that reaches another person or another system — network calls, deletes,
+   deploys — is worth keeping on ask. Rule syntax is in the permission docs;
+   `/permissions` shows what you already have.
+3. **Consider `acceptEdits` before anything broader.** It auto-accepts file
+   edits and common filesystem commands inside the working directory. That is
+   usually the difference between ten prompts a session and two — without
+   handing over network or delete.
+4. **Bound the blast radius instead of removing the gate.** If you do widen
+   what runs unattended, do it where a mistake is recoverable: a worktree per
+   task, commits pushed early, nothing irreversible in reach. Operators who run
+   agents unattended describe exactly this split — free hand on what git can
+   undo, confirmation on what it can't.
+5. **Make the wait visible.** Claude Code fires a `Notification` hook when it
+   sends a notification, and a permission prompt is one — the payload carries a
+   `notification_type` of `permission_prompt`. A hook on that event, wired to a
+   desktop notification you'd see from another window, turns the silent wait
+   back into a ten-second approval.
+
+One next step: run `/permissions` today and add allow rules for the three
+commands you find yourself approving most. The prompts that remain will be the
+ones that deserve a read.
+
+---
+
+## Fact-check table (not part of the page)
+
+Every technical claim above, with its primary source. Claims about Claude
+Code's behaviour come from its own documentation, re-read 2026-11-05.
+
+| # | Claim in the page | Source |
+|---|---|---|
+| 1 | In `default` mode Claude Code "prompts for permission on first use of each tool" | Claude Code permissions doc — https://code.claude.com/docs/en/permissions (Permission modes table) |
+| 2 | `defaultMode` in settings files sets the default mode for new sessions | same permissions doc (Permission modes section) |
+| 3 | Rules are evaluated deny → ask → allow, first match wins | same permissions doc (Permission rule syntax) |
+| 4 | `/permissions` lists all permission rules and the settings.json each comes from | same permissions doc (Manage permissions) |
+| 5 | `Bash(npm run build)` matches the exact command; `Bash(git log *)` wildcard form | same permissions doc (Use specifiers for fine-grained control) |
+| 6 | `acceptEdits` "automatically accepts file edits and common filesystem commands such as mkdir, touch, mv, cp for paths in the working directory" | same permissions doc (Permission modes table) |
+| 7 | A `Notification` hook fires when Claude Code sends a notification; permission prompts carry `notification_type: "permission_prompt"` and a message like "Claude needs your permission" | Claude Code hooks reference — https://code.claude.com/docs/en/hooks (Notification event) |
+| 8 | Undo-split practice ("free hand on what git can undo, confirmation on what it can't") | r/ClaudeCode 1xkoz06 (2026-10-31, u/tomm3hshipp thread), commenter's described practice, logged in `drafts/listening.md` Scan 3 addendum. Described as one operator's approach, not a rule. |
+| 9 | The 55-minutes-lost framing | r/ClaudeAI 1xhbc71 (2026-10-28): "coming back an hour later to find it's been sitting on a permission prompt for 55 minutes". Used as the problem's shape, not quoted as a person. |
+
+**Ban compliance:** no product of ours named · no competitor named · no
+superlatives · no benchmark numbers · no invented testimonials · no price · no
+roadmap dates.

marketing/approved/agent-waiting-on-permission/rationale.md

@@ -0,0 +1,77 @@
+# Rationale — "Why is my coding agent sitting on a permission prompt?"
+
+FRE-199 item 1, page 2 of the first pair. Drafted 2026-11-05 by CMO.
+
+## The phrase
+
+Primary: **"claude code waiting for permission"** and the away-from-desk variant
+("approvals when you're away from the computer"). First phrase on the standing
+list (`drafts/listening.md` §The phrase list).
+
+## Why this phrase won the slot
+
+- **The strongest single thread in the backlog.** r/ClaudeAI 1xhbc71 (2026-10-28,
+  47 comments and moving) asks the buying question outright: kicked off a long
+  task, came back an hour later, agent had been sitting on a permission prompt
+  for 55 minutes. The thread's own answers (remote control, tmux+SSH,
+  skip-permissions, allowlists) prove demand; none of them makes the wait
+  visible at the machine — that is the honest gap this page answers without
+  naming anyone.
+- **The week's objection vocabulary.** Scans 1–9 keep returning "the model keeps
+  handing control back" and "stops and waits for me" — permission friction is
+  the category's core complaint, not a niche one.
+- **Recurring independent accounts.** The invisible-permission theme has three
+  independent accounts in one week (1xksutq — gh used without a visible prompt;
+  1xkejsp's Linux panel; the scheduled-tasks silent-stall finding), so the
+  search demand is not one loud thread.
+- **Wedge-aligned.** This is the literal wedge sentence's territory — "an agent
+  blocked on a permission prompt is the most expensive kind of idle" — answered
+  with the agent's own documented mechanism.
+
+## Deliberate scoping
+
+This page owns the **blocked-half** of the approval problem (why prompts happen,
+how to make them rare, how to make the wait visible at the machine). The
+**away-half** (controlling a remote agent from elsewhere) is a different phrase,
+a different page, and one where the honest answer is dominated by the agent
+vendor's own remote feature — the page deliberately does not go there
+(`drafts/listening.md` Scan 1 category intel #1).
+
+## Evidence trail
+
+| Thread | Date | What it showed |
+|---|---|---|
+| r/ClaudeAI 1xhbc71 — "How do you handle Claude Code approvals when you're away from your computer?" | 2026-10-28 | 55-minute wait on a permission prompt; 47 comments of demand; "what's still annoying about your setup?" |
+| r/ClaudeCode 1xkoz06 — "How permissive are you with AI and for how long?" | 2026-10-31 | The undo-split: "file edits, tests and branches get a free hand, since git is the undo. Anything that reaches another person … stays on confirm" |
+| r/ClaudeCode 1xksutq — gh used without visible prompt | 2026-11-01 | Third independent invisible-permission account of the week |
+| r/ClaudeCode 1xkejsp — Linux panel app | 2026-10-31 | Per-session "Needs You" differentiation shipping elsewhere; the need is real and cross-platform |
+
+All rows live in `drafts/listening.md` with URLs and verbatim quotes.
+
+## Gates before this page ships
+
+1. **Sponsor fact-check** of the claims table in `copy.md` (owner: Michael
+   Freno); page moves `pending/` → `approved/` on his read.
+2. **CTO eyes on the agent-behaviour claims** — all eight doc-sourced claims
+   re-read 2026-11-05; the FRE-199 plan routes anything asserted about an
+   agent's behaviour to the CTO.
+3. **Publish path:** `pending/` → `approved/` → a human places it on
+   nook.freno.me (blog route). Nothing posts itself.
+
+## Ban compliance (FRE-199 + positioning.md rule 1)
+
+- The Nook: not named; notch/island/companion not mentioned.
+- Competitors: not named — including the agent vendor's remote feature, which
+  the page never needs to mention because it stays on the at-the-machine half.
+- Claude Code is named only as the subject whose documented permission system
+  the page explains, with its own docs as the source — same status the
+  listening phrase list already gives it.
+- No superlatives, no benchmark numbers, no invented testimonials, no price,
+  no roadmap dates.
+
+## Cadence note
+
+Second page of the first pair. Queue behind it: multi-agent tracking ("How do
+you keep track of multiple coding agents running in parallel?", 1xm6frp,
+2026-11-03) and the invisible-permission cluster — the queue holds above the
+three-candidate floor, so the two-a-week cadence holds.

marketing/briefs/registry-wave-2.md

@@ -0,0 +1,91 @@
+# Registry wave 2 — brief and copy (FRE-199 item 3)
+
+**Owner:** CMO prepares · sponsor submits · **Copy ready 2026-11-05** (target was
+Fri 2026-11-13) · **Submit:** week of 2026-11-16, after the wave-1 readback.
+**Status:** `briefs/` — nothing here has been posted; humans hold every account;
+no agent authenticates, posts or sends.
+
+## What wave 2 is, and what it waits for
+
+Wave 1 is FRE-207's packet (`The-Nook` worktree `drafts/directory-submissions.md`
++ `drafts/click-list.md`): 8 targets, CTO claim verdict applied 2026-11-01
+(C1–C5 signed, C7 refused → relay sentence), sponsor-owned inputs G2 (price
+line), G3 (`@freno.me` mailbox), G4 (screenshots). **Wave-2 submission waits on
+the wave-1 readback** — what actually got submitted, what got listed, what was
+rejected and why — so targets can be re-ranked on evidence instead of guesswork.
+The readback lives on the FRE-207 issue; this brief is ready either way.
+
+**Copy rule inherited from wave 1:** paste the wave-1 blocks, do not improvise.
+Only claims signed by the CTO verdict ship:
+
+- C1 — works with 18 coding agents (compatibility fact, not a competitor mention).
+- C2 — answer an agent's approval from your Mac, iPhone or Watch.
+- C3 — sessions keep arriving while the Mac app is closed (widgets; fleet status only).
+- C4 — macOS 14.2+, universal.
+- C5 — iPhone/iPad and Apple Watch companions are **TestFlight beta**; no App Store link anywhere.
+- C7 — "no cloud service of its own" is refused; block D ships the relay sentence.
+- **Price line (G2):** "Free 14-day trial" only — no number — until CoS + sponsor
+  clear the "$10 one-time licence" line for public listings (FRE-204 holds $10 in-app;
+  the listing text is a separate publish decision).
+- Banned: superlatives, user counts, testimonials, competitor names.
+
+## Targets — fetched live 2026-11-05, marked per the wave-1 legend
+
+| # | Target | What it is | How it ships | Fit | Verified |
+|---|---|---|---|---|---|
+| W2-1 | `iCHAIT/awesome-macOS` (19.4k ★) | Curated macOS app list; PR-based | PR adding one line to the relevant section from `contributing.md`; copy: block A + block B compressed | High — category fit, persistent link | ✅ repo + contributing rules read 2026-11-05 |
+| W2-2 | 1000.tools | Curated tool directory, self-serve categories (AI, developer tools, productivity) | Category submission form; copy: block A + B | Medium-high | ✅ fetched 2026-11-05 (categories listed on page) |
+| W2-3 | uneed.best | Daily product launch site | Launch submission (account needed, held by a human) | Medium — launch-format, needs assets | ✅ fetched 2026-11-05 |
+| W2-4 | devhunt.org | Daily dev-tool launches | Launch submission | Medium | ✅ fetched 2026-11-05 |
+| W2-5 | Product Hunt | Launch site | Maker/hunter flow, on-screen (403 to plain fetch — read live before filing) | Low-medium this wave; big-audience launch usually wants FRE-203's launch-day coordination | ⚠️ bot-walled; fields read on screen |
+
+Re-rank after the wave-1 readback: if directory listings (wave-1 §1/§3–5)
+produced traffic or referrers, wave 2 leads with W2-1/W2-2; if nothing was
+submittable, wave 2 waits until G3/G4 clear rather than submitting half-copy.
+
+## Copy — paste-ready, inheriting the signed claims only
+
+**One-liner (≤60):** `Your coding agents, at the edge of the screen` (43 chars — wave-1 block A).
+
+**Short description (~250 chars):** wave-1 block B verbatim; if a field forces a
+price, "Free 14-day trial" and no number (G2).
+
+**awesome-macOS PR line (one row, section: menu-bar / status-bar apps or the
+section the maintainers route notch apps to — read the README section headers
+before filing):**
+
+```
+- [The Nook](https://nook.freno.me/) - Puts every coding-agent session at the
+  edge of your screen and lets you answer approvals from your Mac, iPhone or
+  Watch. Works with 18 coding agents. [![Open-Source Software][OSS Icon]] — not
+  open source; omit the badge row, keep the description.
+```
+
+(The badge syntax is copied from the list's own rows; The Nook is not open
+source, so the OSS badge is **omitted** — the line above shows the shape only.
+No TestFlight mention needed in a one-row listing; add "Companions for iPhone
+and Apple Watch (TestFlight beta)" only if the PR reviewer asks for platform
+detail — C5 wording.)
+
+**Launch-site fields (W2-3/W2-4):** wave-1 blocks A, B, C (widgets — fleet
+status only), D (relay sentence, not C7's refused wording). Gallery needs G4's
+three real screenshots.
+
+## Gates before anything here is submitted
+
+| Gate | Owner | State |
+|---|---|---|
+| Wave-1 readback recorded (what submitted/listed/rejected) | sponsor → FRE-207 issue, carried to FRE-199 | owed before submission week |
+| G2 price line for public listings | CoS + sponsor | pending (copy ships without a number either way) |
+| G3 `hello@freno.me` mailbox | sponsor | pending |
+| G4 three real screenshots + logo PNG | sponsor or CTO | pending — blocks every upload field |
+| Claim sign-off | CTO | **cleared 2026-10-31** for C1–C5; C7 ships as the relay sentence |
+
+## Provenance
+
+- Targets fetched 2026-11-05: uneed.best, devhunt.org, 1000.tools (HTTP 200,
+  content read); `iCHAIT/awesome-macOS` via GitHub API (19,441 stars,
+  contributing.md linked from README); producthunt.com returns 403 to a plain
+  fetch — marked ⚠️, read on screen before filing.
+- All claims inherited from FRE-207's CTO verdict of 2026-10-31 — no new
+  claims introduced by this brief.

marketing/drafts/agent-keeps-asking/copy.md

@@ -0,0 +1,96 @@
+# Why does your coding agent keep stopping to ask you questions?
+
+> **Status: draft — awaiting sponsor fact-check** (FRE-199 pair 3, internal target
+> Thu 2026-11-12). Not publishable from `drafts/`.
+> This page never names a product of ours and never names a competitor.
+
+Most of the stopping is not the model being chatty — it is the permission system
+doing what it was told. In the default mode, the agent prompts before the first
+use of each tool; separately, its turn ends every time it finishes responding,
+and ending a turn with a question is finishing a turn. You cannot and should not
+eliminate every ask — but you can decide, once, which asks deserve an
+interruption and let the routine ones pass without you.
+
+## Where the asks come from
+
+**Permission gates.** In the default mode the agent "prompts for permission on
+first use of each tool" — so every new tool, and often every new command shape,
+costs one prompt. The configuration decides who answers:
+
+- **`acceptEdits`** automatically accepts file edits and common filesystem
+  commands (like `mkdir`, `touch`, `mv`, `cp`) for paths in your working
+  directory — the single biggest ask category for most coding sessions, gone.
+- **Permission rules** do the fine work: `deny` rules block a tool outright,
+  `allow` rules pass it silently, `ask` rules force the prompt. Order matters:
+  rules are evaluated deny, then ask, then allow — the first match wins, and an
+  allow rule cannot carve an exception out of a deny.
+- **Modes set the floor.** `defaultMode` in your settings picks where every new
+  session starts. At the far end, `bypassPermissions` skips prompts entirely —
+  the docs' own warning is that it belongs only in isolated environments like
+  containers or VMs.
+
+One fact worth internalising: permission rules are enforced by the coding
+agent's harness, not by the model. A line in your prompt asking it to "not ask"
+changes nothing about what it is allowed to do — the configuration is the only
+lever.
+
+**Turn ends.** A `Stop` hook fires when the agent finishes responding — every
+turn, including the turns that end in a question. From the terminal's side of
+the glass, "it finished", "it's asking me something" and "it's waiting on a
+permission prompt" are the same silence. That is why the asking *feels*
+endless: each ask costs a context switch, and nothing distinguishes the asks
+from the completions.
+
+Practitioners describe the pattern in their own words. A developer who measured
+why their sessions kept stopping found that the agent "just kept handing
+control back" even with a permissive mode already on — the model's own habit of
+ending turns to stay in the loop, on top of the permission asks. An operator
+running a team of agents with per-agent autonomy levels put the other side:
+"if every decision routes through you, you're the bottleneck agents were meant
+to eliminate."
+
+## What to check or do
+
+1. **Sort the asks by kind before touching anything.** File edits in your
+   working directory: `acceptEdits` removes them wholesale. The same safe
+   command every session: an `allow` rule. The commands that must never run: a
+   `deny` rule. What is left is the set of questions only you can answer.
+2. **Write the rules in the right order.** Deny, then ask, then allow; first
+   match wins. A broad deny stays broad — narrowing an allow elsewhere does not
+   soften it.
+3. **Keep the genuinely ambiguous asks.** A mode that asks less is not a mode
+   that asks smarter. `bypassPermissions` in a throwaway container is a
+   documented pattern for unattended runs; using it on your daily machine is
+   the docs' own caution, not a recommendation.
+4. **Make every stop visible.** Because every stop ends a turn, wire the
+   turn-end and notification moments (the `Stop` and `Notification` hooks) so
+   an ask reaches you where you actually are — and a permission wait is
+   distinguishable from a finished job.
+
+One next step: run one session with the asks tallied by kind — edits, known
+commands, everything else. The first two usually turn out to be rules you
+hadn't written yet; the third is the work.
+
+---
+
+## Fact-check table (not part of the page)
+
+Every technical claim above, with its primary source. Claims about the
+permission system and hooks were verified against the live docs on 2026-11-05.
+
+| # | Claim in the page | Source |
+|---|---|---|
+| 1 | Default mode "prompts for permission on first use of each tool" (labeled Manual; `manual` alias) | Claude Code permissions doc — https://code.claude.com/docs/en/permissions (permission modes table; fetched 2026-11-05) |
+| 2 | `acceptEdits` "automatically accepts file edits and common filesystem commands such as mkdir, touch, mv, and cp for paths in the working directory or additionalDirectories" | same page (permission modes table) |
+| 3 | Rules are evaluated in order deny, then ask, then allow; "the first match in that order determines the outcome"; "an allow rule can't carve an exception out of a deny rule" | same page (rule precedence section) |
+| 4 | `bypassPermissions` "skips permission prompts"; docs' caution: "Only use this mode in isolated environments like containers or VMs where Claude Code can't cause damage" | same page (permission modes table) |
+| 5 | `defaultMode` in settings files sets the default permission mode for new sessions | same page ("To change the default permission mode for new sessions, set defaultMode in your settings files") |
+| 6 | "Permission rules are enforced by Claude Code, not by the model. Instructions in your prompt or CLAUDE.md shape what Claude tries to do, but they don't change what Claude Code allows." | same page (verbatim) |
+| 7 | `Stop` fires when the agent finishes responding; hook cadence is per turn | Claude Code hooks reference — https://code.claude.com/docs/en/hooks (verified 2026-11-05 in FRE-199 round 1; unchanged) |
+| 8 | Anecdote: "it just kept handing control back"; sessions kept stopping with a permissive mode on | r/ClaudeCode thread 1xlfqmo ("I measured why my Claude Code sessions kept stopping…", 2026-11-01, u/belovoj), logged in `drafts/listening.md` Scan 5 #1. Quoted as one developer's described experience; the thread's own measurement figures are deliberately **not** cited. |
+| 9 | Anecdote: "if every decision routes through you, you're the bottleneck agents were meant to eliminate"; per-agent autonomy levels 0–5 | r/ClaudeCode thread 1xk0ghj ("multiple agents working on multiple projects", 2026-10-31, quote by u/iceydee), logged in `drafts/listening.md` Scan 4 #2. One operator's described practice. |
+
+**Ban compliance:** no product of ours named · no competitor named · no
+superlatives · no benchmark numbers (the 1xlfqmo poster's measurement figures
+are deliberately not cited) · no invented testimonials (anecdotes are real
+threads, described without handles) · no price · no roadmap dates.

marketing/drafts/agent-keeps-asking/rationale.md

@@ -0,0 +1,52 @@
+# Rationale — "Why does your coding agent keep stopping to ask you questions?"
+
+FRE-199 item 1, page 2 of the third pair. Drafted 2026-11-06 by CMO (internal
+target Thu 2026-11-12 — six days early).
+
+## The phrase
+
+Primary: **"why does my coding agent keep stopping to ask me questions"**
+(variants: "agent keeps handing control back", "claude code keeps asking for
+permission"). The H1 carries the generic form; "handing control back" is the
+backlog's own added phrase (Scan 5's phrase-list finding).
+
+## Why this phrase won the slot
+
+- **Backlog evidence.** r/ClaudeCode 1xlfqmo (2026-11-01, Scan 5 #1): "Auto mode
+  was already on, so permissions weren't the issue… it just kept handing
+  control back"; "the model was forcably trying to keep me in the loop." The
+  phrase-list finding from the same scan added "handing control back" as a
+  standing query. Corroborated by 1xlxw0q (turns ending with "nothing yet") and
+  the autonomy-ladder operator (Scan 4 #2, thread 1xk0ghj: "if every decision
+  routes through you, you're the bottleneck agents were meant to eliminate").
+- **Shortlist position (c)** in the plan's pair-3 shortlist, recorded at
+  revision 5 — the page extends the done-signal cluster (pair 1) with the
+  handback half. The distinction is kept deliberately: *agent-done-signal*
+  owns "how do I know it's done"; this page owns "why does it keep stopping on
+  me". Different question, different searcher.
+- **Answerable honestly from verified sources only.** Every mechanism claim
+  re-reads to the permissions doc and hooks reference — the same pages and the
+  same claims the CTO verified in FRE-199 rounds 1–2 (mode ladder, precedence,
+  acceptEdits scope, enforced-by-harness sentence, Stop cadence). Nothing new
+  is asserted about agent behaviour.
+
+## What the page deliberately does not do
+
+- **Does not cite the 1xlfqmo poster's measurement figures** (the 28-of-73
+  sample is the poster's own 18-day data, and the backlog row carries an
+  explicit do-not-cite flag). The anecdote is quoted as experience, not
+  measurement, and the fact-check table says so.
+- Does not promise the asks can be eliminated. The honest answer is that the
+  asking is partly the permission system working as configured and partly the
+  agent ending turns to stay in the loop — the page sorts which is which.
+- Does not touch environment contention (page 1 of this pair owns that half).
+
+## Evidence trail
+
+| Thread | Date | What it showed |
+|---|---|---|
+| r/ClaudeCode 1xlfqmo — "I measured why my Claude Code sessions kept stopping" | 2026-11-01 | "It just kept handing control back" with a permissive mode on; "forcibly trying to keep me in the loop" — the model-behaviour half |
+| r/ClaudeCode 1xk0ghj — "multiple agents working on multiple projects" (quote by u/iceydee) | 2026-10-31 | "If every decision routes through you, you're the bottleneck agents were meant to eliminate"; per-agent autonomy levels 0–5 — the configuration half |
+| r/ClaudeAI 1xlxw0q — "2,300 hours waiting" | 2026-11-02 | Turns ending in a one-word answer reload context each time — the per-ask cost, corroborating |
+
+All rows live in `drafts/listening.md` (The-Nook local master line).

marketing/drafts/agent-worktree-contention/copy.md

@@ -0,0 +1,72 @@
+# How do you manage worktrees when your agents end up waiting on each other?
+
+> **Status: draft — awaiting sponsor fact-check** (FRE-199 pair 3, internal target
+> Thu 2026-11-12). Not publishable from `drafts/`.
+> This page never names a product of ours and never names a competitor.
+
+Usually, the worktrees are not what your agents are waiting on — the environment
+they share is. Two agents can sit in two worktrees of the same repo and still
+queue up behind one dev server, one test database, one `docker compose` stack.
+The fix that scales is to multiply the environment per worktree, not to
+orchestrate the waiting.
+
+## Why agents queue when the code doesn't
+
+Git supports parallel work out of the box: `git worktree add <path> <branch>`
+creates a second working directory linked to the same repository — shared
+history, but its own HEAD, its own index, its own checked-out branch. Git even
+enforces the ownership half for you: it refuses to check out a branch into a
+second worktree while the first one holds it.
+
+What git does not duplicate is everything the repo only *points at*: the dev
+server bound to port 3000, the database named after the project directory, the
+compose stack whose project name defaults to the folder you launched it from.
+Two agents in two worktrees that both bring up the same stack are two agents
+contending for one environment — and the queue looks like a worktree problem
+when it is an environment problem.
+
+Practitioners who hit this converge on the same verdict. One, in a thread
+asking this exact question: the queue "comes from having one test env, so I'd
+multiply the env instead of orchestrating the waiting."
+
+## What to check or do
+
+1. **Give every worktree its own copy of the stack.** Docker Compose exists for
+   exactly this: it uses a *project name* to isolate environments from each
+   other, and names "multiple copies of a single environment, useful for
+   running stable copies for each feature branch" as a use case. Set a unique
+   one per worktree — the `-p` flag has top precedence, or use `name:` in the
+   compose file — and the port and container-name collisions disappear.
+2. **Anything that cannot be multiplied, serialise on purpose.** One migration
+   runner, one deploy target, one flaky hardware-in-the-loop device: put it
+   behind a single serial step rather than letting two agents race it. A queue
+   you chose is a queue you can reason about.
+3. **One branch, one worktree.** Git already refuses to check out the same
+   branch in two worktrees; keep it that way. Two agents on one branch is a
+   merge conflict waiting for both of them to finish.
+4. **Remember a fresh worktree starts unconfigured.** Env files, generated
+   config and installed dependencies live in the worktree, not the repo — a new
+   worktree is a new environment to set up, which is exactly why the per-worktree
+   copy should be scripted, not hand-arranged.
+
+One next step: find the resource your agents contend for most often — usually
+the test stack — and give it a per-worktree project name. The waiting usually
+resolves before any queueing tool is needed.
+
+---
+
+## Fact-check table (not part of the page)
+
+Every technical claim above, with its primary source. Claims about git and
+Docker Compose were verified against the live docs on 2026-11-05.
+
+| # | Claim in the page | Source |
+|---|---|---|
+| 1 | `git worktree add <path> [<commit-ish>]` creates a worktree "linked to the current repository, sharing everything except per-worktree files such as HEAD, index, etc." | git worktree docs — https://git-scm.com/docs/git-worktree (COMMANDS › add; fetched 2026-11-05) |
+| 2 | `add` "refuses to create a new worktree when <commit-ish> is a branch name and is already checked out by another worktree" | same page (OPTIONS › `--force`) |
+| 3 | Compose "uses a project name to isolate environments from each other"; "multiple copies of a single environment, useful for running stable copies for each feature branch" is a named use case; precedence: `-p` flag > `COMPOSE_PROJECT_NAME` > `name:` attribute > directory basename | Docker Compose docs, "Specify a project name" — https://docs.docker.com/compose/how-tos/project-name/ (fetched 2026-11-05) |
+| 4 | Anecdote: "The queue comes from having one test env, so I'd multiply the env instead of orchestrating the waiting" | r/ClaudeCode thread 1xlz2bs ("How do you manage worktrees when your agents end up waiting on each other?", 2026-11-02, u/Roland_culait / u/First-Painter7431), logged in `drafts/listening.md` Scan 6 #4. Quoted as one commenter's described practice, not a measurement. |
+
+**Ban compliance:** no product of ours named · no competitor named · no
+superlatives · no benchmark numbers · no invented testimonials (the anecdote is
+a real thread, described without handles) · no price · no roadmap dates.

marketing/drafts/agent-worktree-contention/rationale.md

@@ -0,0 +1,46 @@
+# Rationale — "How do you manage worktrees when your agents end up waiting on each other?"
+
+FRE-199 item 1, page 1 of the third pair. Drafted 2026-11-06 by CMO (internal
+target Thu 2026-11-12 — six days early).
+
+## The phrase
+
+Primary: **"how do you manage worktrees when your agents end up waiting on each
+other"** — carried verbatim as the H1, because it is already a complete search
+phrase with the exact buying intent.
+
+## Why this phrase won the slot
+
+- **Backlog evidence.** r/ClaudeCode 1xlz2bs (2026-11-02, ~15 h old at scan time,
+  Scan 6 #4). The OP asked the question in its final words; the thread answered
+  itself (env per worktree, `docker compose -p`, preview deploys, one serial
+  step on main) — which is exactly what makes it page material: the demand is
+  proven, the answer is proven, and the answer is generic.
+- **Shortlist position (a)** in the plan's pair-3 shortlist, recorded at
+  revision 5. Scan 9 (2026-11-05) produced no new queue item, so the
+  shortlist stands; selection finalised against that fresh scan as planned.
+- **Answerable honestly and generically.** Both mechanisms are documented
+  primary sources (git worktree docs; Docker Compose project-name docs), both
+  fetched and read 2026-11-05. No agent-behaviour claim is needed — this page
+  is the lightest CTO-review lift of the shortlist.
+- **Wedge-adjacent without a mention.** "Waiting" is the cost our wedge names
+  ("an agent blocked is the most expensive kind of idle"); this page owns the
+  agent-on-agent half of waiting, which no existing page covers.
+
+## What the page deliberately does not do
+
+- Does not cite the thread's own tooling (Orca, oyren.ai) or any workflow
+  product — category nouns only.
+- Does not invent a measurement. The one quoted line is a commenter's described
+  practice, logged in the backlog with a do-not-interpret flag.
+- Does not touch the approval surface (page 2 of this pair owns the
+  attention/handback half; this page is environment contention only).
+
+## Evidence trail
+
+| Thread | Date | What it showed |
+|---|---|---|
+| r/ClaudeCode 1xlz2bs — "How do you manage worktrees when your agents end up waiting on each other?" | 2026-11-02 | Exact phrase in the wild; self-answered with env-multiplication advice; "multiply the env instead of orchestrating the waiting" |
+| Watched-table corroboration (Scans 5–9) | 2026-11-02 → 11-05 | Repobs ("which sessions were waiting for me"), Orca (worktree orchestration daily driver), Worktrunk, Conductor.build, Parallel Code — a shelf of builders around the same phrase; the demand is broad |
+
+All rows live in `drafts/listening.md` (The-Nook local master line).

marketing/drafts/faq-from-objections.md

@@ -1,478 +0,0 @@
-# `/faq` from the objections we already have
-
-**Date:** 2026-10-29 · **Owner:** CMO · **Status:** CTO-verified (FRE-329) and CoS-decided (FRE-334, option A: withdraw both) on 2026-10-29; **awaiting the sponsor's publish approval** — not approved, not published · **Source issue:** FRE-326
-**Page:** `nook.freno.me/faq` · **Page source:** `freno-dev/src/routes/nook/faq.tsx` · **Site commit read:** `c1c498e` (branch `faq/from-objections-2026-10-29`, unmerged)
-**Product commit read:** The-Nook `f9cbd879` — the exact revision the CTO verified against (0.13.4, build 37)
-
-Every entry below is traceable to a real question or a real report. Nothing is invented to fill a
-category. No testimonial is used. No price, refund term, or umbrella/cross-promotion answer appears
-here — those stay with FRE-204, the Chief of Staff and the sponsor.
-
----
-
-## 1. What I could read, and what I could not
-
-| Source | What it is | Read on | What it yielded |
-|---|---|---|---|
-| `nook.freno.me/faq` | The live page | 2026-10-29 | Six questions already published: privacy, notch, battery, permissions, macOS 14.2, offline. |
-| FRE-326 description | This board issue | 2026-10-29 | Two purchase-blocking questions named verbatim: *"does it work with Cursor?"* and *"what happens when my agent is idle?"* |
-| NOOK issue corpus | 948 issues imported from Plane, plus the 324-issue Paperclip board | 2026-10-08 → 2026-10-28 | User-observable defect reports. These are reports, not captured asks; they prove an objection is live. |
-| `freno-dev/marketing/positioning.md` | Voice, approved claims, competitor ban | 2026-10-29 | The register and the "never name a competitor" rule. |
-| The-Nook code | `AgentRegistry.swift`, `SessionModels.swift`, `Terminal*`, `hook/setup.go`, `PluginInstaller.swift`, `LicenseService.swift`, `main.swift` | 2026-10-29 | The technical facts each answer is allowed to use. |
-| NOOK-121 | The original `/faq` creation (2026-10-08) | 2026-10-29 | Confirms the six live questions came from the strategy's named objections, not from a support corpus. Refund was deliberately dropped by Mike. |
-
-### The gap that shapes this draft
-
-**Support mail is not readable from this run.** There is no mailbox on the machine; the in-app
-"Report a bug" form `POST`s to `freno-dev/src/routes/api/the-nook/report.ts`, which emails the
-developer and stores nothing queryable. `/privacy` and the repo contain no support corpus.
-
-**Reply threads are not collected.** `freno-dev/marketing/listening.md` is an empty table; FRE-201
-(the listening job) has not produced a thread yet.
-
-**Directory comments do not exist yet.** FRE-207 has a submission packet, not live listings; none of
-the directories has a comment thread about The Nook to mine.
-
-**Consequence:** I cannot rank by observed ask frequency, because no ask corpus exists. What follows
-ranks by **purchase-blocking weight first**, then by **the number of named reports in our own issue
-corpus that belong to the cluster**. The report counts are a proxy for "this objection is live", not
-a count of people who asked. I have not put a percentage on anything.
-
----
-
-## 2. The register — clusters, sources, frequency, and whether they block a purchase
-
-| # | Cluster | The question in the buyer's words | Verbatim source(s), with dates | Frequency evidence | Blocks a purchase? | Disposition |
-|---|---|---|---|---|---|---|
-| 1 | Privacy / what leaves the Mac | "Does The Nook read my prompts or my code?" | Live `/faq`, 2026-10-29; code findings in `main.swift:272-278`, `LicenseService.swift:254`, `docs/sidecar-frames.md` | 1 live question + 3 named code findings | **Yes — the whole decision for this audience** | **Withdraw the live answer; replacement held.** See §4. |
-| 2 | Agent fit / Cursor | "Does it work with Cursor — and can I approve from the notch, or only watch?" | FRE-326, 2026-10-29: *"does it work with Cursor?"*; NOOK-643 (2026-10-20), NOOK-695 (2026-10-20), NOOK-699 (2026-10-20), NOOK-707 (2026-10-21), NOOK-638 (2026-10-20) | 1 board question + 5 reports | **Yes** | **Propose E1** |
-| 3 | Idle / is it actually working? | "What happens when my agent is idle?" | FRE-326, 2026-10-29: *"what happens when my agent is idle?"*; NOOK-281 (2026-10-12), NOOK-415 (2026-10-15), NOOK-417 (2026-10-15), NOOK-823 (2026-10-22), NOOK-898 (2026-10-23) | 1 board question + 5 reports | **Yes** | **Propose E2** |
-| 4 | Install trust / permissions | "What permissions does it need — and what does it write into my agent's config?" | Live `/faq`, 2026-10-29; NOOK-733 (2026-10-21), NOOK-648 (2026-10-20), NOOK-685 (2026-10-20), NOOK-418 (2026-10-15), NOOK-568 (2026-10-17) | 1 live question + 5 reports | **Yes** | **Propose E3** |
-| 5 | Terminal / tmux fit | "Does it work with my terminal, including tmux?" | NOOK-302 (2026-10-13), NOOK-310 (2026-10-13), NOOK-788 (2026-10-22) | 3 reports; no captured ask | **Yes for tmux-first buyers** | **Propose E4** — report-sourced, not an ask |
-| 6 | Notch / display | “Do I need a Mac with a notch?” | Live `/faq`, 2026-10-29; NOOK-290 (2026-10-12), NOOK-291 (2026-10-12), NOOK-386 (2026-10-14) | 1 live question + 3 reports | Compatibility; rarely the blocker | **Rewrite E5** — the pointer-display sentence was never true |
-| 7 | Battery / cost | "How much battery does it cost?" | Live `/faq`, 2026-10-29; NOOK-850 (2026-10-23), NOOK-851 (2026-10-23), NOOK-877 (2026-10-23) | 1 live question + 3 reports | Curious, not a hard blocker | **Rewrite E6 without a number** |
-| 8 | macOS floor | "Why macOS 14.2 or later?" | Live `/faq`, 2026-10-29; NOOK-881 (2026-10-23) | 1 live question + 1 report | Compatibility; a hard no on 14.0/14.1 | **Keep current answer** |
-| 9 | Offline | "Does it work offline?" | Live `/faq`, 2026-10-29; NOOK-494 (2026-10-16) | 1 live question + 1 report | Compatibility; a hard no for offline-only | **Rewrite E8 for the phone exception** |
-| 10 | Trial / licence mechanics | "What am I actually buying — trial, Macs, updates?" | NOOK-682 (2026-10-20), NOOK-684 (2026-10-20), NOOK-60 (2026-10-08) | 2 reports; no captured ask | **Yes** | **Held** — no verbatim ask; do not invent one |
-| 11 | Remote agents / containers | "Can I approve an agent running on a remote box or in Docker?" | FRE-323, FRE-320, FRE-315; `marketing/positioning.md` claims remote SSH | Many reports; the claim is unverified | **Yes — the launch claim** | **Held** — no answer before the demo |
-| 12 | Phone / Watch | "Is there an iPhone app? Do I need one?" | NOOK-939 (2026-10-27), NOOK-294 (backlog) | 2 reports; status unverified | Curious; would be blocking if sold | **Held** — CTO status answer first |
-| 13 | Refund / price | "What's your refund policy? Is $10 the real price?" | FRE-204, NOOK-121 | No readable source; contractual | **Yes** | **Out of scope** — FRE-204, CoS + sponsor |
-
-### What changed since the last register (FRE-204)
-
-- The live page already has six entries; this draft **keeps one** (macOS 14.2), **rewrites four**
-  (permissions, battery, offline, and notch — whose pointer-display sentence the CTO found was never
-  true), **withdraws one** (privacy), and **proposes three new ones** (E1, E2, E4). It does not re-ask
-  the six questions as if they were new.
-- The privacy answer is not merely unverified — it is **false at the current build**. It must come
-  down in the same edit, not wait for a nicer replacement.
-- Cursor is now a supported agent row (`AgentRegistry.swift:524`), so "does it work with Cursor?"
-  has a factual answer today. It was an open question when the live page was written.
-
-### CTO verdict (FRE-329, 2026-10-29)
-
-The CTO read The-Nook `f9cbd879`, the site at `c1c498e` and the live page, and checked every entry
-against the code. **No entry is cut.** Six change text, exactly as below; E1 and E7 ship as written.
-
-| Entry | Verdict | What changed in this revision |
-|---|---|---|
-| E1 Agent fit / Cursor | **verified** | nothing |
-| E2 Idle | verified, one sentence tightened | the row-eviction sentence |
-| E3 Permissions / config | **not verified** | three sentences: Login Items toggle, per-event entries, `~/.nook` |
-| E4 Terminal / tmux | **not verified** | one sentence: which terminals take a typed reply |
-| E5 Notch | **not verified** | one sentence: one island per enabled display, not the pointer's display |
-| E6 Battery | verified, one clause tightened | "never runs them in the background" |
-| E7 macOS 14.2 | **verified** | nothing |
-| E8 Offline | **not verified** | one sentence, plus a six-row network list in its gate |
-| §4 privacy | all three findings confirmed; withdrawal is right | `positioning.md` rule 3 comes down in the same change |
-
-The verdict adds two things to the plan, both now in §4 and §7: the false claim's **source rule** in
-`marketing/positioning.md` — rule 3 and its approved-claims row — must be struck in the same change
-as the withdrawal, or the next page restates it; and the egress inventory's scope widens to cover
-weather, the network panel, the speed test, the changelog, the bug report and Sparkle, plus Sentry's
-`sendDefaultPii` and trace sample rate.
-
-The verdict's full text and its per-sentence evidence is
-[FRE-329's `faq-verdict` document](/FRE/issues/FRE-329#document-faq-verdict). Nothing in it is
-reproduced here as a new claim; the entry text below is the verdict's own replacement wording, except
-E4, where I took the verdict's first option (keep the Alacritty clause) and narrowed the jump
-sentence, which the verdict itself notes is `open -b` for three of the seven names.
-
----
-
-## 3. Proposed entries — page-ready
-
-Each entry carries the six required things: **claim, audience, channel, owner, date, and what has to
-be true before it ships.** The answer text is the copy to paste; the trace is the evidence a CTO can
-check.
-
-### E1 · "Does it work with my agent — and can I approve from the notch, or only watch?"
-
-> **It depends on the agent, and Cursor is the useful example.** Cursor is watched, not gated: its
-> sessions, finished turns and errors appear in the island, but when Cursor asks for permission the
-> prompt stays in Cursor. That is deliberate — Cursor blocks the action when a permission hook runs
-> and prints nothing, so gating it would override Cursor's own prompts. Other agents do hand the
-> decision to The Nook, so a tool call waits and you tap Allow or Deny from the card. One limit:
-> `cursor-agent -p` one-shot runs send no turn end, so they appear but do not get a completion card.
-
-- **Question source:** FRE-326, 2026-10-29 (*"does it work with Cursor?"*); NOOK-643, 2026-10-20
-  (*"No permission hook is installed, deliberately: Cursor blocks the action when a permission hook
-  prints nothing…"*).
-- **Claim:** agent gating is per-agent; Cursor is watch-only.
-- **Audience:** the buyer whose agent is not Claude Code.
-- **Channel:** `/faq`. No FAQ structured data in this pass — see §6.
-- **Owner:** CMO writes; CTO verified 2026-10-29.
-- **Date:** CTO verified 2026-10-29 ([FRE-329](/FRE/issues/FRE-329)); publish on approval, target 2026-11-05.
-- **Must be true:** at the shipped commit, Cursor still reads `.missing(.approvals)` with the same
-  reason, and `.available(.sessions)`, `.available(.completion)` and `.available(.errors)` as stated
-  (`AgentRegistry.swift:523-555`, which is where the CTO read it). The separate `/agents` page is
-  incomplete for Cursor and the other newer rows; that is a page correction, not a gate for this
-  self-contained answer.
-
-### E2 · "What happens when my agent is idle?"
-
-> **Idle means the last turn is over, or the session has not produced anything yet — not that the
-> process is gone.** A running process is liveness, not work: a just-opened agent window can show
-> idle until you type. When an agent finishes a turn with a final message, the row stays green for
-> ten minutes, then goes gray. A stale row is different: it means The Nook's integration cannot
-> report for that session, and the row says so instead of pretending it is idle. Nothing is lost when
-> a row goes idle — the next prompt brings it back and flips it to running. The row itself leaves the
-> island 15 minutes after the turn (5 if the turn ended without a reply), so a long-quiet session
-> reappears on its next event instead of sitting there. If a session that is obviously working says
-> idle, that is a bug; tell us.
-
-- **Question source:** FRE-326, 2026-10-29 (*"what happens when my agent is idle?"*); NOOK-898,
-  2026-10-23 (*"kimi payloads fail to decode, so every Kimi session stays idle"*); NOOK-823,
-  2026-10-22 (*"Codex terminal: sessions become idle or disappear prematurely"*); NOOK-417,
-  2026-10-15 (*"Never render plain Idle for a session whose integration is dark"*).
-- **Claim:** idle is a statement about the last turn, not a guess at the process; stale is a separate
-  state.
-- **Audience:** anyone watching a fleet and wondering whether to intervene.
-- **Channel:** `/faq`.
-- **Owner:** CMO writes; CTO verified 2026-10-29.
-- **Date:** CTO verified 2026-10-29 ([FRE-329](/FRE/issues/FRE-329)); publish on approval, target 2026-11-05.
-- **Must be true:** `SessionModels.swift:511,552,564-577` still defines `islandStatus` this way (no
-  content → idle; complete → ready for 10 minutes → idle; `integrationStale` → stale) and
-  `SessionState.swift:35,40` still evicts a finished turn after 15 minutes, 5 when it ended without a
-  reply. If an open bug makes a working agent render idle at the shipped commit, the "that is a bug"
-  sentence stays but the bug gets a named issue.
-
-### E3 · "What permissions does it need — and what does it write into my agent's config?"
-
-> **The app itself runs unprivileged.** Fan control and charge limiting go through a small helper
-> that macOS requires to run as root for hardware access; the app registers it on first use and takes
-> you to System Settings › General › Login Items & Extensions, where you switch it on once. For each
-> agent it adds what that agent needs — a hook group per event it listens to, or one plugin link —
-> inside the agent's own config file or directory. It keeps its own files under `~/.nook` — the hook
-> binary and one plugin copy per agent — and adds only its own entries to that agent's config. A hook
-> entry you added yourself in the same file survives install and uninstall, and it only touches the
-> records and switches it created. Uninstall removes exactly what it wrote — and switches off what it
-> turned on — with no leftover links or orphaned files.
-
-- **Question source:** live `/faq`, 2026-10-29 (*"What permissions does it need?"*); NOOK-418,
-  2026-10-15 (a custom agent's install target is never shown to the user); NOOK-733, 2026-10-21 (a
-  Codex hook installed but not trusted, so it never ran); NOOK-648, 2026-10-20 and NOOK-685,
-  2026-10-20 (uninstall leftovers); NOOK-568, 2026-10-17 (helper re-registration tore down an
-  approved helper).
-- **Claim:** reversible install; the helper is the only root step; uninstall is exact.
-- **Audience:** the buyer who has a hand-tuned `~/.claude/settings.json` or `~/.codex/hooks.json`.
-- **Channel:** `/faq`.
-- **Owner:** CMO writes; CTO verified 2026-10-29.
-- **Date:** CTO verified 2026-10-29 ([FRE-329](/FRE/issues/FRE-329)); publish on approval, target 2026-11-05.
-- **Must be true:** `hook/setup.go`'s strip functions and `PluginInstaller.uninstall` still remove
-  only their own records at the shipped commit (`removeIfOurs`, `stripOurGroups`/`groupIsOurs`); the
-  helper is still registered through `SMAppService.daemon` with a Login Items toggle and no password
-  prompt (`PrivilegedHelper.swift:62-112,204-208`); the custom-agent target is still shown and
-  accepted before install (NOOK-418); the only host switch uninstall flips is Amp's own hook-enable
-  flag (`PluginInstaller.swift:379-385`) — and the answer now says so.
-
-### E4 · "Does it work with my terminal, including tmux?"
-
-> **Yes — it recognises Terminal.app, iTerm2, Warp, Ghostty, kitty, WezTerm and tmux. Four of those
-> take a typed reply; the rest are watched.** A session is tied to the terminal that started it. Jump
-> lands in the right window for Terminal.app, iTerm2, kitty and any tmux pane — in tmux, the right
-> pane; on Warp, WezTerm and Ghostty it brings the app forward instead. Replies type straight back
-> into Terminal.app, iTerm2, kitty and any tmux pane; on Warp, WezTerm and Ghostty you answer in the
-> app's own window, and Alacritty takes no typed reply from another app at all.
-
-- **Question source:** no captured ask. Underlying reports: NOOK-302, 2026-10-13 (*"a tmux session
-  shows only 'tmux', and its outer terminal comes from whoever started the tmux server"*); NOOK-310,
-  2026-10-13 (*"jump and send address tmux panes on the default server, ignoring the session's tmux
-  socket"*).
-- **Claim:** seven terminal families and tmux panes included. Remote panes are not claimed here;
-  the remote launch story is still held.
-- **Audience:** anyone whose workflow is tmux-first.
-- **Channel:** `/faq`.
-- **Owner:** CMO writes; CTO verified 2026-10-29.
-- **Date:** CTO verified 2026-10-29 ([FRE-329](/FRE/issues/FRE-329)); publish on approval, target 2026-11-05.
-- **Must be true:** `TerminalAncestry.programs` still recognises those seven names; `TerminalSend.attempts`
-  still builds a delivery channel only for tmux, herdr, kitty, iTerm2 and Terminal.app and refuses
-  Alacritty by name; `TerminalJump` still raises the app rather than the window for Warp, WezTerm and
-  Ghostty. This entry is **report-sourced, not ask-sourced**; if a captured ask never arrives, it is
-  still publishable because the reports are real, but it ranks below E1–E3 until one does.
-
-### E5 · "Do I need a Mac with a notch?"
-
-> **No. On a notched MacBook the island sits in the notch. On machines and displays without one, it
-> sits at the top centre of the display — the same pill with the same slots.** You get one island on
-> every display it is turned on for (all connected displays on first launch), each anchored to the top
-> of its own screen; Settings › Displays trims that list, and the pointer only decides which display's
-> floating controls are live. Everything inside the island — agent cards, fan control, the stats strip
-> — works identically either way.
-
-- **Question source:** live `/faq`, 2026-10-29; NOOK-290, 2026-10-12 and NOOK-291, 2026-10-12
-  (non-notch display geometry bugs), NOOK-386, 2026-10-14 (empty pill tucks away on a non-notch
-  display).
-- **Claim:** a notch is optional; external displays work.
-- **Audience:** Mac mini / Studio / external-monitor buyers.
-- **Channel:** `/faq`.
-- **Owner:** CMO keeps the question and rewrites the answer; CTO verified 2026-10-29.
-- **Date:** CTO verified 2026-10-29 ([FRE-329](/FRE/issues/FRE-329)); publish on approval, target 2026-11-05.
-- **Must be true:** `IslandDisplayManager` still owns one island per enabled display, `DisplayStore`
-  still snapshots every connected display on first launch (`DisplayStore.swift:52-59`), and the
-  non-notch geometry tests still pass. Nothing tests that first-launch snapshot today — that is a test
-  gap to file, not a gate on this answer.
-
-### E6 · "How much battery does it cost?"
-
-> **It is a native app, not a background agent.** It watches the agents you already run and never
-> runs them in the background, so their draw is the number that matters. We do not have a published battery
-> measurement for The Nook alone; when we do, it will be a measurement, not an estimate. If it costs
-> more than it should on your Mac, that is a bug — tell us.
-
-- **Question source:** live `/faq`, 2026-10-29; NOOK-850, 2026-10-23 (*"the idle app does work
-  nothing asked for (CPU wins from a live profile)"*), NOOK-851, 2026-10-23 (a 30 fps timeline ticks
-  the fan icon at idle), NOOK-877, 2026-10-23 (compact Nook still costs too much CPU at rest).
-- **Claim:** native app, not a background agent; **no numeric battery claim**.
-- **Audience:** the buyer checking whether this is another menu-bar battery sink.
-- **Channel:** `/faq`.
-- **Owner:** CMO writes; CTO verified the no-number wording 2026-10-29.
-- **Date:** CTO verified the no-number wording 2026-10-29; publish on approval, target 2026-11-05.
-- **Must be true:** either a measurement exists and is quoted, or the no-number sentence ships. Do
-  not restore "the heaviest thing it does is a sensor read" — the profile findings above contradict
-  it.
-
-### E7 · "Why macOS 14.2 or later?"
-
-> **The audio mixer listens to each app's own sound stream, and Apple only shipped that API in macOS
-> 14.2 (Sonoma).** The app links against it, so 14.0 and 14.1 cannot launch it.
-
-- **Question source:** live `/faq`, 2026-10-29; NOOK-881, 2026-10-23 (*"A macOS 14.0/14.1 Mac cannot
-  launch the app at all: dyld dies on a strongly linked CATapDescription overlay symbol"*).
-- **Claim:** the floor is 14.2 because of the audio tap API, not a policy choice.
-- **Audience:** anyone on an older macOS.
-- **Channel:** `/faq`.
-- **Owner:** CMO keeps; CTO verified 2026-10-29.
-- **Date:** CTO verified 2026-10-29 ([FRE-329](/FRE/issues/FRE-329)); publish on approval, target 2026-11-05.
-- **Must be true:** `Package.swift:12` and `LSMinimumSystemVersion` still say 14.2, and
-  `DeploymentFloorTests` still refuses an older floor.
-
-### E8 · "Does it work offline?"
-
-> **The Mac app does.** The island, agent cards, permission cards and fan control work with no
-> network; the hooks talk to the app over a local socket. The network is used for update checks,
-> licence activation, crash reports and the optional trial email, plus a few things only when you use
-> them: weather (asked for through our relay, with the location you chose), the network panel's
-> IP-and-ISP lookup, the speed test, the changelog in Settings, and a bug report if you send one. The
-> phone link is the exception: when you are away from your Mac, the phone reaches it through our
-> relay, so that part needs a connection.
-
-- **Question source:** live `/faq`, 2026-10-29; NOOK-494, 2026-10-16 (*"iOS: the main list gives no
-  sign the phone is offline from the Mac"*).
-- **Claim:** the Mac app is offline-first; the phone link is not.
-- **Audience:** the buyer with a disconnected or privacy-sensitive setup.
-- **Channel:** `/faq`.
-- **Owner:** CMO writes; CTO verified 2026-10-29.
-- **Date:** CTO verified 2026-10-29 ([FRE-329](/FRE/issues/FRE-329)); publish on approval, target 2026-11-05.
-- **Must be true:** the only network uses at the shipped commit are the update check, licence
-  activation, crash reporting, the optional trial email and the phone relay, plus exactly these five
-  user-triggered ones — `/v1/weather` on the relay (`SidecarRelayAPI.swift:182-196`),
-  `NetworkInfoService.swift:60-88,276`, `SpeedTest.swift:36,57`, `ChangelogModel.swift:102`,
-  `BugReportClient.swift:72-94` — and `/privacy` lists the same set. This entry shares its gate with
-  the privacy correction below.
-
----
-
-## 4. The correction that is not a new entry: privacy
-
-**Live answer, quoted from `nook.freno.me/faq` on 2026-10-29:**
-
-> "No. The hooks and plugins that connect your agents to The Nook send session metadata only — which
-> agent is running, which session, which event happened, which terminal it lives in. No prompt text
-> and no code content leaves your device. Two things do leave the device, and we'd rather say so
-> plainly: anonymous usage telemetry, and your email address if you choose to give it at trial start.
-> That's the whole list."
-
-**Why it cannot stay up:** it is contradicted by the current build.
-
-1. **Sentry starts unconditionally with `sendDefaultPii = true`** (`Sources/NookApp/main.swift:272-278`).
-   That is crash and error reporting with personal identifiers, not "anonymous usage telemetry".
-2. **The licence/trial call sends `IOPlatformUUID` and the Mac's device name** (`LicenseService.swift:254`,
-   `:305`). Precision from the verdict: the identifiers ride on activation, not on every launch — a
-   licensed Mac's launch call is `/status` with the key only (`:290-295`).
-3. **With the phone link on, prompt and reply text transit `nook-relay.freno.me`, sealed end to end**
-   (`docs/sidecar-frames.md`). The relay can route the payload but cannot read it; the live answer
-   still says no prompt text leaves the device.
-
-`/privacy` discloses the hardware UUID, device name and Stripe, but **not** Sentry and **not** the
-relay. So there is no replacement sentence I can write that is both true and consistent with the
-privacy page today.
-
-**Proposed:** remove the privacy entry from `/faq` in the same edit that ships the other entries,
-rather than replace it with another sentence I cannot stand behind. The replacement is held until
-the Security Engineer's egress inventory and the `/privacy` update land.
-
-**Decided 2026-10-29 — option A, withdraw both.** The Chief of Staff ruled on
-[FRE-334](/FRE/issues/FRE-334) (`decision` document) that the `/faq` answer and `positioning.md`
-rule 3 with its approved-claims row come down **in one commit**, and that no privacy claim is written
-anywhere until FRE-333 lands and the CTO verifies it. Three consequences for the sequence below: the
-withdrawal is no longer one of the sponsor's options, it is settled company policy; the publish card
-asks one thing, publish the eight entries with the privacy answer withdrawn; and if an answer ever
-ships the seven entries with the false answer still up, that is not a variant to absorb — it stops
-and goes back to the CoS, because it would publish something the CoS has ruled out.
-
-**The rule that produced the falsehood comes down with it.** The CTO's verdict traces the live answer
-to `freno-dev/marketing/positioning.md` rule 3 (“Honest privacy scoping”) and to the matching
-approved-claims row, which state the defensible claim as “No prompt or code content leaves the
-device” with the backing “envelope carries session/event/terminal metadata only”. That backing is true
-of the hook→app envelope and says nothing about what leaves the device, so if rule 3 stands while the
-FAQ answer comes down, the next page restates the claim. Rule 3 and that row are struck in the same
-commit as this patch (§7 step 3; the same edit also fixes the stale “macOS 14+” row in that table,
-which NOOK-881 retired).
-
-- **Claim:** none until the inventory exists — deliberately.
-- **Audience:** the buyer for whom this is the whole decision.
-- **Channel:** `/faq` (withdrawal), `/privacy` (replacement), `marketing/positioning.md` (the rule).
-- **Owner:** CoS for the withdrawal decision — **done 2026-10-29, option A**; Security Engineer for the
-  egress inventory and the disclosure text; CTO for any build change and for verifying the replacement;
-  CMO for the replacement copy and the rule-3 strike.
-- **Date:** withdrawal decision **done 2026-10-29** (was targeted 2026-10-31); inventory 2026-11-05;
-  replacement copy 2026-11-09, and it needs both the CTO's verification and the sponsor's approval —
-  rule-3 strike in the same commit as the page patch (§7 step 3).
-- **Must be true:** every egress in the inventory is either in the answer or gone from the build, and
-  `/privacy` lists the same set. The inventory's scope is wider than the draft first drew it — it must
-  cover `main.swift`, `LicenseService.swift`, `Info.plist`, `ChangelogRelease.swift`,
-  `SidecarController.swift`, **plus** `SidecarRelayAPI`/`WeatherService` (`/v1/weather`),
-  `NetworkInfoService`, `SpeedTest`, `ChangelogModel`, `BugReportClient` and Sparkle's appcast — and
-  on the Sentry side not only that it starts but `sendDefaultPii` and the trace sample rate. Until
-  then, do not publish a privacy answer.
-
----
-
-## 5. Held — clusters with no entry yet
-
-| Cluster | Why it is held | Owner and date |
-|---|---|---|
-| Trial / licence mechanics ("trial, Macs, updates") | No captured ask. NOOK-682 and NOOK-684 are defect reports, not a buyer question. The answer is factual (14 days, 3 Macs, Sparkle updates), but the task says do not invent a question to fill the slot. | CMO to capture an ask; CTO confirms `LicenseService.swift:43`, `:262` by 2026-11-03. |
-| Remote agents / containers | The launch claim is unverified (FRE-315, FRE-322, FRE-323, FRE-320). No FAQ answer before the demo. | CTO evidence; CMO copy the day it exists. Revisit 2026-11-12. |
-| Phone / Watch | Status is unverified; the landing page and FAQ currently disagree. | CTO status answer by 2026-11-03; CMO copy after. |
-| Refund / price | Contractual, and explicitly out of this issue. | FRE-204, CoS + sponsor. |
-| Custom agents | No captured ask; the `/agents` page already says a custom agent can wire itself in. | No entry until asked. |
-
----
-
-## 6. What the page edit would change
-
-**File:** `freno-dev/src/routes/nook/faq.tsx` (site `master` at `134f41e`; the branch is cut from
-local `c1c498e`, which removed the remote claim from the landing page, not from the FAQ).
-
-| Action | Entry |
-|---|---|
-| **Remove** | “Does The Nook read my prompts or my code?” — until the egress inventory and `/privacy` are true |
-| **Rewrite (correction only)** | “Do I need a Mac with a notch?” → E5 (per-display island, not the pointer's display) |
-| **Keep, with the exact text above** | “Why macOS 14.2 or later?” |
-| **Rewrite** | “What permissions does it need?” → E3 (adds the config/uninstall answer) |
-| **Rewrite** | “How much battery does it cost?” → E6 (no number) |
-| **Rewrite** | “Does it work offline?” → E8 (phone exception, six-row network list) |
-| **Add** | E1 (agent fit / Cursor) |
-| **Add** | E2 (idle) |
-| **Add** | E4 (terminal / tmux) |
-| **Edit** | The file header comment that cites `positioning.md` rule 3 → “Privacy is deliberately absent until the egress inventory and /privacy make an honest answer possible.” |
-| **Edit** | The `PageHead` description, which still advertises the privacy question → the new eight-entry list |
-
-Order on the page: E1, E2, E3, E4, E5, E6, E7, E8. The mailto link, the accordion behavior and the
-page title stay unchanged.
-
-**Not in this pass:** FAQPage JSON-LD. The page has none today; adding structured data is an SEO
-change, not an objection-mining change. It should be its own reviewed edit — and E1 no longer promises
-it.
-
-**Patch artifacts:** `freno-dev/marketing/drafts/faq-page.patch`, regenerated for this revision, and
-`freno-dev/marketing/drafts/positioning-privacy-withdrawal.patch` for the rule-3 strike step 3 needs
-to land with it (both proposals, neither applied). The page file and `positioning.md` are untouched
-until the gates below are satisfied; `faq-page.patch` re-checked against `freno-dev` master
-`c1c498e` on 2026-10-29 and applies cleanly.
-
----
-
-## 7. Publish gates and sequence
-
-| Step | Owner | Date | What settles it |
-|---|---|---|---|
-| 1. CTO verifies the claims and evidence pointers in E1–E8 | CTO | **done 2026-10-29** | [FRE-329](/FRE/issues/FRE-329), verdict in its `faq-verdict` document: E1/E7 verified as written, E2/E6 verified after one sentence each, E3/E4/E5/E8 corrected above, **no entry cut**. Applied in this revision. |
-| 2. Human approves this revision | Sponsor | target 2026-10-31 | The draft moves from `marketing/drafts/` to `marketing/approved/`, or the confirmation card on FRE-326 is accepted. The card asks one question now — publish the eight entries with the privacy answer withdrawn — because 2b is settled. |
-| 2b. Withdrawal of the false privacy answer and of `positioning.md` rule 3 | Chief of Staff | **done 2026-10-29** | [FRE-334](/FRE/issues/FRE-334) `decision`: **option A, withdraw both, one commit**, no privacy claim anywhere until FRE-333 lands and the CTO verifies it. Recorded here so the page, the rule and the card cannot disagree. |
-| 3. Apply the page patch, strike rule 3 + its approved-claims row, commit on `freno-dev` | CMO | 2026-11-03 | Both patches apply together to `freno-dev` master `c1c498e` (checked 2026-10-29, in a throwaway worktree, as one change set); the diff contains only the FAQ entries, the page comment/description, the `positioning.md` rule-3 strike and the 14.2 row. **The site's suite has not been run — this host has no `bun`** — so step 3 still has to run it before the commit. One commit, so the page and the rule move together. |
-| 4. Merge to `freno-dev/master` (the publish) | Sponsor or Chief of Staff | 2026-11-05 | A human merge; Vercel deploys. No agent pushes to master. |
-| 5. Verify the live page | CMO | 2026-11-05 | `https://nook.freno.me/faq` returns 200 and shows the eight entries with no privacy answer; the text matches the approved draft, sentence for sentence. |
-
-**If the CTO had rejected an entry:** cut it from the patch and ship the rest — it did not reject any.
-**If the sponsor does not approve:** nothing is applied; the draft stays in `drafts/`.
-**If the support mailbox becomes readable:** re-sort the register by observed asks before step 3;
-the top three may change, and the page order should follow the asks, not this draft's proxy ranking.
-**If a `Must be true` line stops being true** before step 3 — a fix regresses, a line moves — the
-entry goes back to the CTO, not onto the page.
-
----
-
-## Appendix A — verbatim source notes
-
-| Date | Source | Verbatim |
-|---|---|---|
-| 2026-10-29 | Live `/faq` | "Does The Nook read my prompts or my code?" / "Do I need a Mac with a notch?" / "How much battery does it cost?" / "What permissions does it need?" / "Why macOS 14.2 or later?" / "Does it work offline?" |
-| 2026-10-29 | FRE-326 description | “does it work with Cursor?” / “what happens when my agent is idle?” |
-| 2026-10-29 | [FRE-329](/FRE/issues/FRE-329) CTO verdict | “Four entries ship as written, two ship after a wording fix… two (E3, E4) currently say something false to a buyer.” Every correction in §3 is that document's own replacement sentence. |
-| 2026-10-08 | NOOK-121 | "Add /faq from real objections" — shipped the six live topics; refund dropped by Mike. |
-| 2026-10-20 | NOOK-643 | "agents: Cursor via hooks.json" — "No permission hook is installed, deliberately: Cursor blocks the action when a permission hook prints nothing…" |
-| 2026-10-21 | NOOK-707 | "agents: Cursor desktop chats bind to the shared extension-host pid and never end" |
-| 2026-10-23 | NOOK-898 | "hook: kimi payloads fail to decode, so every Kimi session stays idle" |
-| 2026-10-22 | NOOK-823 | "Codex terminal: sessions become idle or disappear prematurely" |
-| 2026-10-15 | NOOK-417 | "Never render plain Idle for a session whose integration is dark" |
-| 2026-10-15 | NOOK-415 | "Sessions whose integration predates the bridge credential freeze as Idle forever" |
-| 2026-10-21 | NOOK-733 | "codex: a non-interactive session never runs an installed hook (0.163.0)" |
-| 2026-10-20 | NOOK-648 | "opencode: uninstalling a pre-package install leaves its old nook.js link dangling" |
-| 2026-10-20 | NOOK-685 | "tests: InstallerTests.clineHookFiles writes through the managed TaskComplete symlink and then expects that path to survive uninstall" |
-| 2026-10-15 | NOOK-418 | "security: a custom agent's install target is never shown to, or approved by, the user" |
-| 2026-10-17 | NOOK-568 | "helper: launch-time re-registration tears down an approved helper and leaves it unregistered" |
-| 2026-10-13 | NOOK-302 | "terminal: a tmux session shows only 'tmux', and its outer terminal comes from whoever started the tmux server" |
-| 2026-10-13 | NOOK-310 | "terminal: jump and send address tmux panes on the default server, ignoring the session's tmux socket" |
-| 2026-10-22 | NOOK-788 | "pane: a remote reply inside a private tmux server resolves to nothing, and a pane id can be sent without its socket" |
-| 2026-10-12 | NOOK-290 | "Compact island: weather slot clips mid-glyph on non-notch displays (no text cap)" |
-| 2026-10-12 | NOOK-291 | "Compact island: non-notch pill is 36 pt wider than its slot row (padding double-counted in pillWidth)" |
-| 2026-10-14 | NOOK-386 | "island: hide the empty pill under the notch (or above the top edge) and keep a narrower hover trigger" |
-| 2026-10-23 | NOOK-850 | "Nook: the idle app does work nothing asked for (CPU wins from a live profile)" |
-| 2026-10-23 | NOOK-851 | "island: a 30 fps timeline ticks the fan icon even when the fan is idle" |
-| 2026-10-23 | NOOK-877 | "island: compact Nook still costs too much CPU at rest (round two, A/B per fix)" |
-| 2026-10-23 | NOOK-881 | "A macOS 14.0/14.1 Mac cannot launch the app at all: dyld dies on a strongly linked CATapDescription overlay symbol" |
-| 2026-10-16 | NOOK-494 | "iOS: the main list gives no sign the phone is offline from the Mac" |
-| 2026-10-20 | NOOK-682 | "licensing: a new user can be blocked at launch instead of getting the 14-day trial" |
-| 2026-10-20 | NOOK-684 | "licensing: parseISO rejects the server's fractional-second trial timestamp, so an expired server trial resets to 14 days" |
-| 2026-10-08 | NOOK-60 | "Capture email at trial start" |
-
-## Appendix B — frequency method
-
-- **Live questions:** one per entry that quotes the live page. There are six, and they are the only
-  questions on the page today.
-- **Board questions:** the two examples in FRE-326. They are not customer quotes; they are the
-  board's own words for the purchase-blocking objections this issue was created to answer.
-- **Report counts:** the number of distinct NOOK issues I read whose subject or resolution directly
-  produced the objection, listed by identifier and date in §2 and Appendix A. I did not use a raw
-  keyword count: "agent" appears in 344 issues and "privacy" in 177, which says nothing about what
-  buyers ask. The counts are deliberately small and inspectable.
-- **No ask frequency, no percentages.** The first thing a real support corpus changes is the order,
-  not the wording.
-
----
-
-*Draft ends. Nothing here is published. The page file stays unchanged until the sponsor approves this
-revision and a human merges it.*

marketing/drafts/faq-page.patch

@@ -1,81 +0,0 @@
-diff --git a/src/routes/nook/faq.tsx b/src/routes/nook/faq.tsx
-index 03d135a..bc3adef 100644
---- a/src/routes/nook/faq.tsx
-+++ b/src/routes/nook/faq.tsx
-@@ -1,8 +1,7 @@
- /**
-  * `/faq` on the Nook subdomain — answers to the objections that actually
-- * stop a purchase. Privacy scoping follows marketing/positioning.md rule 3:
-- * "no prompt or code content leaves the device" (telemetry and the trial
-- * email do leave — never claim "no data leaves the device").
-+ * stop a purchase. Privacy is deliberately absent until the egress
-+ * inventory and /privacy make an honest answer possible.
-  */
- import { For } from "solid-js";
- import { createSignal, Show } from "solid-js";
-@@ -17,34 +16,46 @@ interface FaqEntry {
- 
- const FAQ: FaqEntry[] = [
-   {
--    question: "Does The Nook read my prompts or my code?",
-+    question:
-+      "Does it work with my agent — and can I approve from the notch, or only watch?",
-     answer:
--      "No. The hooks and plugins that connect your agents to The Nook send session metadata only — which agent is running, which session, which event happened, which terminal it lives in. No prompt text and no code content leaves your device. Two things do leave the device, and we'd rather say so plainly: anonymous usage telemetry, and your email address if you choose to give it at trial start. That's the whole list."
-+      "It depends on the agent, and Cursor is the useful example. Cursor is watched, not gated: its sessions, finished turns and errors appear in the island, but when Cursor asks for permission the prompt stays in Cursor. That is deliberate — Cursor blocks the action when a permission hook runs and prints nothing, so gating it would override Cursor's own prompts. Other agents do hand the decision to The Nook, so a tool call waits and you tap Allow or Deny from the card. One limit: cursor-agent -p one-shot runs send no turn end, so they appear but do not get a completion card."
-   },
-   {
--    question: "Do I need a Mac with a notch?",
-+    question: "What happens when my agent is idle?",
-     answer:
--      "No. On a notched MacBook the island sits in the notch. On machines and displays without one, it anchors to the display your cursor is on, so a desktop setup with external monitors gets the same treatment. Everything inside the island — agent cards, fan control, the stats strip — works identically either way."
-+      "Idle means the last turn is over, or the session has not produced anything yet — not that the process is gone. A running process is liveness, not work: a just-opened agent window can show idle until you type. When an agent finishes a turn with a final message, the row stays green for ten minutes, then goes gray. A stale row is different: it means The Nook's integration cannot report for that session, and the row says so instead of pretending it is idle. Nothing is lost when a row goes idle — the next prompt brings it back and flips it to running. The row itself leaves the island 15 minutes after the turn (5 if the turn ended without a reply), so a long-quiet session reappears on its next event instead of sitting there. If a session that is obviously working says idle, that is a bug; tell us."
-   },
-   {
--    question: "How much battery does it cost?",
-+    question:
-+      "What permissions does it need — and what does it write into my agent's config?",
-+    answer:
-+      "The app itself runs unprivileged. Fan control and charge limiting go through a small helper that macOS requires to run as root for hardware access; the app registers it on first use and takes you to System Settings › General › Login Items & Extensions, where you switch it on once. For each agent it adds what that agent needs — a hook group per event it listens to, or one plugin link — inside the agent's own config file or directory. It keeps its own files under ~/.nook — the hook binary and one plugin copy per agent — and adds only its own entries to that agent's config. A hook entry you added yourself in the same file survives install and uninstall, and it only touches the records and switches it created. Uninstall removes exactly what it wrote — and switches off what it turned on — with no leftover links or orphaned files."
-+  },
-+  {
-+    question: "Does it work with my terminal, including tmux?",
-     answer:
--      "The Nook is a small native UI, not a background agent — it watches the agents you're already running; it doesn't run anything itself. The heaviest thing it does is read and write your Mac's fan and charging controllers, which is a lightweight sensor read. If you're running enough coding agents to need it, those agents dwarf the app's own draw."
-+      "Yes — it recognises Terminal.app, iTerm2, Warp, Ghostty, kitty, WezTerm and tmux. Four of those take a typed reply; the rest are watched. A session is tied to the terminal that started it. Jump lands in the right window for Terminal.app, iTerm2, kitty and any tmux pane — in tmux, the right pane; on Warp, WezTerm and Ghostty it brings the app forward instead. Replies type straight back into Terminal.app, iTerm2, kitty and any tmux pane; on Warp, WezTerm and Ghostty you answer in the app's own window, and Alacritty takes no typed reply from another app at all."
-   },
-   {
--    question: "What permissions does it need?",
-+    question: "Do I need a Mac with a notch?",
-+    answer:
-+      "No. On a notched MacBook the island sits in the notch. On machines and displays without one, it sits at the top centre of the display — the same pill with the same slots. You get one island on every display it is turned on for (all connected displays on first launch), each anchored to the top of its own screen; Settings › Displays trims that list, and the pointer only decides which display's floating controls are live. Everything inside the island — agent cards, fan control, the stats strip — works identically either way."
-+  },
-+  {
-+    question: "How much battery does it cost?",
-     answer:
--      "The app itself runs unprivileged. Fan control and charge limiting go through a small helper component that macOS requires to run as root for hardware access — the app installs it on first use and you approve it once with your password. The hooks live in each agent's own config directory; you can inspect or remove every file it writes."
-+      "It is a native app, not a background agent. It watches the agents you already run and never runs them in the background, so their draw is the number that matters. We do not have a published battery measurement for The Nook alone; when we do, it will be a measurement, not an estimate. If it costs more than it should on your Mac, that is a bug — tell us."
-   },
-   {
-     question: "Why macOS 14.2 or later?",
-     answer:
--      "The audio mixer listens to each app's own sound stream, and Apple only shipped that API in macOS 14.2 (Sonoma)."
-+      "The audio mixer listens to each app's own sound stream, and Apple only shipped that API in macOS 14.2 (Sonoma). The app links against it, so 14.0 and 14.1 cannot launch it."
-   },
-   {
-     question: "Does it work offline?",
-     answer:
--      "Yes. Everything The Nook does — the agent grid, permission cards, fan and thermal control — works with no network at all, and your agents' hooks talk to the app over a local socket. The network is only used for update checks, license activation, and the optional trial email."
-+      "The Mac app does. The island, agent cards, permission cards and fan control work with no network; the hooks talk to the app over a local socket. The network is used for update checks, licence activation, crash reports and the optional trial email, plus a few things only when you use them: weather (asked for through our relay, with the location you chose), the network panel's IP-and-ISP lookup, the speed test, the changelog in Settings, and a bug report if you send one. The phone link is the exception: when you are away from your Mac, the phone reaches it through our relay, so that part needs a connection."
-   }
- ];
- 
-@@ -56,7 +67,7 @@ export default function NookFaqPage() {
-       <EdgeCacheHeaders maxAge={300} />
-       <PageHead
-         title="Frequently asked questions"
--        description="Does The Nook read your prompts? Do you need a notch? Battery cost, permissions, the macOS 14.2 requirement, offline use — answered straight."
-+        description="Which agents can you approve from the notch? What does idle mean? Terminal and tmux support, permissions, the macOS 14.2 requirement, offline use — answered straight."
-         ogTitle="The Nook — FAQ"
-       />
-       <SubdomainHeader />

marketing/drafts/newsletter-postmortem-pitch/copy.md

@@ -0,0 +1,96 @@
+# Newsletter pitch — post-mortem shape (narrowed; no conversion figure)
+
+> **Status: draft — narrowed 2026-11-06 per the CTO's reopening verdict on
+> FRE-199.** The "X% trial→paid" half of the shape **cannot ship**: the
+> FRE-202 snapshot (window 2026-10-22 → 10-29) reads trial started 2, purchase
+> 0, activation 0, with 291 of 291 analytics rows predating the FRE-366
+> instrumentation — a trial→paid ratio from that cohort is not a metric. The
+> ratio comes from FRE-197's mature Day 28–35 cohort read when it lands.
+> **No figure in this file is a measurement.** Send gates at the bottom.
+
+## Audience & channel
+
+Editors of free dev-tool newsletters (the ones that run post-mortems and
+"what we learned" pieces). Direct email, one editor at a time, personalised.
+No paid placements at any budget without a CoS + sponsor decision.
+
+## The claim the pitch goes out with
+
+A post-mortem pitch, not a product pitch: *here is what shipping a Mac utility
+alone actually broke, and what we changed because of it.* The product is the
+setting; the breakage and the fix are the story. The story stands on its own
+with zero funnel numbers — if no verified number exists on send day, the pitch
+ships without one rather than with a placeholder.
+
+## The pitch (shape — names and dates personalised; nothing else is a placeholder)
+
+**Subject:** What shipping a Mac utility alone broke (post-mortem)
+
+Hi <editor>,
+
+We build The Nook, a $10 Mac utility that surfaces coding-agent approvals at
+the notch. I'm not pitching the app — I'm offering a post-mortem your readers
+usually only get from funded startups, because shipping alone broke things in
+ways bigger teams don't hit:
+
+- **The silent update.** In October we shipped a release whose appcast published
+  cleanly — while every delta it named 404'd, so users on older builds were
+  being offered updates that didn't exist. The publish path deleted files
+  before the feed that named them was live. Nothing alerted; the feed just
+  lied quietly. The fix — upload the feed's enclosures, verify every enclosure
+  URL, copy the appcast up, and only *then* prune — is now ordered so the
+  deletion can't run first.
+- **The green suite.** Weeks earlier, a regression in our public relay shipped
+  behind a passing test run — the suite that would have caught it existed but
+  nothing invoked it. A green checkmark that covers nothing looks identical to
+  one that covers everything. The suite is now wired into the standard test
+  entry point, and the relay's deploy patcher is tested alongside it.
+- **What we're not going to quote you.** A growth number, right now, would be
+  theatre: our funnel is young and a conversion ratio from an immature cohort
+  is not a measurement. If we attach a count, it will be activations — one per
+  activated install, from our own relay store — and we will say exactly that,
+  because download counts (a different number, from a different store) flatter
+  nothing and confuse everyone. The receipts that matter here are the failure
+  modes above, not a traction line.
+
+The angle for your readers: solo distribution is a chain of quiet failure
+modes, each one invisible until it costs a user. We kept the receipts.
+
+Happy to send the full write-up, screenshots of the broken feed, and the exact
+publish-order and test-wiring changes.
+
+— <name>, FrenoCorp
+
+## Where a number could come from, and what disqualifies it
+
+- **Trial→paid ratio: cannot ship today.** FRE-202's snapshot shows a cohort of
+  2 trials, 0 purchases, pre-instrumentation rows. The ratio waits for
+  FRE-197's mature Day 28–35 read. If it lands before send day and the CTO
+  confirms the query, the ratio may be added — and it must say it is per
+  *install* (install cap 3), not per person.
+- **Activations: the only count eligible to ship.** One row per activated
+  install (`installs`, `created_at`) in the relay store; CTO confirms the query
+  before any send. The pitch names it as activations, never as downloads.
+- **Downloads (S3 side) are never quoted.** Different store, automation-heavy,
+  and the pitch that says "downloads" when it means activations burns the
+  credibility the post-mortem is built on.
+- No number is estimated to fill any gap, ever.
+
+## Gates before anything is sent
+
+1. Any count quoted is activations, from a CTO-confirmed query — owner: CTO.
+2. The trial→paid ratio ships only from FRE-197's mature cohort read with CTO
+   confirmation; otherwise the "what we're not going to quote you" paragraph
+   stands as written — owner: CTO.
+3. Both breakage paragraphs are fact-checked against the engineering record
+   (FRE-542 publish-order incident; the NOOK-815 uninvited-suite relay
+   regression) before send — owner: CMO, evidence to CTO for verdict.
+4. Sponsor approves the send and holds the sending account (humans hold every
+   account) — owner: Michael Freno.
+
+## Target dates (internal)
+
+- Draft with placeholders: **done 2026-11-05**; narrowed to the no-figure shape
+  **2026-11-06** (CTO direction).
+- Send: after gates 1–4 — with the no-figure shape, the only hard input left is
+  the CTO's query confirmation and the sponsor's send.

marketing/drafts/newsletter-postmortem-pitch/rationale.md

@@ -0,0 +1,73 @@
+# Rationale — newsletter post-mortem pitch (shape)
+
+FRE-199 item 2. Drafted 2026-11-05 by CMO (plan date was 2026-11-06; FRE-201
+landed today, which was the only gate on drafting the shape).
+
+## Why draft now
+
+The Chief of Staff's sequencing had the pitch drafted when FRE-201 landed. It
+landed 2026-11-05 (row closed `done` 18:45Z; the daily scan routine
+`2553b201` has been producing the backlog since 2026-10-30). The figures were
+never gated on FRE-201 — only the shape was — so the shape ships now and the
+figures stay placeholders behind their own gate.
+
+## Why a post-mortem and not a product pitch
+
+The issue text's own thesis: "1,900 downloads, 6% trial→paid, here's what
+broke" outperforms a product pitch. Editors of free dev-tool newsletters run
+post-mortems; a solo shop shipping a Mac utility and keeping receipts is a
+story they can run without us asking for a review.
+
+## The breakage is real, not invented
+
+The lead paragraph is the 0.13.4 delta incident (FRE-542): the appcast stayed
+at 0.13.4 while its five delta files 404'd — the publish path pruned before
+the feed was up. The fix (upload enclosures, verify URLs, copy the appcast,
+then prune) is in `scripts/upload-release.sh` and is engineering-verified by
+the FRE-542 record.
+
+**Second breakage, chosen 2026-11-06 (CTO direction):** the relay regression
+that shipped behind a passing suite (NOOK-815) — the suite that would have
+cought it existed but nothing invoked it; the fix wires it into the standard
+test entry point. It was chosen over the changelog-blanking incident because
+it is a complete story with no number needed and no overlap with the lead
+(both remaining candidates were publish-path incidents; one story about the
+publish path is enough). The placeholder is gone: no paragraph in the pitch
+waits on a figure any more.
+
+## Narrowed 2026-11-06 — what the numbers can and cannot support
+
+The CTO's reopening verdict on FRE-199 confirmed **no figure for the pitch
+today**: FRE-202's snapshot (trial started 2, purchase 0, activation 0; 291 of
+291 rows predate the FRE-366 instrumentation) cannot yield a trial→paid ratio —
+that waits for FRE-197's mature Day 28–35 cohort read. So the pitch narrowed:
+
+- the "X% trial→paid" placeholder is deleted, not held;
+- if any count ships, it is **activations** (relay store, one row per activated
+  install), named as activations — downloads (S3 side) are never quoted;
+- a new paragraph — "what we're not going to quote you" — turns the missing
+  number into part of the post-mortem's credibility instead of a gap;
+- with the no-figure shape, the only inputs left before send are the CTO's
+  query confirmation (if a count is attached) and the sponsor's send.
+
+## Hard rules honoured
+
+- No figure in the file is a measurement; nothing is estimated to fill a gap.
+- No conversion figure ships — the ratio is FRE-197's, gated and CTO-confirmed.
+- Any count that ships is activations, named as activations; downloads are
+  never quoted.
+- The two caveats (per-install conversion with install cap 3; downloads ≠
+  activations) are written to travel inside the pitch, not a footnote.
+- Paid placements: out, per the issue text and the plan (TLDR ≈ $3k, no
+  verifiable CPC). No placement is bought without CoS + sponsor.
+- Price appears once ($10, what the app actually charges) to identify the
+  product — no discount, no countdown, no price-change copy (FRE-204 holds).
+
+## Gates before send
+
+1. Any count quoted is activations, from a CTO-confirmed query — CTO.
+2. Trial→paid ratio ships only from FRE-197's mature read, CTO-confirmed;
+   otherwise the no-figure paragraph stands — CTO.
+3. Both breakage paragraphs fact-checked against the engineering record
+   (FRE-542; NOOK-815) — CMO drafts, CTO verifies.
+4. Sponsor approves the send; a human holds the account and sends — sponsor.

marketing/drafts/positioning-privacy-withdrawal.patch

@@ -1,40 +0,0 @@
-diff --git a/marketing/positioning.md b/marketing/positioning.md
-index 1bc4973..26d6b04 100644
---- a/marketing/positioning.md
-+++ b/marketing/positioning.md
-@@ -53,13 +53,20 @@ pages, marketing copy, comparison tables, meta descriptions, emails, FAQs, all o
- Copy that says "13 agents" or "no data leaves the device" must have a test backing it.
- If a claim cannot be pointed at code or a test, it does not go in copy.
- 
--### 3. Honest privacy scoping
-+### 3. No privacy claim until the egress inventory exists (withdrawn 2026-10-29)
- 
--Telemetry and the trial email **do** leave the device. The defensible claim is:
-+The claim that stood here — "No prompt or code content leaves the device" — is **false at HEAD**
-+and must not be restated in any copy until it is verified and replaced. It was backed by an
-+argument about envelope metadata, which says nothing about what leaves the machine. Three things
-+at HEAD contradict it: crash reporting initialises with `sendDefaultPii = true`; the licence call
-+sends the hardware UUID and the device name; the phone relay carries sealed prompt and reply
-+payloads. `/privacy` names the hardware UUID and the device name and says nothing about crash
-+reporting with PII or about the relay.
- 
--> **No prompt or code content leaves the device.**
--
--Never "no data leaves the device".
-+So: write **no** privacy claim at all — not softened, not partial. "Telemetry and the trial email
-+do leave the device" is true and insufficient; it is not a substitute. The replacement goes in
-+only after FRE-333 lands an egress inventory and `/privacy` text that match what the app does.
-+See FRE-326 (the `/faq` withdrawal) and FRE-333 (the inventory).
- 
- ### 4. Sell what works today
- 
-@@ -87,8 +94,7 @@ nothing posts itself.
- | Permission gate answered from a card | awaitPolicyTable + bridge directive path (`hook/normalize.go`, `serialize.go`) |
- | Fan / thermal / charge control | `helper/` (privileged helper, SMC, no kext) |
- | One-time purchase, no subscription | $10 → $15 at 1.0; Stripe checkout |
--| macOS 14+ | 27 source files use the `@Observable` framework |
--| No prompt or code content leaves the device | envelope carries session/event/terminal metadata only (see `docs/agent-interface.md`) |
-+| macOS 14.2+ | the CoreAudio overlay symbol the mixer uses only exists from 14.2 (NOOK-881) |
- 
- ## Held claims (not publishable)
- 

marketing/drafts/privacy-page.md

@@ -1,92 +0,0 @@
-# `/privacy` — replacement copy, FRE-354 corrections applied 2026-11-04
-
-**Status:** applied on branch `faq/from-objections-2026-10-29` (commit after `bb6cf27`), per the CTO's FRE-354 verdict — "apply the corrections above and the page is signed." The two copy decisions the verdict delegated to the CMO are taken: the **fuller iPhone paragraph** (its push-token evidence row is recorded in the evidence table below and routed to FRE-333's owner to append to the signed inventory), and the **full (c) block with the LAN/tailnet sentence**, which pulls the corresponding Section 3 clause in. Nothing here is published; the sponsor's merge + push on card [`392a8465`](/FRE/issues/FRE-326#interaction-392a8465) is still the deploy step.
-**Sequencing fact, updated 2026-11-06:** the contingency has **fired**. `v0.15.1` (tagged 2026-11-04, first tag containing FRE-355's merge `6e74b261`) and `v0.15.2` are live on the appcast (`freno.me/api/TheNook/appcast.xml`, newest item 0.15.2). Shipped behaviour when enabled: crash/error reports, session pings (`enableAutoSessionTracking` untouched), traces at 0.1, and **Sentry also receives the connection's IP address** (`sendDefaultPii = false` is the SDK default and does not suppress it; only the Sentry project's *Prevent Storing of IP Addresses* switch does — FRE-1480). Paragraph (b) and the iPhone paragraph are therefore swapped to the opt-in form in this commit, with two corrections against the pre-written swap text: pings and traces are named (the contingency's own completeness warning), and the IP sentence is kept. Releases 0.3.0 through 0.15.0 started Sentry on every launch with no off switch; the page describes the current release.
-**Patch:** `marketing/drafts/privacy-page.patch` — applies cleanly to `c1c498e` (`git apply --check`, verified 2026-10-29; parse-checked with esbuild, not the site suite).
-**Evidence base:** [FRE-333 `egress-inventory`](/FRE/issues/FRE-333#document-egress-inventory) rev 1, eleven destinations, file:line per row, read at `The-Nook` `3c3ba7ee`; and the same document's §G, which proposed a page text. This patch is the §G text **corrected against the inventory** — the differences are listed below, each with the row that forces it.
-**Why this exists:** [FRE-326](/FRE/issues/FRE-326) + [FRE-334](/FRE/issues/FRE-334#document-decision) recorded option A — the privacy claim is withdrawn everywhere, and no privacy claim returns until the inventory exists, `/privacy` matches it, the CTO verifies both, and the sponsor approves the replacement copy. The inventory landed on 2026-10-29. This is the page half.
-
-| Field | Value |
-|---|---|
-| Claim this page carries | None. It is a disclosure page, not a claim: it states what the app sends and what it does not. The one favourable sentence is (j), which is the CTO's FRE-322 §2 code fact and which he may still decline. |
-| Audience | Someone deciding whether to pay $10 for a tool that reads their prompts. They read this page *before* the FAQ. |
-| Channel | `nook.freno.me/privacy`, one page |
-| Owner | CMO (copy + commit), CTO (verification), sponsor (approval of the replacement copy), Chief of Staff (publish switch) |
-| Date | Prepared 2026-10-29. Applied 2026-11-04 on the branch with the FRE-354 corrections; the contingency (b)/iPhone swap applied 2026-11-06. `Last Updated` on the page now reads November 6, 2026 — re-check it against the actual deploy date at push. Not a public date. |
-| What has to be true before it ships | 1) CTO signs the page against `The-Nook` HEAD, paragraph by paragraph — [FRE-354](/FRE/issues/FRE-354), due 2026-11-02. 2) Sponsor accepts the replacement copy. 3) The Sentry paragraph matches the build being deployed — see *Contingency*. 4) It deploys in the same push as the FAQ withdrawal; a page that discloses Sentry next to a FAQ that still says "anonymous usage telemetry" is worse than either alone. |
-
-## What changed against the live page
-
-The live page (fetched 2026-10-29T09:2xZ and again 09:4xZ, HTTP 200, `Last Updated: August 26, 2026`, unchanged) says the app "runs locally on your device and sends only the minimal data required for trial and licensing" and lists four things. Against the inventory that is wrong in two directions: it **omits** Sentry (crash reports with IP address, every launch, no off switch), the relay and its install ID, the licence key crossing to the relay, sealed phone payloads, weather coordinates going to the relay *and* to Apple, the GeoIP third parties, the speed test, the changelog fetch, bug-report contents and update checks. It also calls the hardware UUID "masked", which the code contradicts — it sends the raw `IOPlatformUUID`.
-
-The replacement is organised by *connection*, not by *data type*, because that is how a reader checks it: eleven rows in the inventory, ten of them reachable from the page, one (Sentry) prominent because it is the only one a reader can turn off entirely and still miss in older builds. On the current Mac release (`v0.15.1`+) it is opt-in and off by default; the iPhone build in TestFlight (`ios-v0.3.2`, 2026-10-22) predates it. See *Contingency*.
-
-## Differences from FRE-333 §G, and what forces each
-
-§G is the Security Engineer's proposed text; this patch is that text corrected against §G's own inventory. Six deliberate differences, none of them stylistic:
-
-| # | §G says | This patch says | Why |
-|---|---|---|---|
-| 1 | Opening: "processed on your device and are never sent to us" | Opening drops "never sent to us"; (c) and (j) state the two paths agent data does take | Sealed frames still transit our relay (§A.5, §B), and a remote machine carries them by design (§C). §G's own §B says the relay routes them. "Never sent to us" is the class of sentence that got the FAQ answer withdrawn. |
-| 2 | (d) Weather: relay registration implied only with Phone | (d) adds that Weather registers **even with Phone off, and on a licensed Mac that registration presents the license key** | §A.3 + §D.2. `SidecarController.weather()` routes through the same `keystore.relayCredential(licenseKey:)` as the phone path (`SidecarController.swift:269-279`, `SidecarRelayAPI.swift:298-312`). §G under-disclosed it. |
-| 3 | (a) trial/activate/status only | (a) adds `/deactivate` (key + UUID) and the trial email (email + UUID, sent once) | §A.2, `/D.4`. §G omitted both endpoints. |
-| 4 | (i) "The email you give at trial start or checkout delivers your license key" | (i) checkout delivers the key; a trial email is one reminder before the trial ends | `LicenseService.submitTrialEmail` + `OnboardingExtrasStep` say the trial email is an expiry reminder; the key is issued at purchase. §G's sentence promised a key that the trial email does not deliver. |
-| 5 | (b) Sentry: opt-in, "off unless you turn it on" | (b) is the opt-in form, applied 2026-11-06: off unless enabled in Settings, and it names session pings and the trace sample; **the IP sentence, kept** | The contingency fired with `v0.15.1`. Corrections against the pre-written swap text: pings/traces named because they still flow when enabled; IP kept because `sendDefaultPii = false` does not stop Sentry receiving the connection IP (FRE-1480); the Contingency text already said so. |
-| 6 | No (j) | (j) carries the CTO's FRE-322 §2 code fact, with the remote-machine exception | Not required for truth; it is the one favourable sentence, and the CTO may decline it. Delete the block if he does. |
-
-Two facts the inventory corrected and the page does not repeat wrongly: Sparkle's automatic checks are **off by default** here (`UpdateManager` owns the schedule; FRE-322 §2.4 said "on by default" and is stale on this row), and the UUID is **raw, not masked**.
-
-## Paragraph-level evidence
-
-| Paragraph | What it now says | Evidence at `3c3ba7ee` |
-|---|---|---|
-| (a) Licensing/trial | raw UUID + device name; every launch while trialing; key-only once licensed; deactivate sends key + UUID; trial email sends email + UUID once; trial/status fail open, activation needs a connection once | `LicenseService.swift:300-313` (`/trial`), `:271-284` (`/status`), `:247-262` (`/activate`), `:286-302` (`/deactivate`), `:219-231` (`/trial-email`) |
-| (b) Crash reporting | opt-in, **off by default**; when enabled: crash/error reports, session pings, traces at 0.1; **Sentry also receives the IP address** (`Options.swift:267-275` at 9.26.1: `sendDefaultPii = false` is the default and does not suppress it); no prompts or code | `Sources/NookApp/main.swift` `startIfEnabled` — `sendDefaultPii = false` (`policy.sendDefaultPii`), `tracesSampleRate = 0.1` while on (`CrashReporting.onTracesSampleRate`); `CrashReporting.registerDefaults` pins `enabledKey: false`; evidence read 2026-11-06, IP row per FRE-1480 |
-| (c) Phone relay | off by default; relay is the default path, LAN/tailnet direct pairing available; install ID + license key at registration; sealed payloads; relay sees device IDs/names/platforms, timing and volume, not content | `SidecarRelayAPI.swift:144-153`, `SidecarPayload.swift:484-490`, `RemoteEndpoint.swift:14-24`, `docs/sidecar-frames.md` (sealing), inventory §B |
-| (d) Weather | 0.1° grid snapped **on the Mac**; registers with the relay even with the phone off, licence key included on a licensed Mac; Apple sees place lookups and position | `WeatherForecast.swift:25-30`, `SidecarController.swift:269-279`, `SidecarRelayAPI.swift:298-312`, `WeatherLocation.swift:14-77`, `:89-143` |
-| (e) Network panel | third-party IP lookup sees your IP; speed test uploads zeros only | `NetworkInfoService.swift:82,276`, `SpeedTest.swift:10-11,36` |
-| (f) Update checks | ship **off**; turning them on fetches `freno.me`, app version + IP | `UpdateManager.swift:48-55` (`automaticallyChecksForUpdates = false`, default key false) |
-| (g) Changelog | fetches release notes from `freno.me` | `ChangelogRelease.swift:75-78` |
-| (h) Bug reports | user-sent only; machine snapshot listed in full | `BugReportClient.swift:44-94`, `BugReportSnapshot.swift:17-36` |
-| (i) Email/payment | checkout email delivers the key; trial email is a reminder; Stripe | `LicenseService.swift:219-231`, `OnboardingExtrasStep.swift:86-110` |
-| (j) What does not leave your Mac | hook and bridge are not a cloud service; helper has no networking; two paths carry agent data across the network, both user-switched: remote machines over SSH or the tailnet, and the sealed phone relay | `hook/transport.go:143` (`resolveBridge`), `BridgeBindPlan.swift:9-23`, `RemoteEndpoint.swift:14-24`, inventory §B + §C |
-| iPhone companion (TestFlight beta) | the TestFlight build (`ios-v0.3.2` = `2e322da5`, 2026-10-22) predates FRE-355: unconditional start, `sendDefaultPii = true`, traces 1.0, no off switch (`ios/AgentNookMobile/App.swift:13-20`); the opt-in code exists at `v0.15.2` but no `ios-v*` tag carries it; other traffic is the phone connection in (c) plus the APNs push token given to the relay | `RelayLink.pair` `RelayLink.swift:104-118`, `updatePushToken` `:226-232` — row added per FRE-354, TestFlight provenance per FRE-1480; append to the FRE-333 inventory |
-
-## Contingency — the Sentry paragraph is the only one that moves
-
-**FIRED 2026-11-06 — applied on the branch.** `v0.15.1` is the first release containing FRE-355 and is live on the appcast. The swap below was applied with the corrections recorded in the sequencing paragraph at the top of this document (pings and traces named; IP sentence kept — the pre-written text below had it, and dropping it was wrong; FRE-1480). The original text is kept for the record:
-
-(b) as committed describes today's build. The inventory's recommendation (§E.1) is an opt-in setting, default off, dropping `sendDefaultPii` and cutting `tracesSampleRate`, on Mac **and** iOS. If that ships, (b) is replaced in the same commit that changes the behaviour:
-
-> **(b) Crash and error reporting — off unless you turn it on.** If you enable crash reporting in Settings, The Nook sends crash and error reports to Sentry, our crash-reporting processor. Reports include the app version, macOS version, Mac model and what the app was doing when it failed, and Sentry also receives your IP address. They never include your prompts or code.
-
-**Sequence call, and who owns it.** Shipping (b)-with-no-off-switch is honest, but it puts "no off switch" in front of a buyer during launch week. The better order is the build change first, then this page — that is a build/priority call, not mine: it is proposed on the board as [FRE-355](/FRE/issues/FRE-355) (Senior Engineer, date proposed 2026-11-06, CTO to confirm), and if the CTO says the build change cannot land before the page, the page ships with today's text. Publishing the truthful-today version is never *blocked* by that choice; the *preferred* order is the other way.
-
-**This is why (b) must not be softened on the way out.** If the opt-in setting ships but `tracesSampleRate` or session tracking stays on, (b)'s opt-in form is incomplete again — it names only "crash and error reports" while performance traces and session pings still flow. The paragraph and the build change move together or neither does. (FRE-354 rewrote this warning: the original named a macOS username that sentry-cocoa never sends.)
-
-## If the CTO declines paragraph (j)
-
-(j) is the only favourable sentence on the page and the only one carrying a CTO verdict rather than an inventory row. It is [FRE-322 §2](/FRE/issues/FRE-322#document-verdict) — *"verified as a code fact, not publishable yet… publishing it before the disclosure work lands would put a true sentence next to false ones."* The disclosure work is this page. If the CTO still declines it, delete the whole (j) block; nothing else on the page depends on it, and the page stays complete and true.
-
-## Open questions for the CTO's read
-
-1. **The iOS app.** §D.10: the iOS target starts the same Sentry DSN with the same `sendDefaultPii` (`ios/AgentNookMobile/App.swift:12-20`). This page says "runs on your Mac". Is any iOS build in users' hands? If yes, the page needs one sentence (or the build needs the same opt-in); if no, say so and the page stays Mac-only.
-2. **Weather registration without a licence key.** §E.3 suggests decoupling weather registration from the licence key. If that ships before the page, (d) loses its licence-key clause; if after, the page is true today.
-3. **(j)** — publish, or cut.
-
-## Apply checklist — what the apply commit must do, in order
-
-1. Re-read the live page and the inventory's HEAD; if either moved, re-derive (a)–(j) before applying. The inventory is pinned to `3c3ba7ee`.
-2. Bump `Last Updated` to the **deploy** date — the patch carries 2026-10-29 as prepared, and that line is the one place the date must change at apply.
-3. If the Sentry opt-in build change is in the same release, swap (b) for the *Contingency* paragraph — one hunk.
-4. Apply `privacy-page.patch` and the FRE-326 `faq-page.patch` + `positioning-privacy-withdrawal.patch` in the **same** commit, so no page states the old claim while another corrects it.
-5. Run the site's suite — `bun test` — which this host cannot do (no `bun`; `node_modules` present, `package.json` test script is `bun test`). A parse/transpile check with esbuild is **not** that suite and must not be recorded as one.
-
-## Rules this page obeys
-
-- No competitor named (category nouns only, and none needed here).
-- No claim without a row in the inventory. Where the inventory has no row, the page says nothing.
-- No roadmap promise: the page never says a feature or fix is "coming", so the Sentry paragraph does not promise an off switch.
-- No price, no discount, no date, no launch language.
-- It is a correction of an existing page, not new marketing; nothing was added to sell anything.
-- It does not add a `/faq` privacy answer. That answer's return is gated separately ([FRE-326](/FRE/issues/FRE-326) `privacy-return-path`).

marketing/drafts/privacy-page.patch

@@ -1,237 +0,0 @@
-diff --git a/src/routes/nook/privacy.tsx b/src/routes/nook/privacy.tsx
-index da0cc1d..db27d8c 100644
---- a/src/routes/nook/privacy.tsx
-+++ b/src/routes/nook/privacy.tsx
-@@ -1,9 +1,38 @@
- /**
-  * The Nook privacy policy — `nook.freno.me/privacy`.
-  *
-- * Reflects the actual data The Nook sends when licensing: a masked hardware
-- * UUID + device name for trial/activation limits, the email used for purchase,
-- * and Stripe payment processing.
-+ * Every statement on this page is traced to the egress inventory at
-+ * `The-Nook` HEAD (FRE-333, `document-egress-inventory`): eleven internet
-+ * destinations, file:line evidence per row. When the app's egress changes,
-+ * this page changes in the same commit — not later.
-+ *
-+ * The crash-reporting paragraphs ((b) and the iPhone companion) describe the
-+ * build users run today: crash reporting is opt-in, off by default, on
-+ * releases v0.15.1 and later — FRE-355 (merge `6e74b261`) first shipped in
-+ * `v0.15.1` (2026-11-04), and the live appcast serves `v0.15.2`. When enabled,
-+ * Sentry receives crash and error reports, session pings, and performance
-+ * traces at a 0.1 sample rate (`tracesSampleRate = 0.1`), and it also receives
-+ * the connection's IP address (`sendDefaultPii = false` is the SDK default and
-+ * does not suppress it — sentry-cocoa 9.26.1 sets `infer_ip = auto` for Cocoa,
-+ * and only the Sentry project's *Prevent Storing of IP Addresses* switch stops
-+ * that; FRE-1480). Releases 0.3.0 through 0.15.0 started Sentry on every
-+ * launch with `sendDefaultPii = true` and no off switch; this page describes
-+ * the current release. The iPhone paragraph describes `ios-v0.3.2`
-+ * (2026-10-22, the build in TestFlight) until an `ios-v*` tag carries
-+ * FRE-355's opt-in code.
-+ *
-+ * The *Contingency* in `marketing/drafts/privacy-page.md` fired with `v0.15.1`
-+ * and is applied in this commit, with two corrections against the pre-written
-+ * swap text: the shipped build still sends session pings and traces while
-+ * enabled, so they are named (the contingency's own completeness warning), and
-+ * the IP sentence is kept — the pre-written swap text already had it, and
-+ * `sendDefaultPii = false` does not stop Sentry receiving the IP (FRE-1480).
-+ *
-+ * Corrected against the CTO's /privacy verdict (FRE-354): no macOS username
-+ * from Sentry (sendDefaultPii sets the IP only), session pings named, (a)
-+ * fail-open scoped, (c) relay-path qualified with the direct-pair sentence,
-+ * (j) "not a cloud service" with the tailnet path, the iPhone paragraph added
-+ * (TestFlight beta is in users' hands), and section 3 says "content".
-  */
- import { buildMainSiteUrl } from "~/lib/subdomain-url";
- import { PageHead } from "~/components/PageHead";
-@@ -21,39 +50,139 @@ export default function NookPrivacyPolicy() {
-       <SubdomainHeader />
-       <div class="min-h-screen px-[8vw] py-[10vh]">
-         <div class="py-4 text-xl">The Nook&apos;s Privacy Policy</div>
--        <div class="py-2">Last Updated: August 26, 2026</div>
-+        <div class="py-2">Last Updated: November 6, 2026</div>
-         <div class="py-2">
--          Welcome to The Nook (&apos;We&apos;, &apos;Us&apos;, &apos;Our&apos;).
--          Your privacy is important to us. This policy explains what we collect,
--          why, and how it is handled. The app itself runs locally on your device
--          and sends only the minimal data required for trial and licensing.
-+          The Nook runs on your Mac, and the iPhone and Apple Watch companion
-+          is in TestFlight beta. Your prompts, your code and your agent
-+          sessions are processed on your own devices. This page lists every
-+          connection the apps make over the internet — and the local-network
-+          and tailnet paths the phone can use — what each one sends, and
-+          whether you can turn it off.
-         </div>
-         <ol>
-           <div class="py-2">
-             <div class="pb-2 text-lg">
--              <span class="-ml-4 pr-2">1.</span> Data We Collect
-+              <span class="-ml-4 pr-2">1.</span> What leaves your devices
-             </div>
-             <div class="pl-4">
-               <div class="pb-2">
--                <div class="-ml-6">(a) Device hardware UUID:</div> When you start
--                a trial or activate a license, The Nook sends a hardware UUID
--                from your Mac. It is used solely to enforce the 14-day trial and
--                the 3-device activation limit, and to prevent resetting the
--                trial by reinstalling the app.
-+                <div class="-ml-6">(a) Licensing and trial:</div> When you start
-+                a trial or activate a license, The Nook sends your Mac&apos;s
-+                hardware UUID and device name to our licensing server
-+                (freno.me). The UUID enforces the 14-day trial and the 3-device
-+                activation limit and stops a trial being reset by reinstalling
-+                the app; the device name is stored with the activation so the
-+                Mac can be identified in your license records. While you are on
-+                the trial, this is sent at each launch. Once you are licensed,
-+                each launch re-checks only that your key has not been revoked.
-+                Deactivating a Mac sends the license key and that Mac&apos;s
-+                UUID. If you add an email during the trial, that request
-+                carries the email and the UUID, and it is sent once. The trial
-+                and status checks fail open: with no connection, an unexpired
-+                trial or a stored license keeps working, because license
-+                verification itself is offline. Activating a new license needs
-+                a connection once.
-+              </div>
-+              <div class="pb-2">
-+                <div class="-ml-6">(b) Crash and error reporting — off unless
-+                you turn it on:</div> Crash reporting is off by default and
-+                runs only if you enable it in Settings. When it is on, The Nook
-+                sends crash reports, error events, hang reports, session pings,
-+                and a sample of performance traces to Sentry, our
-+                crash-reporting processor. Each report carries the app version,
-+                the macOS version, the Mac model and what the app was doing
-+                when it failed. Sentry also receives your IP address. They
-+                never include your prompts, your code or your session content.
-+              </div>
-+              <div class="pb-2">
-+                <div class="-ml-6">(c) Phone connection:</div> The phone
-+                connection ships off and is yours to enable. With the default
-+                relay path, turning it on registers your Mac with our relay
-+                (nook-relay.freno.me) using a random install ID, and a licensed
-+                Mac presents its license key once at registration. Everything
-+                your Mac and your phone then exchange — session updates,
-+                approvals, replies — is encrypted end-to-end: the relay routes
-+                it and cannot read it. On the relay path, the relay can see
-+                which devices are connected — their IDs, names and platforms —
-+                when, and how much traffic they exchange.
-+              </div>
-+              <div class="pb-2">
-+                You can also pair over your LAN or tailnet instead; those paths
-+                carry the same sealed traffic and do not use the relay.
-+              </div>
-+              <div class="pb-2">
-+                <div class="-ml-6">(d) Weather:</div> If you add the Weather
-+                module, your Mac asks our relay for forecasts using coordinates
-+                rounded to a 0.1° grid — about 11 km — and the rounding happens
-+                on your Mac before anything is sent. The Weather module
-+                registers with the relay for this even if you never turn on the
-+                phone connection, and on a licensed Mac that registration
-+                presents the license key, exactly as the phone connection&apos;s
-+                does. &quot;My Location&quot; asks macOS for your
-+                approximate position, and naming or searching for a place uses
-+                Apple&apos;s Maps service, so Apple sees those lookups. Neither
-+                feature sends us your precise location.
-+              </div>
-+              <div class="pb-2">
-+                <div class="-ml-6">(e) The Network panel:</div> While the
-+                Network panel&apos;s connection section is on screen, The Nook
-+                asks a third-party IP-lookup service (get.geojs.io, with
-+                ipwho.is as backup) what your public IP address and provider
-+                are — that is how the panel can show them to you. Those services
-+                necessarily see your IP address. The speed-test button measures
-+                against Cloudflare&apos;s public speed endpoint and uploads only
-+                zeros, never your data.
-+              </div>
-+              <div class="pb-2">
-+                <div class="-ml-6">(f) Update checks:</div> Automatic update
-+                checks ship off. If you turn them on, or press &quot;Check for
-+                Updates&quot;, The Nook fetches the update feed from freno.me
-+                and the request carries your app version. Like every request on
-+                this page, it also arrives from your IP address.
-+              </div>
-+              <div class="pb-2">
-+                <div class="-ml-6">(g) Changelog:</div> Opening Settings ›
-+                Changelog fetches the release notes from freno.me.
-+              </div>
-+              <div class="pb-2">
-+                <div class="-ml-6">(h) Bug reports:</div> only what you choose
-+                to send. If you write a bug report, you decide what it says.
-+                Bug reports also include a machine snapshot — macOS version, Mac
-+                model, CPU, memory, free disk, locale, and your displays&apos;
-+                names and resolutions — so the problem can be reproduced. The
-+                optional contact email is used only to reply to you.
-               </div>
-               <div class="pb-2">
--                <div class="-ml-6">(b) Device name:</div> The Nook sends your
--                Mac&apos;s name so you can recognize the device in your license
--                activations. It is not used for any other purpose.
-+                <div class="-ml-6">(i) Your email and payment:</div> The email
-+                you give at checkout delivers your license key and looks up your
-+                order. An email you add during the trial is used for one
-+                reminder before the trial ends. Payments are processed by
-+                Stripe; we never see or store your card details.
-               </div>
-               <div class="pb-2">
--                <div class="-ml-6">(c) Email:</div> The email you provide at
--                checkout is used to deliver your license key and to look up your
--                order.
-+                <div class="-ml-6">(j) What does not leave your Mac:</div> The
-+                hook and the bridge that connect your agents to The Nook are
-+                not a cloud service: the hook dials the bridge on your Mac, and
-+                the bridge only listens. Two paths carry agent data across the
-+                network, and both are switched on by you: if you add a remote
-+                machine, the hook on that machine dials this Mac over SSH or
-+                your tailnet; and if you use the phone connection, the session
-+                updates, approvals and replies described in (c) travel through
-+                the relay, sealed end to end. The privileged helper that
-+                controls fans and charging has no networking code at all.
-               </div>
-               <div class="pb-2">
--                <div class="-ml-6">(d) Payment:</div> Payments are processed by
--                Stripe. We never see or store your card details.
-+                <div class="-ml-6">The iPhone companion.</div> The iPhone and
-+                Apple Watch app is in TestFlight beta. The build in TestFlight
-+                starts Sentry on every launch, with no setting that turns it
-+                off: it sends crash, error and hang reports, session pings,
-+                performance traces, the app version, the iOS version, the
-+                iPhone model and your IP address. Those reports never include
-+                your prompts, code or session content.
-+                Its other network traffic is the phone connection in (c) — the
-+                relay, or a direct LAN/tailnet link — plus, if you allow
-+                notifications, the push token it gives the relay so Apple can
-+                deliver them.
-               </div>
-             </div>
-           </div>
-@@ -63,9 +192,11 @@ export default function NookPrivacyPolicy() {
-               <span class="-ml-4 pr-2">2.</span> How We Use It
-             </div>
-             <div class="pb-2 pl-4">
--              Device identifiers, your email, and license records are used only
--              to operate the trial, deliver purchases, and enforce the 3-device
--              license. We do not use them for advertising or sell them to anyone.
-+              Device identifiers, install IDs, your email and license records are
-+              used only to operate the trial and the licenses, to run the relay
-+              and the weather service, to answer bug reports, and to deliver
-+              purchases. We do not use them for advertising and we do not sell
-+              them to anyone.
-             </div>
-           </div>
- 
-@@ -74,9 +205,13 @@ export default function NookPrivacyPolicy() {
-               <span class="-ml-4 pr-2">3.</span> Data Security
-             </div>
-             <div class="pb-2 pl-4">
--              License keys are signed and verified with Ed25519. The connection
--              to our servers uses TLS. Your license key is stored in the macOS
--              Keychain on your Mac.
-+              License keys are signed and verified with Ed25519 and stored in
-+              the macOS Keychain. The session content your Mac and phone
-+              exchange is encrypted end-to-end with keys your devices generate
-+              at pairing; our relay holds no key that can read it, though it
-+              can read the routing metadata described in (c). Every internet
-+              connection described on this page uses TLS; the direct
-+              LAN/tailnet paths use the same end-to-end encryption.
-             </div>
-           </div>
- 

marketing/drafts/remote-ssh/copy.md

@@ -1,6 +1,9 @@
 # Remote SSH copy — HELD, do not publish
 
-**Status:** removed from the live site on 2026-10-29 in the FRE-323 correction.
+**Status:** removed from the `freno-dev` source on 2026-10-29 in the FRE-323
+correction, and **not yet off the live site** — the deploy is blocked on a write
+credential to `mikefreno/freno-dev` (card `82d1e1b7`). `nook.freno.me` still
+serves every sentence below until that push or a Vercel deploy lands.
 **Owner:** CMO. **Verified by:** CTO, on the FRE-320/FRE-205 work.
 **Restore only when:** FRE-320/FRE-205 ship a genuinely one-click install, the CTO
 verifies that flow, and a recording shows a remote agent joining the island.

marketing/drafts/remote-ssh/rationale.md

@@ -10,10 +10,12 @@ credential. FRE-315 and FRE-322 §3 correction 4 marked the remote claim
 unverified and demo-gated. The CTO named it the largest launch risk because it
 was already in front of buyers.
 
-So the landing page now says only what the product can back today: local agents,
-the card, and the notch. The remote story is not deleted — it is parked here with
-the FRE-320/FRE-205 work so it can return the day the one-click install ships and
-is recorded.
+So the `freno-dev` source now says only what the product can back today: local
+agents, the card, and the notch. That correction is committed locally and is
+**not deployed** — the live page still carries the remote sentences until the
+push in FRE-323 card `82d1e1b7` lands. The remote story is not deleted — it is
+parked here with the FRE-320/FRE-205 work so it can return the day the one-click
+install ships and is recorded.
 
 ## What has to be true before it returns
 

marketing/metrics/weekly.md

@@ -1,4 +1,43 @@
 # Weekly funnel snapshot
 
-Generated weekly from the analytics DB + `trials`/`licenses`/`activations`.
-Format: the funnel numbers, what moved, and the one thing worth acting on.
+Window: **2026-10-22 18:05:00 → 2026-10-29 18:05:00 UTC** (7 days). Previous: 2026-10-15 18:05:00 → 2026-10-22 18:05:00 UTC.
+
+Generated by `bun --env-file=.env scripts/weekly-metrics.ts`; regenerated weekly, never hand-edited. The analysis is the CMO's.
+
+## Funnel
+
+| Stage | This week | Last week | Change |
+|---|---:|---:|---:|
+| visit (nook.freno.me page views) | 0 | 0 | 0 |
+| download click | 0 | 0 | 0 |
+| DMG served | 0 | 0 | 0 |
+| trial started | 2 | 0 | +2 |
+| checkout started (Stripe session) | 0 | 0 | 0 |
+| purchase (licence issued) | 0 | 0 | 0 |
+| activation | 0 | 0 | 0 |
+
+## Campaigns
+
+Top 10 by volume, untagged excluded — the same grouping `getAnalyticsSummary.topCampaigns` returns.
+
+| Source | Medium | Campaign | Rows |
+|---|---|---|---:|
+| x | — | — | 1 |
+
+1 of 291 rows in the window carry campaign tags; the rest are untagged and therefore unattributed.
+
+## The one thing that moved
+
+**trial started: 0 → 2 (+2).**
+
+## Before acting on these numbers
+
+- **291 of 291 rows in the window predate the FRE-366 instrumentation.** They carry no host, and their recorded address is the production proxy's loopback (127.0.0.1 / ::1) — the writers then recorded the direct peer, not the visitor. They are excluded from every host-scoped stage above (visits, and the download click/served split), and "unique visitors" over them still collapses to one host. Rows recorded since carry the site they addressed and the visitor's address truncated to a prefix (/24, or /56 for IPv6 — the FRE-369 privacy floor), so "unique visitors" counts networks, not machines.
+- **Download rows are automation-heavy.** Of this window's 137 download rows, 0 are clicks and 0 are served files; the remaining 137 predate the click/served stage label and cannot be split, so they count in neither stage. 112 of all 137 are not browser user agents (curl, Sparkle, link-preview crawlers).
+- **No conversion rate before the cohort matures.** Trial→paid belongs to the mature Day 28–35 read (FRE-197); a ratio from a partial cohort is not a metric.
+
+## Sources
+
+- `VisitorAnalytics` (freno.me Turso DB) — visits, downloads, campaigns.
+- `trials`, `licenses`, `activations` (the-nook Turso DB) — the paid funnel.
+- Generated 2026-10-29T18:05:00Z.

marketing/positioning.md

@@ -4,13 +4,39 @@ Every drafted asset draws its voice, claims, and constraints from this file. If
 artifact invents its own framing, fix the artifact or fix this file — never both
 silently diverging.
 
-Primary source: `~/Code/the-nook/docs/marketing-strategy.md`.
+**Reconciled 2026-10-29**, and again **2026-11-03** for the FRE-997 count
+correction, against the CTO's verdicts ([FRE-315], [FRE-322], [FRE-354],
+[FRE-997]), the Chief of Staff's price decision (2026-10-29 04:01), the Plan B
+launch route ([FRE-346] → [FRE-203] `plan-b`), and `The-Nook` master (app floor is
+**14.2**, not 14.0 — `freno-dev` `881190d`, site merge `134f41e`). The previous
+version of this file named an upstream `the-nook/docs/marketing-strategy.md` that
+no longer exists; the verdicts below are the source of truth it was pointing at.
+
+[FRE-315]: https://paperclip.freno.me/FRE/issues/FRE-315
+[FRE-322]: https://paperclip.freno.me/FRE/issues/FRE-322
+[FRE-354]: https://paperclip.freno.me/FRE/issues/FRE-354
+[FRE-320]: https://paperclip.freno.me/FRE/issues/FRE-320
+[FRE-346]: https://paperclip.freno.me/FRE/issues/FRE-346
+[FRE-203]: https://paperclip.freno.me/FRE/issues/FRE-203
+[FRE-997]: https://paperclip.freno.me/FRE/issues/FRE-997
 
 ## The sentence
 
-> **Your Mac and your agents, under control.** The Nook puts your whole coding-agent
-> fleet in the notch — thirteen agents — so you see what is running,
-> unblock it in one tap, and keep the machine from overheating while it works.
+There is no single approved public sentence yet, and saying otherwise is the one
+mistake this file exists to prevent. What exists is a **launch claim set** — two
+sentences, both from one 15-second take, recorded as the chosen route by the Chief
+of Staff on 2026-10-29 ([FRE-346] `decision` §2–§4):
+
+| Slot | Exact sentence | Status today |
+|---|---|---|
+| Launch line | **"Every agent you're running reports into one notch, and the one waiting on you pins above the rest."** | Verified by code ([FRE-322] §3). Needs the one-Mac take before it is publishable. |
+| Second line, same take | **"Approve an agent's tool call from your Mac's notch, and the agent carries on."** | Needs the demo ([FRE-322] §1). The same take settles it. |
+
+Working line for internal writing, not for publication:
+
+> **Your Mac and your agents, under control.** One notch for the whole fleet: you
+> see what is running, you unblock what is waiting, and the machine stays cool
+> while it works.
 
 ## The wedge
 
@@ -22,15 +48,18 @@ The thing to say over and over, in every channel, in slightly different words:
 It is acute, quantifiable, and true — and it is the demo: a card appears, you tap
 Allow, work resumes. Ten seconds, no explanation needed.
 
-## The bundling reframe
+## The consolidation reframe
 
 Three audiences (agent herders, hardware tinkerers, glanceable-widget users) in one
-$10 app reads like a grab bag. Reframe as consolidation, which is the honest story:
+app reads like a grab bag. Reframe as consolidation, which is the honest story:
 
-> One $10 app instead of a notch toy, a fan utility, a battery limiter, a menu-bar
-> stats strip, and a notification hack. Same one-time purchase, no subscription.
+> One app instead of a notch toy, a fan utility, a battery limiter, a menu-bar stats
+> strip, and a notification hack. One purchase, no subscription.
 
-Price rises to $15 at 1.0 — dated and honest, not a permanent beta.
+**No price, no discount and no future price in copy.** The price is $10, it stays
+$10, and the dated rise to $15 is withdrawn (Chief of Staff, 2026-10-29 04:01). A
+price change is a Chief of Staff + sponsor call; it is never a marketing decision
+and never a launch asset.
 
 ## Hard rules
 
@@ -48,30 +77,49 @@ pages, marketing copy, comparison tables, meta descriptions, emails, FAQs, all o
   community replies written by a human, where quoting what a user said about another
   tool is normal conversation.
 
-### 2. A claim requires a test to exist
+### 2. A claim needs a verdict, not just a test
 
-Copy that says "13 agents" or "no data leaves the device" must have a test backing it.
-If a claim cannot be pointed at code or a test, it does not go in copy.
+Copy that says "every agent", "13 agents", "no data leaves the device" must point at
+both a test **and** a CTO verdict naming the exact sentence. A passing test is not a
+verdict; a verdict is not a recording. If a sentence cannot be traced to a row in the
+tables below, it does not go in copy.
 
 ### 3. Honest privacy scoping
 
-Telemetry and the trial email **do** leave the device. The defensible claim is:
+Telemetry and the licence check **do** leave the device: Sentry runs on **every
+launch, unconditionally** (with the Mac's IP address via `sendDefaultPii`), and the
+trial check sends `IOPlatformUUID` and the device name to `freno.me` ([FRE-322]
+§2.4, corrected by [FRE-354] `(b)`). Never publish, in any wording:
 
-> **No prompt or code content leaves the device.**
+- "no data leaves the device" / "local-only" / "no telemetry" / "no account"
+- "nothing leaves your Mac"
 
-Never "no data leaves the device".
+The one favourable engine sentence — about the **hook and bridge only**, never
+"The Nook" — as corrected by [FRE-354] `(j)`: the hook and bridge **are not a cloud
+service**. Do not write "talk to nothing but your Mac" (too absolute: the
+`NOOK_PORTS` fan-out resolves `host.docker.internal` and the default gateway, and
+`defaultGateway()` opens a no-packet UDP socket to `8.8.8.8:80`), and do not narrow
+it to "over SSH" (a tailnet peer dials directly).
+
+It is verified as a code fact ([FRE-322] §2, [FRE-354] `(j)`), and it is still
+**held** until the disclosures land: Sentry gated behind a preference or removed,
+and `/privacy` + `/faq` corrected against the egress inventory (patch on branch
+`faq/from-objections-2026-10-29`, verified by [FRE-354]). A true sentence next to
+false ones is worse than no sentence.
 
 ### 4. Sell what works today
 
-Phone approvals are deferred until a shipped iOS app exists — no "(coming soon)"
-parentheticals. The launch story is the approval card: an agent blocked on a
-permission prompt, unblocked from the Mac's notch, and work resumes.
+An iPhone + Apple Watch companion **is** in users' hands as a TestFlight beta
+(`ios-v0.3.2`, 2026-10-22; [FRE-354] open question). That makes one thing true and
+one thing forbidden: say "TestFlight beta" when the phone exists in a sentence at
+all, and never claim approvals-from-phone as a shipped capability without its own
+CTO verdict — no "(coming soon)" parentheticals either way.
 
-Remote SSH is **held**, not approved. The one-click install has not shipped and
-has not been recorded (FRE-320, FRE-205), and the current path needs hand-edited
-`~/.ssh/config` and a one-time `ssh-copy-id` (FRE-320). Its copy is parked in
-`marketing/drafts/remote-ssh/` until the CTO verifies the shipping flow and a
-demo exists.
+Remote SSH is **held**, not approved: the one-click install has not
+been verified end to end ([FRE-315] §1) and the shipped path needs hand-edited
+`~/.ssh/config` and a one-time `ssh-copy-id` ([FRE-320]). Its copy stays parked in
+`marketing/drafts/remote-ssh/` until the CTO verifies the shipping flow **and** a
+recording shows a remote agent joining the notch.
 
 ### 5. Humans hold every account
 
@@ -79,28 +127,30 @@ No agent authenticates, posts, upvotes, or DMs. No sock puppets, no self-mention
 without disclosure. `approved/` **is the only thing a human ever publishes from** —
 nothing posts itself.
 
-## Approved claims (each backed by code)
+## Claims: status at 2026-11-03
 
-| Claim | Backing |
-|---|---|
-| Thirteen hooked agents, one glance | `AgentSpec.all` — claude, codex, opencode, pi, omp, muse, hermes, openclaw, zai, gemini, cline, qwen, deepseek |
-| Permission gate answered from a card | awaitPolicyTable + bridge directive path (`hook/normalize.go`, `serialize.go`) |
-| Fan / thermal / charge control | `helper/` (privileged helper, SMC, no kext) |
-| One-time purchase, no subscription | $10 → $15 at 1.0; Stripe checkout |
-| macOS 14+ | 27 source files use the `@Observable` framework |
-| No prompt or code content leaves the device | envelope carries session/event/terminal metadata only (see `docs/agent-interface.md`) |
+Each row names the evidence, not a feeling. Re-read the verdict before using a row.
 
-## Held claims (not publishable)
-
-| Claim | Why it is held | What has to be true first |
+| Claim | Status | Evidence / next step |
 |---|---|---|
-| Remote agents over SSH, one click to install | The one-click path is app-UI-only and needs hand-edited `~/.ssh/config` plus a one-time `ssh-copy-id`; no demo exists (FRE-320). FRE-315 and FRE-322 hold it unverified and demo-gated. | FRE-320/FRE-205 ship a genuinely one-click install, the CTO verifies it, and a recording shows a remote agent joining the island. Copy parked in `marketing/drafts/remote-ssh/`. |
+| Approve an agent's tool call from the notch, and it carries on | **Needs demo** — not publishable | [FRE-322] §1. `AgentLiveTurnTests` has never run on a signed-in host; one observed local run settles it. Say "an agent", never "any agent", never "always". |
+| Every agent you're running reports into one notch; the blocked one pins above the rest | **Verified by code, gated on the take** | [FRE-322] §3. Same one-Mac take as above. No count in the sentence. |
+| The hook and bridge are not a cloud service | **Verified code fact, held on disclosure** | [FRE-322] §2, wording corrected by [FRE-354] `(j)`. Held until Sentry is gated/removed and `/privacy` + `/faq` land. Never widen to "The Nook", never "nothing but your Mac". |
+| Fan, thermal and charge control | **No claim verdict yet — do not lead with it** | Backed by `helper/` (privileged helper, SMC, no kext), but no CTO sentence exists for it. Documentary, not launch. |
+| One-time purchase, no subscription | **Publishable fact, price not a launch asset** | $10, held at $10. No dated rise, no discount framing, no pricing copy. |
+| Agent coverage numbers ("eighteen agents", "18 agents") | **Publishable at 18** | [FRE-997]: the /agents table now lists every row of `AgentSpec.all` and `agents.test.ts` asserts equality with the 18-name registry in registry order, so the landing bullet, the marquee chip and the /agents copy say 18. No other number is publishable. |
+| macOS 14.2 or later | **Publishable fact** | The app cannot start below 14.2 (`freno-dev` `881190d`, site `134f41e`). "macOS 14+" is false and was fixed on the site. |
+| Remote agents over SSH, one click to install | **Held** | [FRE-315] §1, [FRE-320], [FRE-323]. Needs a verified one-click install plus a recording. |
+| "Nothing leaves your Mac", "no telemetry", "local-only", "no account" | **False today — banned** | Sentry unconditional, licence check with hardware fingerprint ([FRE-322] §2.4). |
+| Approvals from the iPhone or Apple Watch | **No verdict — not a launch claim** | The companion is a TestFlight beta ([FRE-354]); the approval-from-phone claim has no CTO verdict and stays out of launch copy. |
 
 ## Voice
 
-- Short, concrete, no hype adjectives. Numbers over adjectives ("thirteen agents",
-  "one tap", "$10 once").
-- The notch/island is the product's home; agents are the product's point.
+- Short, concrete, no hype adjectives. Numbers over adjectives — the only count
+  that ships is eighteen, and it is the registry's own size (see the coverage row
+  above).
+- The notch is the product's home; agents are the product's point.
 - Never apologize for being a utility. The utility is the point.
 - Banned phrasings: competitor names (see rule 1), "AI-powered", "revolutionary",
-  "game-changer", "seamlessly". Unverifiable superlatives generally.
+  "game-changer", "seamlessly", any unverifiable superlative — and the specific
+  banned sentences in rule 3 and the table above.

package.json

@@ -12,6 +12,7 @@
     "test:coverage": "bun test --coverage",
     "perf": "bun run scripts/perf-test.ts",
     "perf:compare": "bun run scripts/perf-compare.ts",
+    "metrics:weekly": "bun --env-file=.env scripts/weekly-metrics.ts",
     "nook:grant": "NODE_ENV=production bun --env-file=.env scripts/grant-nook-license.ts"
   },
   "dependencies": {

scripts/weekly-metrics.ts

@@ -0,0 +1,159 @@
+import { createClient } from "@libsql/client/web";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import {
+  ensureAnalyticsSchema,
+  getWeeklyReport,
+  renderWeeklyMarkdown,
+  type Connections
+} from "~/server/weekly-metrics";
+
+/**
+ * Write `marketing/metrics/weekly.md` from the live analytics and licence DBs.
+ *
+ *   bun --env-file=.env scripts/weekly-metrics.ts
+ *   bun --env-file=.env scripts/weekly-metrics.ts --days 14 --now 2026-11-05T09:00:00Z
+ *
+ * Required environment (all four; the analytics token also opens the licence
+ * DB, which is why the weekly job can run from a checkout that has no Stripe
+ * or Apple secrets):
+ *
+ *   TURSO_DB_URL / TURSO_DB_TOKEN        freno.me DB — VisitorAnalytics
+ *   NOOK_DB_URL / NOOK_DB_TOKEN          the-nook DB — trials, licenses, activations
+ *
+ * This script deliberately does not import `~/env/server`: that schema demands
+ * every production secret, and the metrics job needs two databases and nothing
+ * else.
+ *
+ * The output path is anchored at the repo root, so running it from any cwd
+ * writes the same file.
+ */
+
+interface Options {
+  days: number;
+  now: Date;
+  out: string;
+  stdout: boolean;
+}
+
+function usage(): string {
+  return [
+    "Usage: bun --env-file=.env scripts/weekly-metrics.ts [options]",
+    "",
+    "  --days N          window length in days (default 7)",
+    "  --now ISO         end of the window (default: now)",
+    "  --out PATH        where to write (default: marketing/metrics/weekly.md)",
+    "  --stdout          print the report instead of writing a file"
+  ].join("\n");
+}
+
+function parseArgs(argv: string[]): Options {
+  const repoRoot = resolve(import.meta.dir, "..");
+  const options: Options = {
+    days: 7,
+    now: new Date(),
+    out: resolve(repoRoot, "marketing/metrics/weekly.md"),
+    stdout: false
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]!;
+    const value = () => {
+      const next = argv[i + 1];
+      if (next === undefined) throw new Error(`${arg} needs a value\n\n${usage()}`);
+      i += 1;
+      return next;
+    };
+
+    switch (arg) {
+      case "--days": {
+        const days = Number(value());
+        if (!Number.isFinite(days) || days <= 0) {
+          throw new Error(`--days must be a positive number\n\n${usage()}`);
+        }
+        options.days = days;
+        break;
+      }
+      case "--now": {
+        const now = new Date(value());
+        if (Number.isNaN(now.getTime())) {
+          throw new Error(`--now must be an ISO timestamp\n\n${usage()}`);
+        }
+        options.now = now;
+        break;
+      }
+      case "--out":
+        options.out = resolve(value());
+        break;
+      case "--stdout":
+        options.stdout = true;
+        break;
+      case "-h":
+      case "--help":
+        console.log(usage());
+        process.exit(0);
+      default:
+        throw new Error(`Unknown argument ${arg}\n\n${usage()}`);
+    }
+  }
+
+  return options;
+}
+
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (!value || value.trim() === "") {
+    throw new Error(
+      `${name} is not set. The weekly job needs TURSO_DB_URL, TURSO_DB_TOKEN, ` +
+        `NOOK_DB_URL and NOOK_DB_TOKEN — run it as ` +
+        `\`bun --env-file=.env scripts/weekly-metrics.ts\` with those four in .env.`
+    );
+  }
+  return value;
+}
+
+function connect(url: string, token: string) {
+  return createClient({ url, authToken: token });
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+
+  const connections: Connections = {
+    analytics: connect(requiredEnv("TURSO_DB_URL"), requiredEnv("TURSO_DB_TOKEN")),
+    nook: connect(requiredEnv("NOOK_DB_URL"), requiredEnv("NOOK_DB_TOKEN"))
+  };
+
+  // The app migrates the table on boot, but this job must not depend on a
+  // deploy having happened: add any missing post-hoc columns (stage, host)
+  // through the same idempotent bootstrap path first.
+  await ensureAnalyticsSchema(connections.analytics);
+
+  const report = await getWeeklyReport(connections, {
+    days: options.days,
+    now: options.now
+  });
+  const markdown = renderWeeklyMarkdown(report);
+
+  if (options.stdout) {
+    process.stdout.write(markdown);
+    return;
+  }
+
+  await mkdir(dirname(options.out), { recursive: true });
+  await writeFile(options.out, markdown, "utf8");
+
+  const f = report.counts;
+  console.log(
+    `wrote ${options.out}\n` +
+      `window ${report.window.start} → ${report.window.end}\n` +
+      `visit ${f.visit}, download click ${f.downloadClick}, DMG served ${f.dmgServed}, ` +
+      `trial ${f.trial}, checkout ${f.checkout}, purchase ${f.purchase}, activation ${f.activation}\n` +
+      `mover: ${report.mover ? `${report.mover.label} ${report.mover.before} → ${report.mover.now}` : "none"}`
+  );
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});

src/components/nook/FeatureBreakdowns.tsx

@@ -851,7 +851,7 @@ export default function FeatureBreakdowns() {
         title="Your whole fleet, in one pixel strip"
         body="Every session, every agent, one square each. The pill never wraps, never grows — an arriving question flashes the fire and swaps the slot, then hands the notch back."
         bullets={[
-          "13 agents: Claude Code, Codex, Gemini CLI, OpenCode, Pi, Muse, and more",
+          "18 agents: Claude Code, Codex, Gemini CLI, OpenCode, Pi, Muse, and more",
           "Custom agents: your own coding agent can wire itself in from the published contract",
           "Slot rankings — you choose which data earns the notch",
           "You don't need a notch — external displays get the same island, floating top-center"

src/components/nook/IslandExtras.tsx

@@ -722,7 +722,7 @@ function LayoutMock() {
 /* ── Marquee ─────────────────────────────────────────────────────── */
 
 const CHIPS_A = [
-  "13 agents",
+  "18 agents",
   "Custom agents",
   "Six chiptunes",
   "Focus-aware slots",

src/db/types.ts

@@ -160,6 +160,8 @@ export interface VisitorAnalytics {
   ttfb?: number | null;
   dom_load?: number | null;
   load_complete?: number | null;
+  stage?: string | null;
+  host?: string | null;
   created_at: string;
 }
 

src/env/server.ts

@@ -69,6 +69,12 @@ const serverEnvSchema = z.object({
   // Bearer secret for the daily lifecycle-email cron. Falls back to
   // Vercel's CRON_SECRET; unset + no CRON_SECRET = the endpoint denies all.
   NOOK_LIFECYCLE_SECRET: z.string().min(1).optional(),
+  // Daily VisitorAnalytics retention cron (/api/analytics-retention). Same
+  // shape: falls back to CRON_SECRET, and unset denies every request.
+  ANALYTICS_RETENTION_SECRET: z.string().min(1).optional(),
+  // How long a VisitorAnalytics row lives. Unset (or unusable) = 365 days;
+  // see src/server/analytics-retention.ts before shortening it.
+  ANALYTICS_RETENTION_DAYS: z.string().optional(),
   CRON_SECRET: z.string().min(1).optional()
 });
 

src/routes/api/analytics-retention.ts

@@ -0,0 +1,35 @@
+import type { APIEvent } from "@solidjs/start/server";
+import { env } from "~/env/server";
+import { ConnectionFactory } from "~/server/db-connections";
+import { runRetentionCron } from "~/server/analytics-retention";
+
+/**
+ * GET /api/analytics-retention — daily Vercel cron.
+ *
+ * Deletes `VisitorAnalytics` rows older than the retention window, so visitor
+ * data has a bound instead of accumulating forever (FRE-369, finding Q4 — the
+ * table's only cleaner used to be a manual admin call, and since FRE-366 the
+ * rows carry a truncated but still real client address).
+ *
+ * Window: `ANALYTICS_RETENTION_DAYS`, defaulting to 365 when unset or unusable
+ * (see `~/server/analytics-retention` for why the default is conservative
+ * rather than the reviewer's 90).
+ *
+ * Auth: `Authorization: Bearer <secret>` where the secret is
+ * `ANALYTICS_RETENTION_SECRET` or Vercel's `CRON_SECRET`. An unconfigured secret
+ * denies every request — an unauthenticated trigger of a bulk delete is the one
+ * outcome this endpoint must never have.
+ */
+export async function GET(event: APIEvent) {
+  const result = await runRetentionCron({
+    authorization: event.request.headers.get("authorization"),
+    secret: env.ANALYTICS_RETENTION_SECRET ?? env.CRON_SECRET,
+    configuredDays: env.ANALYTICS_RETENTION_DAYS,
+    conn: ConnectionFactory()
+  });
+
+  return new Response(JSON.stringify(result.body), {
+    status: result.status,
+    headers: { "Content-Type": "application/json" }
+  });
+}

src/routes/api/downloads/[filename].ts

@@ -95,7 +95,7 @@ export async function GET(event: APIEvent) {
 
     console.log(`✓ Serving ${filename} (${body.length} bytes)`);
 
-    await trackDownload(event, assetKeys[asset]!);
+    await trackDownload(event, assetKeys[asset]!, "served");
 
     // SAFETY: `transformToByteArray` yields `Uint8Array<ArrayBufferLike>`, which the
     // DOM lib's `BufferSource` (ArrayBuffer-backed) does not accept, though undici

src/routes/api/the-nook/checkout.ts

@@ -3,6 +3,7 @@ import { env } from "~/env/server";
 import { TURNSTILE_CONFIG } from "~/config";
 import { verifyTurnstileToken } from "~/server/fetch-utils";
 import { json, error } from "./_lib";
+import { trackRequest } from "~/server/track-download";
 
 /**
  * POST /api/the-nook/checkout
@@ -12,6 +13,14 @@ import { json, error } from "./_lib";
  * session for the one-time $10 The Nook license. Returns the hosted
  * checkout URL for the client to redirect to.
  *
+ * Analytics: a created session is the funnel's "checkout started" stage
+ * (FRE-366). Until then the only trace was the client-side /checkout page
+ * view — a page, not a started checkout. Recorded through the shared
+ * `trackRequest` writer (referrer, campaign tags, country, real client
+ * address, host) under this route's own path, best-effort: a failed
+ * analytics write never blocks a checkout, and an attempt Turnstile or
+ * Stripe rejects is correctly not a started checkout.
+ *
  * Uses raw `fetch` (Node 24 / Vercel Node functions have global fetch) — no
  * `stripe` npm dependency added.
  */
@@ -67,5 +76,14 @@ export async function POST(event: APIEvent) {
   if (!data.url) {
     return error("Stripe returned no checkout URL", 502);
   }
+
+  // The session exists: that is "checkout started". Awaited so the row is
+  // flushed before the response — a buffered write is not guaranteed to
+  // survive the response on serverless.
+  await trackRequest(event, {
+    path: "/api/the-nook/checkout",
+    method: "POST"
+  });
+
   return json({ checkoutUrl: data.url });
 }

src/routes/api/the-nook/download.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, mock, beforeEach } from "bun:test";
+import { truncateIpAddress } from "~/server/request-client";
 
 // The route's contracts:
 //   1. Every click is recorded through the shared analytics buffer with the
@@ -55,9 +56,13 @@ mock.module("~/server/analytics", () => ({
   flushAnalytics: async () => {
     flushCalls += 1;
   },
-  // Mirrors the real enrichment contract: deviceType is derived from the UA.
+  // Mirrors the real enrichment contract: deviceType is derived from the UA,
+  // and the address is cut to its prefix by the FRE-369 privacy floor. The
+  // real `enrichAnalyticsEntry` does both, so the mirror has to apply the same
+  // truncation — otherwise this file would prove the door stores a full address.
   enrichAnalyticsEntry: (entry: Entry) => ({
     ...entry,
+    ipAddress: truncateIpAddress(entry.ipAddress as string | null),
     deviceType: String(entry.userAgent ?? "").includes("Macintosh")
       ? "desktop"
       : null
@@ -113,6 +118,10 @@ describe("GET /api/the-nook/download", () => {
     expect(logged[0]).toMatchObject({
       path: "/api/downloads/thenook",
       method: "GET",
+      // The door is the click half of the split; the file route writes
+      // "served". And the row names the site it came from (FRE-366).
+      stage: "click",
+      host: "nook.freno.me",
       referrer: "https://nook.freno.me/"
     });
     // Flushed within the request, not left to the batch timer.
@@ -137,9 +146,16 @@ describe("GET /api/the-nook/download", () => {
     expect(logged[2]!.country).toBe("JP");
   });
 
-  it("falls back to the forwarded address when no request IP is available", async () => {
-    await GET(request({ "x-forwarded-for": "198.51.100.9, 10.0.0.1" }));
-    expect(logged[0]!.ipAddress).toBe("198.51.100.9");
+  it("records the forwarded visitor below the trusted edge, truncated", async () => {
+    // Client → Cloudflare → origin proxy: the sender's spoof is first, the real
+    // client second, the edge last. And the stored value is the /24, never the
+    // address itself (FRE-369).
+    await GET(
+      request({
+        "x-forwarded-for": "198.51.100.9, 203.0.113.7, 198.51.100.1"
+      })
+    );
+    expect(logged[0]!.ipAddress).toBe("203.0.113.0");
   });
 
   it("still logs the click when the appcast cannot be read", async () => {

src/routes/api/the-nook/download.ts

@@ -13,8 +13,10 @@ import { resolveLatestDownload } from "./_download";
  * Why a redirect and not a direct S3 link: the appcast route and the DMG
  * route never logged anything, so step 2 of the funnel (download click →
  * DMG served) was invisible. Every click now lands one row in
- * VisitorAnalytics under `/api/downloads/thenook`, alongside the clicks and
- * served files of every other product — see `~/server/track-download`.
+ * VisitorAnalytics under `/api/downloads/thenook` with `stage = "click"`,
+ * distinct from the `stage = "served"` row the file route writes when the
+ * DMG is actually streamed — the split FRE-366 added, alongside the clicks
+ * and served files of every other product — see `~/server/track-download`.
  *
  * Referrer, campaign tags, edge country (with `?c=` override) and user agent
  * are read by `trackDownload`, which is shared with the other download doors.
@@ -28,7 +30,7 @@ import { resolveLatestDownload } from "./_download";
 export async function GET(event: APIEvent): Promise<Response> {
   // Recorded before resolving: a click that dies at resolution is exactly the
   // failure the funnel needs to show.
-  await trackDownload(event, "thenook");
+  await trackDownload(event, "thenook", "click");
 
   let target: string | null = null;
   try {

src/routes/api/the-nook/report.test.ts

@@ -10,6 +10,8 @@ import { describe, expect, it, mock, beforeEach } from "bun:test";
 
 const sentEmails: { to: string; subject: string; html: string }[] = [];
 const tokenAnswers: { allowed: boolean; retryAfterSec?: number }[] = [];
+/** Every rate-limit key the route derived, in order. */
+const rateKeys: string[] = [];
 
 mock.module("~/server/email", () => ({
   default: async (to: string, subject: string, html: string) => {
@@ -19,7 +21,10 @@ mock.module("~/server/email", () => ({
 }));
 
 mock.module("~/server/bug-report-rate-limit", () => ({
-  takeBugReportToken: () => tokenAnswers.shift() ?? { allowed: true }
+  takeBugReportToken: (key: string) => {
+    rateKeys.push(key);
+    return tokenAnswers.shift() ?? { allowed: true };
+  }
 }));
 
 const { POST } = await import("./report");
@@ -72,6 +77,7 @@ describe("POST /api/the-nook/report", () => {
   beforeEach(() => {
     sentEmails.length = 0;
     tokenAnswers.length = 0;
+    rateKeys.length = 0;
   });
 
   it("emails the owner a report containing the snapshot, escaped", async () => {
@@ -133,10 +139,49 @@ describe("POST /api/the-nook/report", () => {
 
   it("still succeeds when no fingerprint header exists", async () => {
     const res = await POST(
-      request(validPayload, { "x-forwarded-for": "203.0.113.9, 10.0.0.1" })
+      request(validPayload, {
+        "cf-connecting-ip": "203.0.113.9",
+        "x-forwarded-for": "203.0.113.9, 10.0.0.1"
+      })
     );
     expect(res.status).toBe(200);
     expect(sentEmails).toHaveLength(1);
+    // The quota key is the Cloudflare-recorded client, not a header hop the
+    // sender chose.
+    expect(rateKeys).toEqual(["203.0.113.9"]);
+  });
+
+  it("a rotating leftmost x-forwarded-for does not mint a fresh quota key", async () => {
+    // FRE-371: the old read keyed on the leftmost hop, which the sender
+    // controls outright — one scripted loop with a rotating header had
+    // unlimited reports. With the same Cloudflare-recorded client and a
+    // different spoofed prefix per request, the key must be stable.
+    for (const spoof of ["1.1.1.1", "2.2.2.2", "3.3.3.3"]) {
+      const res = await POST(
+        request(validPayload, {
+          "cf-connecting-ip": "203.0.113.9",
+          "x-forwarded-for": `${spoof}, 203.0.113.9, 10.0.0.1`
+        })
+      );
+      expect(res.status).toBe(200);
+    }
+
+    expect(rateKeys).toEqual([
+      "203.0.113.9",
+      "203.0.113.9",
+      "203.0.113.9"
+    ]);
+  });
+
+  it("keys on the rightmost-minus-one hop when Cloudflare's header is absent", async () => {
+    const res = await POST(
+      request(validPayload, {
+        "x-forwarded-for": "6.6.6.6, 203.0.113.9, 10.0.0.1"
+      })
+    );
+    expect(res.status).toBe(200);
+    // Never the leftmost (sender-chosen) hop.
+    expect(rateKeys).toEqual(["203.0.113.9"]);
   });
 
   it("delivers the landing page's beta request with only the email", async () => {

src/routes/api/the-nook/report.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import sendEmail from "~/server/email";
 import { CONTACT_RECIPIENT_EMAIL } from "~/lib/contact-config";
 import { takeBugReportToken } from "~/server/bug-report-rate-limit";
+import { resolveTrustedClientIp } from "~/server/trusted-client-ip";
 import { json, error } from "./_lib";
 
 /**
@@ -103,10 +104,9 @@ export async function POST(event: APIEvent): Promise<Response> {
   )
     .trim()
     .toLowerCase();
-  const forwarded = event.request.headers.get("x-forwarded-for");
-  const rateKey =
-    fingerprint ||
-    (forwarded ? forwarded.split(",")[0]!.trim() : "unknown");
+  // FRE-371: the IP fallback must be the spoof-resistant read — a rotating
+  // leftmost x-forwarded-for used to mint unlimited report quota.
+  const rateKey = fingerprint || resolveTrustedClientIp(event);
   const token = takeBugReportToken(rateKey);
   if (!token.allowed) {
     return new Response(JSON.stringify({ error: "Too many reports" }), {

src/routes/nook/agents.test.ts

@@ -1,5 +1,5 @@
 /**
- * Regression test for the /agents roster (NOOK-336).
+ * Regression test for the /agents roster and its coverage count.
  *
  * The page mirrors the app's registry, `AgentSpec.all` in
  * the-nook/Sources/NookCore/Agents/AgentRegistry.swift. When Muse joined
@@ -8,6 +8,12 @@
  * them. The registry lives in another repo, so the expected roster is
  * restated here; when an agent is added there, add it here and on the page.
  *
+ * FRE-997 restored the count. The page said thirteen while the registry held
+ * eighteen, so the count was dropped rather than corrected (FRE-359 verdict B);
+ * now that all eighteen rows are on the page, the roster check is an equality
+ * check again and the page states eighteen. A subset check would let a shipped
+ * agent go missing behind a passing suite, which is the NOOK-336 failure.
+ *
  * STATIC SOURCE AUDIT, the same pattern as the downloads regressions.
  */
 import { describe, it, expect } from "bun:test";
@@ -16,7 +22,10 @@ import { join } from "node:path";
 
 const SOURCE = readFileSync(join(import.meta.dir, "agents.tsx"), "utf8");
 
-/** AgentSpec.all display names, in registry order. */
+/** User-facing copy only: comments are not copy and may name the old wording. */
+const COPY = SOURCE.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+
+/** AgentSpec.all display names, in registry order (18 rows). @ The-Nook f4258034, 2026-10-29 */
 const REGISTRY = [
   "Claude Code",
   "Codex",
@@ -30,25 +39,31 @@ const REGISTRY = [
   "Gemini CLI",
   "Cline",
   "Qwen Code",
-  "DeepSeek"
+  "DeepSeek",
+  "Kimi",
+  "GitHub Copilot CLI",
+  "Crush",
+  "Cursor",
+  "Amp"
 ];
 
-const NUMBER_WORDS = ["twelve", "thirteen", "fourteen", "fifteen"];
-
 const entries = [...SOURCE.matchAll(/^\s{4}name: "([^"]+)",$/gm)].map((m) => m[1]);
 
-describe("Nook /agents roster (NOOK-336)", () => {
-  it("lists every registry agent, in registry order", () => {
+describe("Nook /agents roster", () => {
+  it("lists every registry agent, once, in registry order", () => {
     expect(entries).toEqual(REGISTRY);
   });
 
-  it("states the same count everywhere it names one", () => {
-    const word = NUMBER_WORDS[entries.length - 12];
-    for (const other of NUMBER_WORDS.filter((w) => w !== word)) {
-      expect(SOURCE.toLowerCase()).not.toContain(other);
-    }
-    expect(SOURCE).toContain(`all ${word}`);
-    expect(SOURCE).toContain(`The ${entries.length} agents`);
-    expect(SOURCE).toContain(`watches ${word} coding agents`);
+  it("states the registry's size", () => {
+    expect(entries.length).toBe(18);
+    expect(COPY).toContain("all eighteen");
+    expect(COPY).toContain("The 18 agents");
+    expect(COPY).toContain("eighteen coding agents");
+  });
+
+  it("carries no stale count", () => {
+    expect(COPY.toLowerCase()).not.toContain("thirteen");
+    expect(COPY).not.toMatch(/\b13 agents\b/);
+    expect(COPY).not.toContain("all thirteen");
   });
 });

src/routes/nook/agents.tsx

@@ -1,9 +1,10 @@
 /**
- * `/agents` on the Nook subdomain — supported agents and their event coverage.
+ * `/agents` on the Nook subdomain — all eighteen agents in the registry and
+ * each row's event coverage.
  *
  * The registry below mirrors `AgentSpec.all` in the app
- * (~/Code/the-nook/Sources/NookCore/Agents/AgentSpec.swift) and each agent's
- * installed hook surface (hook/setup.go) or plugin event subscription
+ * (~/Code/the-nook/Sources/NookCore/Agents/AgentRegistry.swift) and each
+ * agent's installed hook surface (hook/setup.go) or plugin event subscription
  * (plugins/*), normalized onto the shared event vocabulary
  * (~/Code/the-nook/docs/agent-interface.md). Copy follows
  * marketing/positioning.md: category nouns, honest scoping, no unverifiable
@@ -259,6 +260,92 @@ const AGENTS: AgentEntry[] = [
     ],
     gating:
       "Tool calls can be allowed or denied from a card; permission prompts stay with the agent"
+  },
+  {
+    name: "Kimi",
+    wiring: "Hook rules in its TOML config, one per event",
+    events: [
+      "SessionStart",
+      "SessionEnd",
+      "UserPromptSubmit",
+      "AgentStart",
+      "PreToolUse",
+      "PermissionRequest",
+      "PermissionResolved",
+      "PostToolUse",
+      "PostToolUseFailure",
+      "Stop",
+      "SessionError",
+      "SubagentStart",
+      "SubagentStop",
+      "PreCompact",
+      "Notification"
+    ],
+    gating:
+      "Observation — every event appears as a card; its PreToolUse fires before its own permission check, so the agent keeps its own prompting"
+  },
+  {
+    name: "GitHub Copilot CLI",
+    wiring: "One hook file of ours in its hooks directory",
+    events: [
+      "SessionStart",
+      "SessionEnd",
+      "UserPromptSubmit",
+      "PreToolUse",
+      "PermissionRequest",
+      "PostToolUse",
+      "PostToolUseFailure",
+      "Stop",
+      "SubagentStart",
+      "SubagentStop",
+      "ErrorOccurred",
+      "PreCompact",
+      "Notification"
+    ],
+    gating:
+      "Observation — every event appears as a card; its permission request runs before its own policy check, so the agent keeps its own prompting"
+  },
+  {
+    name: "Crush",
+    wiring:
+      "One entry in its JSONC config, the only event it documents",
+    events: ["PreToolUse"],
+    gating:
+      "Observation — tool calls appear as cards; its own permission prompts decide"
+  },
+  {
+    name: "Cursor",
+    wiring:
+      "Hook entries in its hooks.json, merged with your own. No permission hook, on purpose",
+    events: [
+      "SessionStart",
+      "SessionEnd",
+      "UserPromptSubmit",
+      "PostToolUse",
+      "PostToolUseFailure",
+      "Stop",
+      "SessionError",
+      "AfterAgentResponse",
+      "SubagentStop",
+      "PreCompact"
+    ],
+    gating:
+      "Observation — a permission hook that stays silent blocks the action here, so Cursor keeps its own prompting"
+  },
+  {
+    name: "Amp",
+    wiring: "In-process extension package",
+    events: [
+      "SessionStart",
+      "SessionEnd",
+      "UserPromptSubmit",
+      "PreToolUse",
+      "PostToolUse",
+      "Stop",
+      "SessionError"
+    ],
+    gating:
+      "Observation — its plugin API has no permission-wait event, so the agent keeps its own prompting"
   }
 ];
 
@@ -283,8 +370,8 @@ export default function NookAgentsPage() {
       <EdgeCacheHeaders maxAge={300} />
       <PageHead
         title="Supported agents"
-        description="Every coding agent The Nook supports — all thirteen, with each hook's exact event coverage and what you can do from a card: watch sessions live, answer permission prompts, unblock work."
-        ogTitle="The 13 agents The Nook supports, and what each hook sees"
+        description="Every coding agent The Nook supports — all eighteen, with each hook's exact event coverage and what you can do from a card: watch sessions live, answer permission prompts, unblock work."
+        ogTitle="The 18 agents The Nook supports, and what each hook sees"
       />
       <SubdomainHeader />
       <main class="min-h-screen px-[8vw] py-[8vh]">
@@ -292,7 +379,7 @@ export default function NookAgentsPage() {
           Supported agents
         </h1>
         <p class="text-subtext0 mb-2 max-w-2xl text-lg">
-          The Nook watches thirteen coding agents in one place — your menu bar and
+          The Nook watches eighteen coding agents in one place — your menu bar and
           notch show every session that is running, thinking, or blocked, and a
           card answers permission prompts without leaving your keyboard.
         </p>
@@ -300,8 +387,7 @@ export default function NookAgentsPage() {
           Each agent reports its own set of events. "Allow / Deny from a card"
           means the agent hands the decision to The Nook while it waits;
           "Observe" means every event still appears live, but the agent keeps
-          its own prompting. Agents can run on this Mac or on remote machines
-          over SSH — remote sessions report into the same grid.
+          its own prompting.
         </p>
 
         <div class="grid gap-4 lg:grid-cols-2">

src/routes/nook/faq.tsx

@@ -1,7 +1,8 @@
 /**
  * `/faq` on the Nook subdomain — answers to the objections that actually
- * stop a purchase. Privacy is deliberately absent until the egress
- * inventory and /privacy make an honest answer possible.
+ * stop a purchase. Privacy scoping follows marketing/positioning.md rule 3:
+ * "no prompt or code content leaves the device" (telemetry and the trial
+ * email do leave — never claim "no data leaves the device").
  */
 import { For } from "solid-js";
 import { createSignal, Show } from "solid-js";
@@ -16,46 +17,34 @@ interface FaqEntry {
 
 const FAQ: FaqEntry[] = [
   {
-    question:
-      "Does it work with my agent — and can I approve from the notch, or only watch?",
+    question: "Does The Nook read my prompts or my code?",
     answer:
-      "It depends on the agent, and Cursor is the useful example. Cursor is watched, not gated: its sessions, finished turns and errors appear in the island, but when Cursor asks for permission the prompt stays in Cursor. That is deliberate — Cursor blocks the action when a permission hook runs and prints nothing, so gating it would override Cursor's own prompts. Other agents do hand the decision to The Nook, so a tool call waits and you tap Allow or Deny from the card. One limit: cursor-agent -p one-shot runs send no turn end, so they appear but do not get a completion card."
-  },
-  {
-    question: "What happens when my agent is idle?",
-    answer:
-      "Idle means the last turn is over, or the session has not produced anything yet — not that the process is gone. A running process is liveness, not work: a just-opened agent window can show idle until you type. When an agent finishes a turn with a final message, the row stays green for ten minutes, then goes gray. A stale row is different: it means The Nook's integration cannot report for that session, and the row says so instead of pretending it is idle. Nothing is lost when a row goes idle — the next prompt brings it back and flips it to running. The row itself leaves the island 15 minutes after the turn (5 if the turn ended without a reply), so a long-quiet session reappears on its next event instead of sitting there. If a session that is obviously working says idle, that is a bug; tell us."
-  },
-  {
-    question:
-      "What permissions does it need — and what does it write into my agent's config?",
-    answer:
-      "The app itself runs unprivileged. Fan control and charge limiting go through a small helper that macOS requires to run as root for hardware access; the app registers it on first use and takes you to System Settings › General › Login Items & Extensions, where you switch it on once. For each agent it adds what that agent needs — a hook group per event it listens to, or one plugin link — inside the agent's own config file or directory. It keeps its own files under ~/.nook — the hook binary and one plugin copy per agent — and adds only its own entries to that agent's config. A hook entry you added yourself in the same file survives install and uninstall, and it only touches the records and switches it created. Uninstall removes exactly what it wrote — and switches off what it turned on — with no leftover links or orphaned files."
-  },
-  {
-    question: "Does it work with my terminal, including tmux?",
-    answer:
-      "Yes — it recognises Terminal.app, iTerm2, Warp, Ghostty, kitty, WezTerm and tmux. Four of those take a typed reply; the rest are watched. A session is tied to the terminal that started it. Jump lands in the right window for Terminal.app, iTerm2, kitty and any tmux pane — in tmux, the right pane; on Warp, WezTerm and Ghostty it brings the app forward instead. Replies type straight back into Terminal.app, iTerm2, kitty and any tmux pane; on Warp, WezTerm and Ghostty you answer in the app's own window, and Alacritty takes no typed reply from another app at all."
+      "No. The hooks and plugins that connect your agents to The Nook send session metadata only — which agent is running, which session, which event happened, which terminal it lives in. No prompt text and no code content leaves your device. Two things do leave the device, and we'd rather say so plainly: anonymous usage telemetry, and your email address if you choose to give it at trial start. That's the whole list."
   },
   {
     question: "Do I need a Mac with a notch?",
     answer:
-      "No. On a notched MacBook the island sits in the notch. On machines and displays without one, it sits at the top centre of the display — the same pill with the same slots. You get one island on every display it is turned on for (all connected displays on first launch), each anchored to the top of its own screen; Settings › Displays trims that list, and the pointer only decides which display's floating controls are live. Everything inside the island — agent cards, fan control, the stats strip — works identically either way."
+      "No. On a notched MacBook the island sits in the notch. On machines and displays without one, it anchors to the display your cursor is on, so a desktop setup with external monitors gets the same treatment. Everything inside the island — agent cards, fan control, the stats strip — works identically either way."
   },
   {
     question: "How much battery does it cost?",
     answer:
-      "It is a native app, not a background agent. It watches the agents you already run and never runs them in the background, so their draw is the number that matters. We do not have a published battery measurement for The Nook alone; when we do, it will be a measurement, not an estimate. If it costs more than it should on your Mac, that is a bug — tell us."
+      "The Nook is a small native UI, not a background agent — it watches the agents you're already running; it doesn't run anything itself. The heaviest thing it does is read and write your Mac's fan and charging controllers, which is a lightweight sensor read. If you're running enough coding agents to need it, those agents dwarf the app's own draw."
+  },
+  {
+    question: "What permissions does it need?",
+    answer:
+      "The app itself runs unprivileged. Fan control and charge limiting go through a small helper component that macOS requires to run as root for hardware access — the app installs it on first use and you approve it once with your password. The hooks live in each agent's own config directory; you can inspect or remove every file it writes."
   },
   {
     question: "Why macOS 14.2 or later?",
     answer:
-      "The audio mixer listens to each app's own sound stream, and Apple only shipped that API in macOS 14.2 (Sonoma). The app links against it, so 14.0 and 14.1 cannot launch it."
+      "The audio mixer listens to each app's own sound stream, and Apple only shipped that API in macOS 14.2 (Sonoma)."
   },
   {
     question: "Does it work offline?",
     answer:
-      "The Mac app does. The island, agent cards, permission cards and fan control work with no network; the hooks talk to the app over a local socket. The network is used for update checks, licence activation, crash reports and the optional trial email, plus a few things only when you use them: weather (asked for through our relay, with the location you chose), the network panel's IP-and-ISP lookup, the speed test, the changelog in Settings, and a bug report if you send one. The phone link is the exception: when you are away from your Mac, the phone reaches it through our relay, so that part needs a connection."
+      "Yes. Everything The Nook does — the agent grid, permission cards, fan and thermal control — works with no network at all, and your agents' hooks talk to the app over a local socket. The network is only used for update checks, license activation, and the optional trial email."
   }
 ];
 
@@ -67,7 +56,7 @@ export default function NookFaqPage() {
       <EdgeCacheHeaders maxAge={300} />
       <PageHead
         title="Frequently asked questions"
-        description="Which agents can you approve from the notch? What does idle mean? Terminal and tmux support, permissions, the macOS 14.2 requirement, offline use — answered straight."
+        description="Does The Nook read your prompts? Do you need a notch? Battery cost, permissions, the macOS 14.2 requirement, offline use — answered straight."
         ogTitle="The Nook — FAQ"
       />
       <SubdomainHeader />

src/routes/nook/privacy.tsx

@@ -1,38 +1,9 @@
 /**
  * The Nook privacy policy — `nook.freno.me/privacy`.
  *
- * Every statement on this page is traced to the egress inventory at
- * `The-Nook` HEAD (FRE-333, `document-egress-inventory`): eleven internet
- * destinations, file:line evidence per row. When the app's egress changes,
- * this page changes in the same commit — not later.
- *
- * The crash-reporting paragraphs ((b) and the iPhone companion) describe the
- * build users run today: crash reporting is opt-in, off by default, on
- * releases v0.15.1 and later — FRE-355 (merge `6e74b261`) first shipped in
- * `v0.15.1` (2026-11-04), and the live appcast serves `v0.15.2`. When enabled,
- * Sentry receives crash and error reports, session pings, and performance
- * traces at a 0.1 sample rate (`tracesSampleRate = 0.1`), and it also receives
- * the connection's IP address (`sendDefaultPii = false` is the SDK default and
- * does not suppress it — sentry-cocoa 9.26.1 sets `infer_ip = auto` for Cocoa,
- * and only the Sentry project's *Prevent Storing of IP Addresses* switch stops
- * that; FRE-1480). Releases 0.3.0 through 0.15.0 started Sentry on every
- * launch with `sendDefaultPii = true` and no off switch; this page describes
- * the current release. The iPhone paragraph describes `ios-v0.3.2`
- * (2026-10-22, the build in TestFlight) until an `ios-v*` tag carries
- * FRE-355's opt-in code.
- *
- * The *Contingency* in `marketing/drafts/privacy-page.md` fired with `v0.15.1`
- * and is applied in this commit, with two corrections against the pre-written
- * swap text: the shipped build still sends session pings and traces while
- * enabled, so they are named (the contingency's own completeness warning), and
- * the IP sentence is kept — the pre-written swap text already had it, and
- * `sendDefaultPii = false` does not stop Sentry receiving the IP (FRE-1480).
- *
- * Corrected against the CTO's /privacy verdict (FRE-354): no macOS username
- * from Sentry (sendDefaultPii sets the IP only), session pings named, (a)
- * fail-open scoped, (c) relay-path qualified with the direct-pair sentence,
- * (j) "not a cloud service" with the tailnet path, the iPhone paragraph added
- * (TestFlight beta is in users' hands), and section 3 says "content".
+ * Reflects the actual data The Nook sends when licensing: a masked hardware
+ * UUID + device name for trial/activation limits, the email used for purchase,
+ * and Stripe payment processing.
  */
 import { buildMainSiteUrl } from "~/lib/subdomain-url";
 import { PageHead } from "~/components/PageHead";
@@ -50,139 +21,39 @@ export default function NookPrivacyPolicy() {
       <SubdomainHeader />
       <div class="min-h-screen px-[8vw] py-[10vh]">
         <div class="py-4 text-xl">The Nook&apos;s Privacy Policy</div>
-        <div class="py-2">Last Updated: November 6, 2026</div>
+        <div class="py-2">Last Updated: August 26, 2026</div>
         <div class="py-2">
-          The Nook runs on your Mac, and the iPhone and Apple Watch companion
-          is in TestFlight beta. Your prompts, your code and your agent
-          sessions are processed on your own devices. This page lists every
-          connection the apps make over the internet — and the local-network
-          and tailnet paths the phone can use — what each one sends, and
-          whether you can turn it off.
+          Welcome to The Nook (&apos;We&apos;, &apos;Us&apos;, &apos;Our&apos;).
+          Your privacy is important to us. This policy explains what we collect,
+          why, and how it is handled. The app itself runs locally on your device
+          and sends only the minimal data required for trial and licensing.
         </div>
         <ol>
           <div class="py-2">
             <div class="pb-2 text-lg">
-              <span class="-ml-4 pr-2">1.</span> What leaves your devices
+              <span class="-ml-4 pr-2">1.</span> Data We Collect
             </div>
             <div class="pl-4">
               <div class="pb-2">
-                <div class="-ml-6">(a) Licensing and trial:</div> When you start
-                a trial or activate a license, The Nook sends your Mac&apos;s
-                hardware UUID and device name to our licensing server
-                (freno.me). The UUID enforces the 14-day trial and the 3-device
-                activation limit and stops a trial being reset by reinstalling
-                the app; the device name is stored with the activation so the
-                Mac can be identified in your license records. While you are on
-                the trial, this is sent at each launch. Once you are licensed,
-                each launch re-checks only that your key has not been revoked.
-                Deactivating a Mac sends the license key and that Mac&apos;s
-                UUID. If you add an email during the trial, that request
-                carries the email and the UUID, and it is sent once. The trial
-                and status checks fail open: with no connection, an unexpired
-                trial or a stored license keeps working, because license
-                verification itself is offline. Activating a new license needs
-                a connection once.
+                <div class="-ml-6">(a) Device hardware UUID:</div> When you start
+                a trial or activate a license, The Nook sends a hardware UUID
+                from your Mac. It is used solely to enforce the 14-day trial and
+                the 3-device activation limit, and to prevent resetting the
+                trial by reinstalling the app.
               </div>
               <div class="pb-2">
-                <div class="-ml-6">(b) Crash and error reporting — off unless
-                you turn it on:</div> Crash reporting is off by default and
-                runs only if you enable it in Settings. When it is on, The Nook
-                sends crash reports, error events, hang reports, session pings,
-                and a sample of performance traces to Sentry, our
-                crash-reporting processor. Each report carries the app version,
-                the macOS version, the Mac model and what the app was doing
-                when it failed. Sentry also receives your IP address. They
-                never include your prompts, your code or your session content.
+                <div class="-ml-6">(b) Device name:</div> The Nook sends your
+                Mac&apos;s name so you can recognize the device in your license
+                activations. It is not used for any other purpose.
               </div>
               <div class="pb-2">
-                <div class="-ml-6">(c) Phone connection:</div> The phone
-                connection ships off and is yours to enable. With the default
-                relay path, turning it on registers your Mac with our relay
-                (nook-relay.freno.me) using a random install ID, and a licensed
-                Mac presents its license key once at registration. Everything
-                your Mac and your phone then exchange — session updates,
-                approvals, replies — is encrypted end-to-end: the relay routes
-                it and cannot read it. On the relay path, the relay can see
-                which devices are connected — their IDs, names and platforms —
-                when, and how much traffic they exchange.
+                <div class="-ml-6">(c) Email:</div> The email you provide at
+                checkout is used to deliver your license key and to look up your
+                order.
               </div>
               <div class="pb-2">
-                You can also pair over your LAN or tailnet instead; those paths
-                carry the same sealed traffic and do not use the relay.
-              </div>
-              <div class="pb-2">
-                <div class="-ml-6">(d) Weather:</div> If you add the Weather
-                module, your Mac asks our relay for forecasts using coordinates
-                rounded to a 0.1° grid — about 11 km — and the rounding happens
-                on your Mac before anything is sent. The Weather module
-                registers with the relay for this even if you never turn on the
-                phone connection, and on a licensed Mac that registration
-                presents the license key, exactly as the phone connection&apos;s
-                does. &quot;My Location&quot; asks macOS for your
-                approximate position, and naming or searching for a place uses
-                Apple&apos;s Maps service, so Apple sees those lookups. Neither
-                feature sends us your precise location.
-              </div>
-              <div class="pb-2">
-                <div class="-ml-6">(e) The Network panel:</div> While the
-                Network panel&apos;s connection section is on screen, The Nook
-                asks a third-party IP-lookup service (get.geojs.io, with
-                ipwho.is as backup) what your public IP address and provider
-                are — that is how the panel can show them to you. Those services
-                necessarily see your IP address. The speed-test button measures
-                against Cloudflare&apos;s public speed endpoint and uploads only
-                zeros, never your data.
-              </div>
-              <div class="pb-2">
-                <div class="-ml-6">(f) Update checks:</div> Automatic update
-                checks ship off. If you turn them on, or press &quot;Check for
-                Updates&quot;, The Nook fetches the update feed from freno.me
-                and the request carries your app version. Like every request on
-                this page, it also arrives from your IP address.
-              </div>
-              <div class="pb-2">
-                <div class="-ml-6">(g) Changelog:</div> Opening Settings ›
-                Changelog fetches the release notes from freno.me.
-              </div>
-              <div class="pb-2">
-                <div class="-ml-6">(h) Bug reports:</div> only what you choose
-                to send. If you write a bug report, you decide what it says.
-                Bug reports also include a machine snapshot — macOS version, Mac
-                model, CPU, memory, free disk, locale, and your displays&apos;
-                names and resolutions — so the problem can be reproduced. The
-                optional contact email is used only to reply to you.
-              </div>
-              <div class="pb-2">
-                <div class="-ml-6">(i) Your email and payment:</div> The email
-                you give at checkout delivers your license key and looks up your
-                order. An email you add during the trial is used for one
-                reminder before the trial ends. Payments are processed by
-                Stripe; we never see or store your card details.
-              </div>
-              <div class="pb-2">
-                <div class="-ml-6">(j) What does not leave your Mac:</div> The
-                hook and the bridge that connect your agents to The Nook are
-                not a cloud service: the hook dials the bridge on your Mac, and
-                the bridge only listens. Two paths carry agent data across the
-                network, and both are switched on by you: if you add a remote
-                machine, the hook on that machine dials this Mac over SSH or
-                your tailnet; and if you use the phone connection, the session
-                updates, approvals and replies described in (c) travel through
-                the relay, sealed end to end. The privileged helper that
-                controls fans and charging has no networking code at all.
-              </div>
-              <div class="pb-2">
-                <div class="-ml-6">The iPhone companion.</div> The iPhone and
-                Apple Watch app is in TestFlight beta. The build in TestFlight
-                starts Sentry on every launch, with no setting that turns it
-                off: it sends crash, error and hang reports, session pings,
-                performance traces, the app version, the iOS version, the
-                iPhone model and your IP address. Those reports never include
-                your prompts, code or session content.
-                Its other network traffic is the phone connection in (c) — the
-                relay, or a direct LAN/tailnet link — plus, if you allow
-                notifications, the push token it gives the relay so Apple can
-                deliver them.
+                <div class="-ml-6">(d) Payment:</div> Payments are processed by
+                Stripe. We never see or store your card details.
               </div>
             </div>
           </div>
@@ -192,11 +63,9 @@ export default function NookPrivacyPolicy() {
               <span class="-ml-4 pr-2">2.</span> How We Use It
             </div>
             <div class="pb-2 pl-4">
-              Device identifiers, install IDs, your email and license records are
-              used only to operate the trial and the licenses, to run the relay
-              and the weather service, to answer bug reports, and to deliver
-              purchases. We do not use them for advertising and we do not sell
-              them to anyone.
+              Device identifiers, your email, and license records are used only
+              to operate the trial, deliver purchases, and enforce the 3-device
+              license. We do not use them for advertising or sell them to anyone.
             </div>
           </div>
 
@@ -205,13 +74,9 @@ export default function NookPrivacyPolicy() {
               <span class="-ml-4 pr-2">3.</span> Data Security
             </div>
             <div class="pb-2 pl-4">
-              License keys are signed and verified with Ed25519 and stored in
-              the macOS Keychain. The session content your Mac and phone
-              exchange is encrypted end-to-end with keys your devices generate
-              at pairing; our relay holds no key that can read it, though it
-              can read the routing metadata described in (c). Every internet
-              connection described on this page uses TLS; the direct
-              LAN/tailnet paths use the same end-to-end encryption.
+              License keys are signed and verified with Ed25519. The connection
+              to our servers uses TLS. Your license key is stored in the macOS
+              Keychain on your Mac.
             </div>
           </div>
 

src/routes/nook/remote-claims.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Regression test for the removed remote / SSH claims and the removed agent
+ * count (FRE-323, FRE-359 verdict B).
+ *
+ * FRE-323 took the remote story off the site because it was unverified and
+ * demo-gated (FRE-315, FRE-320, FRE-322 §3 correction 4): the "one click
+ * installs the nook-hook" flow is app-UI-only, needs a hand-edited
+ * `~/.ssh/config` for any host not already in ssh config or on the tailnet,
+ * needs a one-time `ssh-copy-id` because the app runs ssh with
+ * `BatchMode=yes`, and has no manual fallback for minting the per-host
+ * credential. FRE-359 verdict B removed the coverage count for the same
+ * reason: the /agents table lists 13 of the registry's 18 rows.
+ *
+ * FRE-997 corrects the second half without touching the first. The count was
+ * stale, not unverifiable: `AgentSpec.all` holds eighteen, /agents now lists
+ * all eighteen and `agents.test.ts` asserts that roster as an equality again.
+ * So the two completeness phrasings FRE-359 banned ("every coding agent",
+ * "Supported agents") no longer rest on a 13-of-18 gap — the ban existed
+ * because the page claimed the set and listed two thirds of it. They are out
+ * of `BANNED_COVERAGE` on this branch for that reason alone; the stale counts
+ * stay banned, and every FRE-323 remote sentence stays banned, because this
+ * branch still carries the FRE-323 site state.
+ *
+ * The copy was not thrown away — it is parked in
+ * `marketing/drafts/remote-ssh/` with the restore gate, and this test asserts
+ * it is still there so nobody deletes the parked story as stale. It goes back
+ * on the site only when the one-click install ships and is recorded.
+ *
+ * STATIC SOURCE AUDIT, the same pattern as `agents.test.ts` and
+ * `downloads.test.ts` (SolidJS does not render under `bun:test`).
+ *
+ * Deliberate exceptions, not audited here — both were weighed with the Chief
+ * of Staff at the go/no-go and left in place on purpose:
+ *  - `src/routes/nook/agents.tsx` Muse row: "This Mac only — remote hosts skip
+ *    it" is a limitation disclosure, not a capability claim.
+ *  - `src/components/nook/IslandExtras.tsx` "Tailscale hosts" chip: adjacent to
+ *    the removed remote story, but tailnet host lookup does exist. Raised on
+ *    FRE-323 rather than widened into this correction.
+ */
+import { describe, it, expect } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const ROOT = join(import.meta.dir, "../../..");
+
+/** Shipped page and component source. Tests and drafts may quote the old copy. */
+const AUDITED = [
+  "src/routes/nook/index.tsx",
+  "src/routes/nook/agents.tsx",
+  "src/routes/nook/faq.tsx",
+  "src/components/nook/FeatureCollage.tsx",
+  "src/components/nook/FeatureBreakdowns.tsx",
+  "src/components/nook/IslandExtras.tsx"
+];
+
+/** Every sentence FRE-323 ordered off the site. */
+const BANNED_REMOTE_CLAIMS = [
+  "Agents on other machines",
+  "one click installs the nook-hook",
+  "Any SSH box",
+  "Works across every hooked agent, local or remote",
+  "Remote sessions are ordinary rows",
+  "One-click SSH setup",
+  "remote machines over SSH",
+  "this Mac or remote machines"
+];
+
+/** FRE-359 verdict B: no stale count, in any form.
+ *
+ * "every coding agent" and "Supported agents" left this list with FRE-997:
+ * the page now lists all eighteen registry rows and `agents.test.ts` asserts
+ * that equality, so the completeness claim is backed rather than incomplete. */
+const BANNED_COVERAGE = [
+  "all thirteen",
+  "thirteen coding agents",
+  "13 agents"
+];
+
+/** User-facing copy only: comments are not copy and may name the old wording. */
+function copyOf(file: string): string {
+  return readFileSync(join(ROOT, file), "utf8")
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/^\s*\/\/.*$/gm, "");
+}
+
+describe("remote claims stay off the site (FRE-323)", () => {
+  for (const file of AUDITED) {
+    it(`${file} does not restore a removed remote sentence`, () => {
+      const copy = copyOf(file);
+      for (const phrase of BANNED_REMOTE_CLAIMS) {
+        expect(copy.toLowerCase()).not.toContain(phrase.toLowerCase());
+      }
+    });
+  }
+
+  it("/agents no longer offers remote sessions", () => {
+    const copy = copyOf("src/routes/nook/agents.tsx");
+    expect(copy).not.toContain("remote sessions report into the same grid");
+    expect(copy).not.toContain("on this Mac or on remote");
+  });
+
+  it("the parked copy still exists, so restoring the story is a revert and not a rewrite", () => {
+    const parked = readFileSync(join(ROOT, "marketing/drafts/remote-ssh/copy.md"), "utf8");
+    for (const phrase of ["Agents on other machines", "Any SSH box, one click away"]) {
+      expect(parked).toContain(phrase);
+    }
+    expect(readFileSync(join(ROOT, "marketing/drafts/remote-ssh/rationale.md"), "utf8")).toContain(
+      "FRE-320"
+    );
+  });
+});
+
+describe("the agent count is corrected, not dropped (FRE-997)", () => {
+  for (const file of AUDITED) {
+    it(`${file} states no stale count`, () => {
+      const copy = copyOf(file);
+      for (const phrase of BANNED_COVERAGE) {
+        expect(copy.toLowerCase()).not.toContain(phrase.toLowerCase());
+      }
+    });
+  }
+
+  it("/agents states the registry's size", () => {
+    expect(copyOf("src/routes/nook/agents.tsx")).toContain("Supported agents");
+  });
+});

src/routes/smarter-remote/privacy.tsx

@@ -0,0 +1,139 @@
+/**
+ * A Smarter Remote privacy policy — `freno.me/smarter-remote/privacy`.
+ *
+ * Linked from the iOS app's paywall (App Review 3.1.2). Reflects what the app
+ * actually does: TV control stays on the local network, pairing data stays on
+ * the phone, purchases go through Apple and RevenueCat, and sharing is a QR
+ * code passed between phones.
+ */
+import { A } from "@solidjs/router";
+import { PageHead } from "~/components/PageHead";
+import { EdgeCacheHeaders } from "~/components/EdgeCacheHeaders";
+
+export default function SmarterRemotePrivacyPolicy() {
+  return (
+    <>
+      <EdgeCacheHeaders maxAge={300} />
+      <PageHead
+        title="A Smarter Remote Privacy Policy"
+        description="Privacy policy for A Smarter Remote, a universal TV remote app that works over your local Wi-Fi network."
+      />
+      <div class="bg-base">
+        <div class="min-h-screen px-[8vw] py-[8vh]">
+          <div class="py-4 text-xl">A Smarter Remote&apos;s Privacy Policy</div>
+          <div class="py-2">Last Updated: November 2, 2026</div>
+          <div class="py-2">
+            Welcome to A Smarter Remote (&apos;We&apos;, &apos;Us&apos;,
+            &apos;Our&apos;). The app controls your TVs over your own Wi-Fi
+            network. It has no accounts, no ads, and no analytics. This policy
+            explains the little data it does handle.
+          </div>
+          <ol>
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">1.</span> Data We Collect
+              </div>
+              <div class="pl-4">
+                <div class="pb-2">
+                  <div class="-ml-6">(a) Your TVs:</div> The app finds TVs on
+                  your local network and stores their names, network addresses,
+                  and platform on your phone. Pairing codes and tokens are kept
+                  in your phone&apos;s Keychain. This data is sent only to the
+                  TV itself, over your local network. It never reaches us.
+                </div>
+                <div class="pb-2">
+                  <div class="-ml-6">(b) Purchases:</div> Payments are handled
+                  by Apple. We use RevenueCat to check whether you own A Smarter
+                  Remote Pro. RevenueCat receives an anonymous app user ID, your
+                  purchase and subscription history, and basic device and app
+                  details such as OS version, app version, and region. It does
+                  not receive your name, email, or payment details.
+                </div>
+                <div class="pb-2">
+                  <div class="-ml-6">(c) Voice input:</div> If you use voice
+                  search, your speech is converted to text by Apple&apos;s
+                  speech recognition. Apple may process it on its servers. The
+                  resulting text is sent only to your TV.
+                </div>
+                <div class="pb-2">
+                  <div class="-ml-6">(d) Sharing:</div> If you share a TV with
+                  someone, its name, address, and platform are put into a QR
+                  code on your screen for them to scan. It goes from one phone
+                  to the other and does not pass through our servers.
+                </div>
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">2.</span> How We Use It
+              </div>
+              <div class="pb-2 pl-4">
+                Data about your TVs is used only to control them. Purchase
+                records are used only to unlock Pro. We do not use any of it for
+                advertising, and we do not sell it.
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">3.</span> Local Network Access
+              </div>
+              <div class="pb-2 pl-4">
+                iOS asks for permission before the app can use your local
+                network. The app needs it to find and control your TVs. If you
+                decline, the app cannot reach your TVs. You can change this in
+                Settings &gt; Privacy &amp; Security &gt; Local Network.
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">4.</span> Deleting Your Data
+              </div>
+              <div class="pb-2 pl-4">
+                Removing a TV in the app deletes its stored details and
+                credentials from your phone. Deleting the app removes all of
+                them. Subscriptions are managed and cancelled in your App Store
+                account settings.
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">5.</span> Children&apos;s Privacy
+              </div>
+              <div class="pb-2 pl-4">
+                The app does not knowingly collect personal information from
+                anyone, including children under 13.
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">6.</span> Changes to the Privacy Policy
+              </div>
+              <div class="pb-2 pl-4">
+                We may update this policy periodically. Any changes are posted on
+                this page, so please review it from time to time.
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">7.</span> Contact Us
+              </div>
+              <div class="pb-2 pl-4">
+                If you have any questions about this policy, you can contact us{" "}
+                <A href="/contact" class="text-blue hover-underline-animation">
+                  here
+                </A>
+                .
+              </div>
+            </div>
+          </ol>
+        </div>
+      </div>
+    </>
+  );
+}

src/routes/smarter-remote/terms.tsx

@@ -0,0 +1,141 @@
+/**
+ * A Smarter Remote terms of use — `freno.me/smarter-remote/terms`.
+ *
+ * Linked from the iOS app's paywall (App Review 3.1.2). Builds on Apple's
+ * standard EULA and adds the Pro subscription and lifetime purchase terms.
+ */
+import { A } from "@solidjs/router";
+import { PageHead } from "~/components/PageHead";
+import { EdgeCacheHeaders } from "~/components/EdgeCacheHeaders";
+
+export default function SmarterRemoteTerms() {
+  return (
+    <>
+      <EdgeCacheHeaders maxAge={300} />
+      <PageHead
+        title="A Smarter Remote Terms of Use"
+        description="Terms of use for A Smarter Remote and its Pro subscription."
+      />
+      <div class="bg-base">
+        <div class="min-h-screen px-[8vw] py-[8vh]">
+          <div class="py-4 text-xl">A Smarter Remote&apos;s Terms of Use</div>
+          <div class="py-2">Last Updated: November 2, 2026</div>
+          <div class="py-2">
+            These terms cover your use of the A Smarter Remote app (&apos;the
+            App&apos;). By using the App you agree to them. The App is licensed
+            to you under Apple&apos;s{" "}
+            <a
+              href="https://www.apple.com/legal/internet-services/itunes/dev/stdeula/"
+              target="_blank"
+              rel="noopener noreferrer"
+              class="text-blue hover-underline-animation"
+            >
+              Licensed Application End User License Agreement
+            </a>
+            , and the terms below add to it.
+          </div>
+          <ol>
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">1.</span> A Smarter Remote Pro
+              </div>
+              <div class="pl-4">
+                <div class="pb-2">
+                  <div class="-ml-6">(a) What it includes:</div> The free App
+                  controls one TV. Pro removes that limit and unlocks the
+                  features marked Pro in the App.
+                </div>
+                <div class="pb-2">
+                  <div class="-ml-6">(b) Yearly subscription:</div> Payment is
+                  charged to your Apple account when you confirm the purchase,
+                  or when any free trial ends. The subscription renews
+                  automatically at the same price unless you cancel at least 24
+                  hours before the end of the current period. Your account is
+                  charged for renewal within 24 hours before the period ends.
+                  Any unused part of a free trial is forfeited when you buy a
+                  subscription.
+                </div>
+                <div class="pb-2">
+                  <div class="-ml-6">(c) Lifetime purchase:</div> A one-time
+                  payment that unlocks Pro with no recurring charge.
+                </div>
+                <div class="pb-2">
+                  <div class="-ml-6">(d) Managing and refunds:</div> You can
+                  manage or cancel a subscription in your App Store account
+                  settings. Refunds are handled by Apple under its policies.
+                  Restore Purchases in the App re-unlocks Pro on another device
+                  signed in to the same Apple account.
+                </div>
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">2.</span> Your TVs
+              </div>
+              <div class="pb-2 pl-4">
+                The App controls TVs through the network features their makers
+                provide. Which features work depends on your TV&apos;s model and
+                software, which can change without notice. We do not guarantee
+                that every feature works on every TV. Only control TVs you own
+                or have permission to use.
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">3.</span> No Warranty
+              </div>
+              <div class="pb-2 pl-4">
+                The App is provided &apos;as is&apos;, without warranties of any
+                kind, to the extent the law allows. To the extent the law allows,
+                we are not liable for indirect or consequential damages arising
+                from your use of the App.
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">4.</span> Privacy
+              </div>
+              <div class="pb-2 pl-4">
+                How the App handles data is described in the{" "}
+                <A
+                  href="/smarter-remote/privacy"
+                  class="text-blue hover-underline-animation"
+                >
+                  Privacy Policy
+                </A>
+                .
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">5.</span> Changes to These Terms
+              </div>
+              <div class="pb-2 pl-4">
+                We may update these terms periodically. Any changes are posted on
+                this page. Continuing to use the App after a change means you
+                accept the new terms.
+              </div>
+            </div>
+
+            <div class="py-2">
+              <div class="pb-2 text-lg">
+                <span class="-ml-4 pr-2">6.</span> Contact Us
+              </div>
+              <div class="pb-2 pl-4">
+                If you have any questions about these terms, you can contact us{" "}
+                <A href="/contact" class="text-blue hover-underline-animation">
+                  here
+                </A>
+                .
+              </div>
+            </div>
+          </ol>
+        </div>
+      </div>
+    </>
+  );
+}

src/server/analytics-retention.test.ts

@@ -0,0 +1,200 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import { Database } from "bun:sqlite";
+import { VISITOR_ANALYTICS_DDL } from "./analytics-schema";
+import {
+  DEFAULT_ANALYTICS_RETENTION_DAYS,
+  MAX_ANALYTICS_RETENTION_DAYS,
+  isAuthorizedCron,
+  pruneVisitorAnalytics,
+  resolveRetentionDays,
+  runRetentionCron
+} from "./analytics-retention";
+
+// Why a real in-memory SQLite database: retention is a `DELETE` whose whole
+// job is a date comparison. A stub returning a canned count would pass with a
+// window that is off by a unit, inverted, or — the failure this file exists for
+// — never applied at all. Same reasoning as the backfill and schema suites, and
+// nothing is module-mocked here on purpose: bun's `mock.module` is process-wide.
+
+let db: Database;
+
+const conn = {
+  async execute(query: { sql: string; args?: unknown[] }) {
+    const statement = db.query(query.sql);
+    const args = (query.args ?? []) as never[];
+    // `DELETE … RETURNING id` answers with rows, which is how the prune counts
+    // what it removed; bun:sqlite exposes those through `.all()`.
+    if (
+      /^\s*(select|pragma|with)\b/i.test(query.sql) ||
+      /\breturning\b/i.test(query.sql)
+    ) {
+      return { rows: statement.all(...args) as unknown[], rowsAffected: 0 };
+    }
+    return {
+      rows: [] as unknown[],
+      rowsAffected: statement.run(...args).changes
+    };
+  }
+};
+
+function insert(id: string, createdAt: string) {
+  db.run(
+    `INSERT INTO VisitorAnalytics (id, path, method, created_at) VALUES (?, '/x', 'GET', ?)`,
+    [id, createdAt]
+  );
+}
+
+function rowCount(): number {
+  return (db.query(`SELECT COUNT(*) AS n FROM VisitorAnalytics`).get() as {
+    n: number;
+  }).n;
+}
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  db.run(VISITOR_ANALYTICS_DDL);
+});
+
+describe("resolveRetentionDays", () => {
+  it("takes a usable configured window", () => {
+    expect(resolveRetentionDays("90")).toBe(90);
+    expect(resolveRetentionDays(30)).toBe(30);
+  });
+
+  it("falls back to the default when the value is missing or nonsense", () => {
+    expect(resolveRetentionDays(undefined)).toBe(
+      DEFAULT_ANALYTICS_RETENTION_DAYS
+    );
+    expect(resolveRetentionDays("")).toBe(DEFAULT_ANALYTICS_RETENTION_DAYS);
+    expect(resolveRetentionDays("0")).toBe(DEFAULT_ANALYTICS_RETENTION_DAYS);
+    expect(resolveRetentionDays("-5")).toBe(DEFAULT_ANALYTICS_RETENTION_DAYS);
+    expect(resolveRetentionDays("1.5")).toBe(DEFAULT_ANALYTICS_RETENTION_DAYS);
+    expect(resolveRetentionDays("all")).toBe(DEFAULT_ANALYTICS_RETENTION_DAYS);
+  });
+
+  it("refuses a window so long it means 'never prune'", () => {
+    expect(resolveRetentionDays(String(MAX_ANALYTICS_RETENTION_DAYS + 1))).toBe(
+      DEFAULT_ANALYTICS_RETENTION_DAYS
+    );
+  });
+});
+
+describe("pruneVisitorAnalytics", () => {
+  it("deletes only rows older than the window", async () => {
+    insert("young", "2020-01-01 00:00:00");
+    insert("old", "2019-01-01 00:00:00");
+    // A row exactly at `now - 365 days` boundary in the other direction: the
+    // comparison is `<`, so the recent one survives.
+    db.run(
+      `UPDATE VisitorAnalytics SET created_at = datetime('now', '-10 days') WHERE id = 'young'`
+    );
+    db.run(
+      `UPDATE VisitorAnalytics SET created_at = datetime('now', '-400 days') WHERE id = 'old'`
+    );
+
+    const deleted = await pruneVisitorAnalytics(conn, 365);
+
+    expect(deleted).toBe(1);
+    expect(rowCount()).toBe(1);
+  });
+
+  it("deletes nothing when every row is inside the window", async () => {
+    insert("a", "x");
+    db.run(
+      `UPDATE VisitorAnalytics SET created_at = datetime('now', '-1 day') WHERE id = 'a'`
+    );
+
+    expect(await pruneVisitorAnalytics(conn, 365)).toBe(0);
+    expect(rowCount()).toBe(1);
+  });
+
+  it("refuses a window it was not given a number for", async () => {
+    insert("a", "2019-01-01 00:00:00");
+
+    await expect(pruneVisitorAnalytics(conn, 0)).rejects.toThrow(/window/);
+    await expect(pruneVisitorAnalytics(conn, -30)).rejects.toThrow(/window/);
+    await expect(pruneVisitorAnalytics(conn, NaN)).rejects.toThrow(/window/);
+    // "0" is not a window either — and must not delete the table.
+    await expect(
+      pruneVisitorAnalytics(conn, "0" as unknown as number)
+    ).rejects.toThrow(/window/);
+
+    expect(rowCount()).toBe(1);
+  });
+
+  it("passes the window as a parameter, not as interpolated SQL", async () => {
+    insert("a", "2019-01-01 00:00:00");
+    const injected = "365); DROP TABLE VisitorAnalytics; --" as unknown as number;
+
+    // Truncating a non-numeric string yields NaN, which the guard refuses — so
+    // the statement never runs and the table is still there.
+    await expect(pruneVisitorAnalytics(conn, injected)).rejects.toThrow(/window/);
+    expect(rowCount()).toBe(1);
+  });
+});
+
+describe("isAuthorizedCron", () => {
+  it("matches the bearer secret and nothing else", () => {
+    expect(isAuthorizedCron("Bearer sekrit", "sekrit")).toBe(true);
+    expect(isAuthorizedCron("bearer SEKRIT".toLowerCase(), "sekrit")).toBe(true);
+    expect(isAuthorizedCron("Bearer nope", "sekrit")).toBe(false);
+    expect(isAuthorizedCron(null, "sekrit")).toBe(false);
+    expect(isAuthorizedCron("Bearer sekrit", null)).toBe(false);
+  });
+
+  it("denies everything when no secret is configured (fail closed)", () => {
+    expect(isAuthorizedCron("Bearer ", undefined)).toBe(false);
+    expect(isAuthorizedCron(undefined, "")).toBe(false);
+  });
+});
+
+describe("runRetentionCron", () => {
+  it("denies an unauthenticated trigger before touching the table", async () => {
+    insert("a", "2019-01-01 00:00:00");
+
+    const res = await runRetentionCron({
+      authorization: null,
+      secret: "sekrit",
+      configuredDays: "365",
+      conn
+    });
+
+    expect(res.status).toBe(401);
+    expect(rowCount()).toBe(1);
+  });
+
+  it("prunes on its window and reports what it removed", async () => {
+    db.run(
+      `INSERT INTO VisitorAnalytics (id, path, method, created_at) VALUES ('old','/x','GET',datetime('now','-400 days'))`
+    );
+    db.run(
+      `INSERT INTO VisitorAnalytics (id, path, method, created_at) VALUES ('new','/x','GET',datetime('now','-1 day'))`
+    );
+
+    const res = await runRetentionCron({
+      authorization: "Bearer sekrit",
+      secret: "sekrit",
+      configuredDays: "365",
+      conn
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ success: true, days: 365, deleted: 1 });
+    expect(rowCount()).toBe(1);
+  });
+
+  it("says it failed rather than reporting a quiet zero", async () => {
+    db.close(); // the table is gone: the prune's statement must now throw
+
+    const res = await runRetentionCron({
+      authorization: "Bearer sekrit",
+      secret: "sekrit",
+      configuredDays: "365",
+      conn
+    });
+
+    expect(res.status).toBe(500);
+    expect(res.body.days).toBe(365);
+    expect(res.body.deleted).toBeUndefined();
+  });
+});

src/server/analytics-retention.ts

@@ -0,0 +1,129 @@
+/**
+ * Scheduled retention for `VisitorAnalytics` (FRE-369, finding Q4).
+ *
+ * The table used to grow without bound: `cleanupOldAnalytics` existed but was
+ * reachable only as a manual tRPC call, and once FRE-366 started recording a
+ * real client address instead of the proxy's loopback, "unbounded" meant
+ * unbounded personal data in a hosted third-party database. Two halves answer
+ * that — the write-time prefix in `./request-client`, and this: a bound on how
+ * long any row exists at all.
+ *
+ * The default (365 days) is deliberately conservative so enabling the schedule
+ * is not itself a destructive event: it deletes nothing on its first run
+ * against a database whose history starts inside the window, and it bounds
+ * growth from then on. Tighten it to the reviewer's suggested 90 by setting
+ * `ANALYTICS_RETENTION_DAYS=90` — that first run *will* delete months of
+ * history that the /analytics dashboard and the weekly report read, which is an
+ * operational decision, not one this file should make silently.
+ */
+
+/** Kept when `ANALYTICS_RETENTION_DAYS` is unset or unusable. */
+export const DEFAULT_ANALYTICS_RETENTION_DAYS = 365;
+
+/** Anything longer is a misconfiguration, not a policy (≈ 2 years). */
+export const MAX_ANALYTICS_RETENTION_DAYS = 730;
+
+/**
+ * The slice of a connection this module needs — the same shape
+ * `weekly-metrics.ts` pins as `MetricsConn`, so a libsql client satisfies it
+ * without a cast (and the in-memory SQLite test adapter satisfies it too).
+ */
+export interface AnalyticsConn {
+  execute(query: {
+    sql: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    args?: any[];
+  }): Promise<{ rows: unknown[]; rowsAffected?: number }>;
+}
+
+/**
+ * The retention window to enforce: a positive integer at most
+ * {@link MAX_ANALYTICS_RETENTION_DAYS}, else the default. Accepts the env
+ * string form and a number, because both callers hand over a different shape.
+ */
+export function resolveRetentionDays(
+  configured: string | number | undefined | null
+): number {
+  const days = typeof configured === "number" ? configured : Number(configured);
+  if (!Number.isInteger(days) || days <= 0) return DEFAULT_ANALYTICS_RETENTION_DAYS;
+  if (days > MAX_ANALYTICS_RETENTION_DAYS) return DEFAULT_ANALYTICS_RETENTION_DAYS;
+  return days;
+}
+
+/**
+ * Delete analytics rows older than `olderThanDays` and report how many went.
+ *
+ * The window is a SQL parameter, not interpolated text: `cleanupOldAnalytics`
+ * used to splice the number into the statement, which only ever sat behind a
+ * `z.number()` input on the tRPC side — one unvalidated caller away from
+ * injection. A non-integer is refused here rather than passed on, so neither
+ * path can delete on a window the code did not check.
+ */
+export async function pruneVisitorAnalytics(
+  conn: AnalyticsConn,
+  olderThanDays: number
+): Promise<number> {
+  const days = Math.trunc(Number(olderThanDays));
+  if (!Number.isInteger(days) || days <= 0) {
+    throw new Error(
+      `Refusing to prune VisitorAnalytics on a non-positive window: ${olderThanDays}`
+    );
+  }
+
+  const result = await conn.execute({
+    sql: `DELETE FROM VisitorAnalytics
+          WHERE created_at < datetime('now', ?)
+          RETURNING id`,
+    args: [`-${days} days`]
+  });
+
+  // Counted from `RETURNING id` rather than `rowsAffected`, keeping the contract
+  // `cleanupOldAnalytics` had: the caller is told how many rows actually went.
+  return result.rows.length;
+}
+
+/** Whether a cron may run: Bearer match, and an unset secret denies everything. */
+export function isAuthorizedCron(
+  authorization: string | null | undefined,
+  secret: string | undefined | null
+): boolean {
+  if (!secret) return false;
+  const provided = (authorization ?? "").replace(/^Bearer\s+/i, "").trim();
+  return Boolean(provided) && provided === secret;
+}
+
+export interface RetentionOutcome {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+/**
+ * The whole cron decision, away from the route: authorise, resolve the window,
+ * prune. Returns the status and body the route should send, so the behaviour is
+ * testable without a database or an environment.
+ *
+ * Fail closed on auth (an unauthenticated trigger deleting real history is the
+ * worst thing this endpoint can do), and 500 rather than a silent zero on a
+ * failed prune — a retention job that quietly stopped pruning is exactly the
+ * state that created this issue.
+ */
+export async function runRetentionCron(options: {
+  authorization: string | null | undefined;
+  secret: string | undefined | null;
+  configuredDays: string | number | undefined | null;
+  conn: AnalyticsConn;
+}): Promise<RetentionOutcome> {
+  if (!isAuthorizedCron(options.authorization, options.secret)) {
+    return { status: 401, body: { error: "Unauthorized" } };
+  }
+
+  const days = resolveRetentionDays(options.configuredDays);
+
+  try {
+    const deleted = await pruneVisitorAnalytics(options.conn, days);
+    return { status: 200, body: { success: true, days, deleted } };
+  } catch (error) {
+    console.error("Analytics retention job failed:", error);
+    return { status: 500, body: { error: "Analytics retention job failed", days } };
+  }
+}

src/server/analytics-schema.test.ts

@@ -40,7 +40,9 @@ const sampleArgs = [
   2, // inp
   3, // ttfb
   4, // dom_load
-  5 // load_complete
+  5, // load_complete
+  "click", // stage
+  "nook.freno.me" // host
 ];
 
 beforeEach(() => {
@@ -69,7 +71,7 @@ describe("VisitorAnalytics schema", () => {
     }
     // The reverse direction matters too: a column the code writes but the
     // DDL omits is the failure this whole file exists to catch.
-    expect(VISITOR_ANALYTICS_COLUMNS.length).toBe(23);
+    expect(VISITOR_ANALYTICS_COLUMNS.length).toBe(25);
   });
 
   it("has one placeholder per inserted column", () => {
@@ -83,7 +85,7 @@ describe("VisitorAnalytics schema", () => {
 
     const row = db
       .prepare(
-        `SELECT path, country, utm_source, utm_medium, utm_campaign
+        `SELECT path, country, utm_source, utm_medium, utm_campaign, stage, host
          FROM VisitorAnalytics`
       )
       .get() as Record<string, unknown>;
@@ -93,7 +95,9 @@ describe("VisitorAnalytics schema", () => {
       country: "GB",
       utm_source: "hn",
       utm_medium: "post",
-      utm_campaign: "launch"
+      utm_campaign: "launch",
+      stage: "click",
+      host: "nook.freno.me"
     });
   });
 

src/server/analytics-schema.ts

@@ -51,6 +51,8 @@ export const VISITOR_ANALYTICS_DDL = `
     utm_source TEXT,
     utm_medium TEXT,
     utm_campaign TEXT,
+    stage TEXT,
+    host TEXT,
     FOREIGN KEY (user_id) REFERENCES User(id) ON DELETE SET NULL
   )
 `;
@@ -79,6 +81,18 @@ export const VISITOR_ANALYTICS_ADDED_COLUMNS = [
   {
     name: "utm_campaign",
     ddl: `ALTER TABLE VisitorAnalytics ADD COLUMN utm_campaign TEXT`
+  },
+  {
+    // Which funnel stage a download row is: "click" (a door) or "served"
+    // (the file route). Null on every non-download row (FRE-366).
+    name: "stage",
+    ddl: `ALTER TABLE VisitorAnalytics ADD COLUMN stage TEXT`
+  },
+  {
+    // The Host the client addressed, e.g. "nook.freno.me" — the site
+    // dimension the table never had (FRE-366).
+    name: "host",
+    ddl: `ALTER TABLE VisitorAnalytics ADD COLUMN host TEXT`
   }
 ];
 
@@ -110,7 +124,9 @@ export const VISITOR_ANALYTICS_COLUMNS = [
   "inp",
   "ttfb",
   "dom_load",
-  "load_complete"
+  "load_complete",
+  "stage",
+  "host"
 ] as const;
 
 /**

src/server/analytics.ts

@@ -9,6 +9,8 @@ import {
   VISITOR_ANALYTICS_INDEXES,
   VISITOR_ANALYTICS_INSERT
 } from "./analytics-schema";
+import { truncateIpAddress } from "./request-client";
+import { pruneVisitorAnalytics } from "./analytics-retention";
 
 /**
  * Idempotent schema bootstrap, mirroring `nook.ts`. The table had no DDL in
@@ -64,6 +66,10 @@ export interface AnalyticsEntry {
   ttfb?: number | null;
   domLoad?: number | null;
   loadComplete?: number | null;
+  /** Funnel stage for download rows ("click" | "served"); null elsewhere. */
+  stage?: string | null;
+  /** Host the client addressed, e.g. "nook.freno.me" — the site dimension. */
+  host?: string | null;
 }
 
 /**
@@ -124,7 +130,9 @@ async function flushAnalyticsBuffer(): Promise<void> {
           entry.inp || null,
           entry.ttfb || null,
           entry.domLoad || null,
-          entry.loadComplete || null
+          entry.loadComplete || null,
+          entry.stage || null,
+          entry.host || null
         ]
       });
     }
@@ -258,6 +266,8 @@ export async function queryAnalytics(
     utm_medium: row.utm_medium as string | null,
     utm_campaign: row.utm_campaign as string | null,
     duration_ms: row.duration_ms as number | null,
+    stage: row.stage as string | null,
+    host: row.host as string | null,
     created_at: row.created_at as string
   }));
 }
@@ -309,6 +319,10 @@ export async function getAnalyticsSummary(days: number = 30): Promise<{
   });
   const totalApiCalls = (totalApiCallsResult.rows[0]?.count as number) || 0;
 
+  // Since the FRE-369 privacy floor, `ip_address` holds a truncated prefix
+  // (/24 for v4, /56 for v6), so this counts distinct prefixes — households and
+  // mobile exits, not machines. It was never accurate before that either: every
+  // row held the proxy's loopback, so the count was 1.
   const uniqueVisitorsResult = await conn.execute({
     sql: `SELECT COUNT(DISTINCT ip_address) as count FROM VisitorAnalytics 
           WHERE ip_address IS NOT NULL 
@@ -620,19 +634,15 @@ export async function getPerformanceStats(days: number = 30): Promise<{
   };
 }
 
+/**
+ * Delete visitor analytics older than `olderThanDays`. Reachable from tRPC
+ * (admin) and from the daily retention cron (`/api/analytics/retention`);
+ * the SQL and the input rules live in `./analytics-retention`.
+ */
 export async function cleanupOldAnalytics(
   olderThanDays: number
 ): Promise<number> {
-  const conn = ConnectionFactory();
-
-  const result = await conn.execute({
-    sql: `DELETE FROM VisitorAnalytics 
-          WHERE created_at < datetime('now', '-${olderThanDays} days')
-          RETURNING id`,
-    args: []
-  });
-
-  return result.rows.length;
+  return pruneVisitorAnalytics(ConnectionFactory(), olderThanDays);
 }
 
 function parseUserAgent(userAgent?: string): {
@@ -667,6 +677,16 @@ function parseUserAgent(userAgent?: string): {
   return { deviceType, browser, os };
 }
 
+/**
+ * Fill in what the writer did not supply, and apply the privacy floor.
+ *
+ * Every analytics entry — page views, tRPC context, downloads, checkout —
+ * passes through here, which is why the truncation lives here and not at the
+ * call sites: a future writer cannot forget it, and no caller can persist a
+ * full client address by accident (FRE-369, finding Q4). The audit log
+ * (`./audit.ts`) is a separate, pre-existing surface with its own stakes and is
+ * deliberately untouched by this change.
+ */
 export function enrichAnalyticsEntry(entry: AnalyticsEntry): AnalyticsEntry {
   const { deviceType, browser, os } = parseUserAgent(
     entry.userAgent || undefined
@@ -674,6 +694,7 @@ export function enrichAnalyticsEntry(entry: AnalyticsEntry): AnalyticsEntry {
 
   return {
     ...entry,
+    ipAddress: truncateIpAddress(entry.ipAddress),
     deviceType: entry.deviceType || deviceType,
     browser: entry.browser || browser,
     os: entry.os || os

src/server/api/routers/analytics.ts

@@ -10,7 +10,7 @@ import {
 } from "~/server/analytics";
 import { ConnectionFactory } from "~/server/database";
 import { v4 as uuid } from "uuid";
-import { getRequestIP } from "vinxi/http";
+import { resolveClientIp, requestHost } from "~/server/request-client";
 import { parseUtm } from "~/server/utm";
 import { VISITOR_ANALYTICS_INSERT } from "~/server/analytics-schema";
 
@@ -98,7 +98,8 @@ export const analyticsRouter = createTRPCRouter({
             getHeader(req.headers, "referer") ||
             getHeader(req.headers, "referrer") ||
             getHeader(ctx.event.request?.headers, "referer");
-          const ipAddress = getRequestIP(ctx.event.nativeEvent) || undefined;
+          const ipAddress = resolveClientIp(ctx.event) || undefined;
+          const host = requestHost(ctx.event) || undefined;
           const enriched = enrichAnalyticsEntry({
             userId: ctx.userId,
             path: input.path,
@@ -106,6 +107,7 @@ export const analyticsRouter = createTRPCRouter({
             userAgent,
             referrer,
             ipAddress,
+            host,
             // The client beacon sends `pathname + search`, so the page URL's
             // own query string is the campaign source; the referrer fills any
             // gap (e.g. clicks that arrive on a clean path).
@@ -145,7 +147,9 @@ export const analyticsRouter = createTRPCRouter({
               enriched.inp || null,
               enriched.ttfb || null,
               enriched.domLoad || null,
-              enriched.loadComplete || null
+              enriched.loadComplete || null,
+              enriched.stage || null,
+              enriched.host || null
             ]
           });
 

src/server/api/routers/downloads.ts

@@ -79,7 +79,7 @@ export const downloadsRouter = createTRPCRouter({
       // exactly the event the funnel needs to show. Unknown asset names are
       // skipped rather than recorded as a download that never happened.
       if (assets[input.asset_name] || latestAssets[input.asset_name]) {
-        await trackDownload(ctx.event, input.asset_name);
+        await trackDownload(ctx.event, input.asset_name, "click");
       }
 
       const bucket = env.VITE_DOWNLOAD_BUCKET_STRING;

src/server/api/utils.ts

@@ -1,7 +1,7 @@
 import { initTRPC, TRPCError } from "@trpc/server";
 import type { APIEvent } from "@solidjs/start/server";
 import { logVisit, enrichAnalyticsEntry } from "~/server/analytics";
-import { getRequestIP } from "vinxi/http";
+import { resolveClientIp, requestHost } from "~/server/request-client";
 import { getAuthPayloadFromEvent } from "~/server/auth";
 
 export type Context = {
@@ -51,7 +51,11 @@ async function createContextInner(event: APIEvent): Promise<Context> {
     getHeader(req.headers, "referer") ||
     getHeader(req.headers, "referrer") ||
     getHeader(event.request?.headers, "referer");
-  const ipAddress = getRequestIP(event.nativeEvent) || undefined;
+  // Behind the production proxy the direct peer is loopback, so the real
+  // client address comes from the forwarded header the proxy sets — see
+  // `~/server/request-client` for the trust boundary (FRE-366).
+  const ipAddress = resolveClientIp(event) || undefined;
+  const host = requestHost(event) || undefined;
 
   // Don't log the performance logging endpoint itself to avoid circular tracking
   if (!path.includes("analytics.logPerformance")) {
@@ -62,7 +66,8 @@ async function createContextInner(event: APIEvent): Promise<Context> {
         method,
         userAgent,
         referrer,
-        ipAddress
+        ipAddress,
+        host
       })
     );
   }

src/server/request-client.test.ts

@@ -0,0 +1,203 @@
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+
+// The trust boundary of FRE-366, as corrected by the FRE-369 security review.
+// Two things must stay true here:
+//   1. The address we record is the visitor, not whoever typed a header first.
+//      Cloudflare and the origin proxy both *append* to x-forwarded-for, so the
+//      leftmost hop is the client's own invention — `cf-connecting-ip` (which
+//      Cloudflare overwrites) comes first, then the hop below the trusted edge.
+//   2. What reaches the database is a prefix, never a full address
+//      (`truncateIpAddress`), because a visitor row is not worth a precise
+//      location.
+// A regression on (1) re-records whatever an attacker claims; on (2) it stores
+// personal data we promised not to.
+
+let directIp: string | null = null;
+mock.module("vinxi/http", () => ({
+  getRequestIP: () => directIp
+}));
+
+const {
+  resolveClientIp,
+  isLoopbackAddress,
+  isIpAddress,
+  truncateIpAddress,
+  normaliseHost,
+  requestHost
+} = await import("./request-client");
+
+function event(
+  headers: Record<string, string> = {},
+  url = "https://nook.freno.me/downloads"
+) {
+  return {
+    request: new Request(url, { headers }),
+    nativeEvent: {}
+  } as never;
+}
+
+beforeEach(() => {
+  directIp = null;
+});
+
+describe("resolveClientIp", () => {
+  it("prefers Cloudflare's connecting address over any forwarded header", () => {
+    directIp = "127.0.0.1";
+    expect(
+      resolveClientIp(
+        event({
+          "cf-connecting-ip": "203.0.113.7",
+          "x-forwarded-for": "198.51.100.9, 203.0.113.7, 198.51.100.1"
+        })
+      )
+    ).toBe("203.0.113.7");
+  });
+
+  it("takes the hop below the trusted edge — never the leftmost one", () => {
+    // client → Cloudflare → same-host origin proxy: the sender's spoof is
+    // first, the real client second, the edge last.
+    directIp = "::1";
+    expect(
+      resolveClientIp(
+        event({
+          "x-forwarded-for": "198.51.100.9, 203.0.113.7, 198.51.100.1"
+        })
+      )
+    ).toBe("203.0.113.7");
+  });
+
+  it("refuses a single-hop forwarded header: nothing above it to discount", () => {
+    directIp = "127.0.0.1";
+    expect(
+      resolveClientIp(event({ "x-forwarded-for": "198.51.100.9" }))
+    ).toBe("127.0.0.1");
+  });
+
+  it("ignores a forwarded header from a real peer — it is spoofable", () => {
+    directIp = "203.0.113.7";
+    expect(
+      resolveClientIp(
+        event({
+          "cf-connecting-ip": "198.51.100.9",
+          "x-forwarded-for": "198.51.100.9, 10.0.0.1"
+        })
+      )
+    ).toBe("203.0.113.7");
+  });
+
+  it("ignores a header value that is not an address", () => {
+    directIp = "127.0.0.1";
+    expect(
+      resolveClientIp(
+        event({
+          "cf-connecting-ip": "not-an-address",
+          "x-forwarded-for": "198.51.100.9, 203.0.113.7, 198.51.100.1"
+        })
+      )
+    ).toBe("203.0.113.7");
+
+    directIp = "127.0.0.1";
+    expect(
+      resolveClientIp(event({ "cf-connecting-ip": "evil.example.com" }))
+    ).toBe("127.0.0.1");
+  });
+
+  it("keeps the loopback peer when the proxy set nothing usable", () => {
+    directIp = "::ffff:127.0.0.1";
+    expect(resolveClientIp(event())).toBe("::ffff:127.0.0.1");
+  });
+
+  it("records nothing rather than inventing an address", () => {
+    expect(resolveClientIp(event())).toBeNull();
+  });
+});
+
+describe("isLoopbackAddress", () => {
+  it("covers the v4 range and every spelling of v6 loopback", () => {
+    expect(isLoopbackAddress("127.0.0.1")).toBe(true);
+    expect(isLoopbackAddress("127.0.0.53")).toBe(true);
+    expect(isLoopbackAddress("::1")).toBe(true);
+    expect(isLoopbackAddress("0:0:0:0:0:0:0:1")).toBe(true);
+    expect(isLoopbackAddress("::ffff:127.0.0.1")).toBe(true);
+    expect(isLoopbackAddress("::ffff:127.9.9.9")).toBe(true);
+  });
+
+  it("is not loopback for a real peer, or for text it cannot parse", () => {
+    expect(isLoopbackAddress("203.0.113.7")).toBe(false);
+    expect(isLoopbackAddress("10.0.0.1")).toBe(false);
+    expect(isLoopbackAddress("localhost")).toBe(false);
+    expect(isLoopbackAddress("127.0.53")).toBe(false); // not a complete address
+    expect(isLoopbackAddress("")).toBe(false);
+  });
+});
+
+describe("isIpAddress", () => {
+  it("accepts a dotted quad and an IPv6 literal", () => {
+    expect(isIpAddress("198.51.100.9")).toBe(true);
+    expect(isIpAddress("2001:db8::1")).toBe(true);
+    expect(isIpAddress("::ffff:198.51.100.9")).toBe(true);
+  });
+
+  it("rejects anything a proxy could not have meant", () => {
+    expect(isIpAddress("999.1.1.1")).toBe(false);
+    expect(isIpAddress("1.2.3")).toBe(false);
+    expect(isIpAddress("2001:db8:::1")).toBe(false);
+    expect(isIpAddress("evil.example.com")).toBe(false);
+    expect(isIpAddress("")).toBe(false);
+    expect(isIpAddress(null)).toBe(false);
+  });
+});
+
+describe("truncateIpAddress", () => {
+  it("cuts IPv4 to its /24", () => {
+    expect(truncateIpAddress("198.51.100.9")).toBe("198.51.100.0");
+    expect(truncateIpAddress("127.0.0.1")).toBe("127.0.0.0");
+  });
+
+  it("cuts IPv6 to its /56, uncompressed and stable", () => {
+    expect(
+      truncateIpAddress("2001:db8:85a3:1234:5678:9abc:defa:1234")
+    ).toBe("2001:db8:85a3:1200:0:0:0:0");
+    // The compressed spelling of the same address truncates to the same string,
+    // so `COUNT(DISTINCT ip_address)` cannot be split by how a proxy rendered it.
+    expect(truncateIpAddress("2001:db8:85a3:1234::")).toBe(
+      "2001:db8:85a3:1200:0:0:0:0"
+    );
+    expect(truncateIpAddress("::1")).toBe("0:0:0:0:0:0:0:0");
+  });
+
+  it("treats an IPv4-mapped v6 address as the v4 it is", () => {
+    expect(truncateIpAddress("::ffff:198.51.100.9")).toBe("198.51.100.0");
+  });
+
+  it("drops what it cannot parse rather than storing it", () => {
+    expect(truncateIpAddress("203.0.113.999")).toBeNull();
+    expect(truncateIpAddress("<script>alert(1)</script>")).toBeNull();
+    expect(truncateIpAddress("")).toBeNull();
+    expect(truncateIpAddress(null)).toBeNull();
+    expect(truncateIpAddress(undefined)).toBeNull();
+  });
+});
+
+describe("normaliseHost", () => {
+  it("lowercases and strips the port so the weekly host scope can match", () => {
+    expect(normaliseHost("Nook.Freno.ME:443")).toBe("nook.freno.me");
+    expect(normaliseHost("nook.freno.me.")).toBe("nook.freno.me");
+    expect(normaliseHost("[::1]:3000")).toBe("::1");
+    expect(normaliseHost("  ")).toBeNull();
+    expect(normaliseHost(null)).toBeNull();
+  });
+});
+
+describe("requestHost", () => {
+  it("reads the host the client addressed from the request URL", () => {
+    expect(requestHost(event())).toBe("nook.freno.me");
+    expect(requestHost(event({}, "https://freno.me/"))).toBe("freno.me");
+  });
+
+  it("normalises a host that carries a port", () => {
+    expect(requestHost(event({}, "https://nook.freno.me:443/downloads"))).toBe(
+      "nook.freno.me"
+    );
+  });
+});

src/server/request-client.ts

@@ -0,0 +1,282 @@
+import type { APIEvent } from "@solidjs/start/server";
+import { getRequestIP } from "vinxi/http";
+import { hostFromEventLike } from "./site-context-server";
+
+/**
+ * The client address and the site a request addressed, for the analytics
+ * writers (FRE-366).
+ *
+ * Until this existed every writer called `getRequestIP` and only looked at
+ * `x-forwarded-for` when it returned null — so behind the production proxy the
+ * recorded address was the proxy itself, and all 12,035 addressed rows in
+ * VisitorAnalytics carried 127.0.0.1 / ::1.
+ *
+ * STANDING RULE (FRE-369, the security review of that change): nothing here is
+ * a security signal. The address is a *best guess at a visitor*, not an
+ * authenticated identity — do not import it into auth, rate limiting, abuse
+ * control, fraud checks, or anything that grants or denies access. A caller
+ * that needs a security decision must re-derive trust for its own stakes; the
+ * blast radius of a wrong answer here is a poisoned analytics row, and that is
+ * the only reason the shortcuts below are acceptable.
+ *
+ * Trust boundary, stated plainly: `x-forwarded-for` is client-controlled text.
+ * It is believed only when the direct peer is a loopback address — the
+ * production shape, where a same-host proxy (nginx/caddy) terminates TLS and
+ * sets the header itself. Anywhere else the direct peer IS the client (dev,
+ * direct hit) and a forwarded header from it is ignored as spoofable.
+ *
+ * Which hop is the visitor (FRE-369 finding Q1): the request arrives as
+ * `client → Cloudflare → same-host origin proxy → app`, and both proxies
+ * *append*. So `x-forwarded-for` reaches us as
+ * `<client-supplied spoof…>, <true client>, <Cloudflare edge>` and the leftmost
+ * hop is exactly the one the sender chose — the original FRE-366 read took it
+ * and was wrong. Order of preference:
+ *
+ *   1. `cf-connecting-ip` — Cloudflare *overwrites* this header, so a
+ *      client-supplied value never survives the edge. Authoritative.
+ *   2. `x-forwarded-for`, counted from the right: drop the rightmost hop (the
+ *      Cloudflare edge address the origin proxy appended) and take the one
+ *      before it. Never the leftmost.
+ *   3. the direct peer, as before.
+ *
+ * h3's own `getRequestIP(event, { xForwardedFor: true })` also takes the
+ * leftmost hop, so it is not a fix for this and must not be swapped in.
+ *
+ * Residual caveat, deliberately not papered over: step 2 assumes the pinned
+ * topology (one trusted proxy above us, i.e. Cloudflare). Behind a *single*
+ * forwarding proxy that does not set `cf-connecting-ip`, a client that sent its
+ * own `x-forwarded-for` sits at the hop we read. That is why the value is only
+ * ever stored truncated (see `truncateIpAddress`) and why it stays out of every
+ * security path. Deploy-side precondition this repo cannot verify: the origin
+ * must be reachable only from Cloudflare (origin firewall / authenticated
+ * origin pull). If it is directly reachable, an attacker can set every header
+ * in this file and no read here can recover the truth.
+ */
+
+/** Cloudflare's "who actually connected" header: overwritten at the edge. */
+const CF_CONNECTING_IP = "cf-connecting-ip";
+const X_FORWARDED_FOR = "x-forwarded-for";
+
+/**
+ * Hops discounted from the right of `x-forwarded-for` before the value is
+ * taken: the Cloudflare edge address the origin proxy appended. Pinned to 1
+ * because there is exactly one trusted proxy between Cloudflare and the app;
+ * raise it only if the topology gains a trusted hop.
+ */
+const FORWARDED_HOPS_TO_DISCOUNT = 1;
+
+function header(event: APIEvent, name: string): string | null {
+  try {
+    return event.request?.headers?.get?.(name) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The visitor's address, resolved through the trust boundary above.
+ *
+ * Never store the result of this directly: `enrichAnalyticsEntry` runs every
+ * analytics entry through {@link truncateIpAddress} so a full address cannot
+ * reach the database even from a writer that forgets. Callers that need the
+ * un-truncated value must justify it in review.
+ */
+export function resolveClientIp(event: APIEvent): string | null {
+  const direct = getRequestIP(event.nativeEvent);
+
+  // A real peer is its own client: believed, and no forwarded header from it
+  // is (it would be the peer lying about who it is).
+  if (direct && !isLoopbackAddress(direct)) return direct;
+
+  // 1. Cloudflare's own record of the connecting address.
+  const connecting = cleanHop(header(event, CF_CONNECTING_IP));
+  if (isIpAddress(connecting)) return connecting;
+
+  // 2. Rightmost-minus-the-trusted-hop, never leftmost.
+  const hops = (header(event, X_FORWARDED_FOR) ?? "")
+    .split(",")
+    .map(cleanHop)
+    .filter(Boolean);
+  const index = hops.length - 1 - FORWARDED_HOPS_TO_DISCOUNT;
+  if (index >= 0) {
+    const candidate = hops[index]!;
+    if (isIpAddress(candidate)) return candidate;
+  }
+
+  // 3. Nothing trustworthy: record what we actually saw, even though it is the
+  // proxy. `readTraffic` reports these rows rather than hiding them.
+  return direct ?? null;
+}
+
+function cleanHop(value: string | null | undefined): string {
+  return (value ?? "").trim();
+}
+
+/**
+ * Whether an address is the loopback the production proxy presents.
+ *
+ * Parses rather than string-matches, so the forms a real peer can present in —
+ * `::ffff:127.0.0.53`, `0:0:0:0:0:0:0:1`, an IPv4-mapped literal — are all
+ * recognised. An address this does not parse is *not* loopback, which fails
+ * closed: forwarded headers from an unrecognised peer are ignored rather than
+ * believed.
+ */
+export function isLoopbackAddress(ip: string): boolean {
+  const bytes = addressBytes(ip);
+  if (!bytes) return false;
+  if (bytes.length === 4) return bytes[0] === 127;
+
+  // IPv6 loopback ::1 — and ::ffff:127/8, which is loopback too.
+  const mapped = ipv4FromBytes(bytes);
+  if (mapped) return isLoopbackAddress(mapped);
+  const tail = bytes[15]!;
+  return bytes.slice(0, 15).every((byte) => byte === 0) && tail === 1;
+}
+
+// ── Addresses: parse, validate, truncate ────────────────────────────────────
+
+/**
+ * The privacy floor the security review required before this ships (FRE-369,
+ * finding Q4): VisitorAnalytics must never hold a full client address. IPv4 is
+ * cut to /24, IPv6 to /56 — the prefix that identifies a household and that a
+ * rotating "privacy" IPv6 address does not actually change. Funnel stages count
+ * rows, and `uniqueVisitors` survives as a count of distinct prefixes, so
+ * nothing measured here needs the last octet.
+ *
+ * An address that does not parse is dropped rather than stored: an unparseable
+ * string is client text we cannot reason about, and keeping it would smuggle
+ * the very granularity this function exists to remove.
+ */
+export function truncateIpAddress(ip: string | null | undefined): string | null {
+  const value = cleanHop(ip);
+  if (!value) return null;
+
+  const bytes = addressBytes(value);
+  if (!bytes) return null;
+
+  const mapped = bytes.length === 16 ? ipv4FromBytes(bytes) : null;
+  if (bytes.length === 4 || mapped) {
+    const octets = (mapped ?? value).split(".").map(Number) as number[];
+    return `${octets[0]}.${octets[1]}.${octets[2]}.0`;
+  }
+
+  // /56 = keep the first 7 bytes, zero the rest. Rendered uncompressed and
+  // lowercase so one client always truncates to one stored string.
+  const kept = bytes.map((_, i) => (i >= 7 ? 0 : _));
+  const groups: string[] = [];
+  for (let i = 0; i < 16; i += 2) {
+    groups.push((((kept[i]! << 8) | kept[i + 1]!) >>> 0).toString(16));
+  }
+  return groups.join(":");
+}
+
+/** Any address this file understands: a dotted quad or an IPv6 literal. */
+export function isIpAddress(value: string | null | undefined): boolean {
+  return value !== null && value !== undefined && addressBytes(value) !== null;
+}
+
+function isIpv4(value: string): boolean {
+  const parts = value.split(".");
+  if (parts.length !== 4) return false;
+  return parts.every(
+    (part) => /^\d{1,3}$/.test(part) && Number(part) <= 255 && !/^0\d/.test(part)
+  );
+}
+
+/** 4 bytes for IPv4, 16 for IPv6 (including `::ffff:a.b.c.d`), else null. */
+function addressBytes(value: string): number[] | null {
+  const raw = value.trim().replace(/^\[|\]$/g, "").split("%")[0]!;
+  if (isIpv4(raw)) return raw.split(".").map(Number);
+  if (!raw.includes(":")) return null;
+
+  const halves = raw.split("::");
+  if (halves.length > 2) return null;
+  const compressed = halves.length === 2;
+
+  const head = groupsToBytes(halves[0] ?? "");
+  const tail = groupsToBytes(halves[1] ?? "");
+  if (!head || !tail) return null;
+
+  const total = head.length + tail.length;
+  if (compressed) {
+    if (total > 8) return null;
+    return [...head, ...new Array(8 - total).fill(0), ...tail].flatMap(split16);
+  }
+  if (total !== 8) return null;
+  return [...head, ...tail].flatMap(split16);
+}
+
+/** One side of `::` as 16-bit groups; a trailing `1.2.3.4` counts as two. */
+function groupsToBytes(side: string): number[] | null {
+  if (side === "") return [];
+  const out: number[] = [];
+  for (const part of side.split(":")) {
+    if (/^[0-9a-fA-F]{1,4}$/.test(part)) {
+      out.push(parseInt(part, 16));
+    } else if (isIpv4(part)) {
+      const o = part.split(".").map(Number);
+      out.push((o[0]! << 8) | o[1]!, (o[2]! << 8) | o[3]!);
+    } else {
+      return null;
+    }
+  }
+  return out;
+}
+
+function split16(group: number): number[] {
+  return [(group >> 8) & 0xff, group & 0xff];
+}
+
+/** The embedded IPv4 of an IPv4-mapped IPv6 address (`::ffff:1.2.3.4`), else null. */
+function ipv4FromBytes(bytes: number[]): string | null {
+  const prefix = bytes.slice(0, 10).every((byte) => byte === 0);
+  const marker = bytes[10] === 0xff && bytes[11] === 0xff;
+  if (!prefix || !marker) return null;
+  return `${bytes[12]}.${bytes[13]}.${bytes[14]}.${bytes[15]}`;
+}
+
+/**
+ * The site the request addressed — the `Host` the client asked for, normalised
+ * to `nook.freno.me`. Recorded on every analytics row so a weekly read can
+ * scope to one site; without it `/` on nook.freno.me is the same row as `/` on
+ * freno.me. Thin alias over the site-context extractor so the analytics writers
+ * share one host-parsing implementation with routing.
+ *
+ * Normalised (lowercased, port stripped) because the weekly read scopes with
+ * `host = ?`: `nook.freno.me:443` or `Nook.Freno.ME` would otherwise store a
+ * value that silently never matches the scope (FRE-369, finding Q3 — no
+ * injection risk, but a correctness one worth fixing at write time).
+ */
+export function requestHost(event: APIEvent): string | null {
+  return normaliseHost(hostFromEventLike(event)) ?? normaliseHost(urlHost(event));
+}
+
+function urlHost(event: APIEvent): string | null {
+  // `host` is a forbidden header and some server shapes drop it from
+  // `event.request.headers`; the request URL is absolute on the server and
+  // carries the same host the client addressed.
+  try {
+    const url = event.request?.url;
+    return url ? new URL(url).host || null : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Lowercase, drop the port and any trailing dot; null when nothing is left. */
+export function normaliseHost(host: string | null | undefined): string | null {
+  const raw = cleanHop(host).toLowerCase();
+  if (!raw) return null;
+
+  // A bracketed IPv6 literal keeps its brackets' contents (`[::1]:3000` →
+  // `::1`); anything else drops a trailing `:port`.
+  const closing = raw.indexOf("]");
+  const withoutPort = raw.startsWith("[")
+    ? closing > 0
+      ? raw.slice(1, closing)
+      : raw.slice(1)
+    : raw.replace(/:\d+$/, "");
+
+  const trimmed = withoutPort.replace(/\.$/, "");
+  return trimmed || null;
+}

src/server/security.ts

@@ -3,6 +3,7 @@ import { getCookie, setCookie } from "vinxi/http";
 import type { H3Event } from "vinxi/http";
 import { t } from "~/server/api/utils";
 import { logAuditEvent } from "~/server/audit";
+import { resolveTrustedClientIp } from "~/server/trusted-client-ip";
 import { env } from "~/env/server";
 import {
   AUTH_CONFIG,
@@ -328,39 +329,15 @@ async function cleanupExpiredRateLimits(): Promise<void> {
 }
 
 /**
- * Get client IP address from request headers.
- * Only trusts X-Forwarded-For outside of local development (set by the Vercel
- * edge network in production; trusted in tests so the header-parsing path is
- * exercised). In local development, uses the socket address to prevent header
- * spoofing.
+ * Get client IP address for a security decision (rate limiting, audit).
+ *
+ * Thin alias over `resolveTrustedClientIp` (./trusted-client-ip), which owns
+ * the trust order: the previous leftmost `x-forwarded-for` read was
+ * client-spoofable in our append-only proxy topology, and `x-real-ip` was
+ * read unconditionally — both fixed there (FRE-371).
  */
 export function getClientIP(event: H3Event): string {
-  // In production on Vercel, X-Forwarded-For is set by the edge network
-  // and cannot be spoofed by clients. In dev, ignore it.
-  if (env.NODE_ENV !== "development") {
-    const forwarded = getHeaderValue(event, "x-forwarded-for");
-    if (forwarded) {
-      return forwarded.split(",")[0].trim();
-    }
-    const realIP = getHeaderValue(event, "x-real-ip");
-    if (realIP) {
-      return realIP;
-    }
-  }
-
-  // Fallback: try socket remote address
-  try {
-    const nodeReq = event.node.req;
-    if (nodeReq?.socket?.remoteAddress) {
-      const addr = nodeReq.socket.remoteAddress;
-      // Clean up IPv6-mapped IPv4 addresses
-      return addr.replace(/^::ffff:/, "");
-    }
-  } catch {
-    // socket access failed
-  }
-
-  return "unknown";
+  return resolveTrustedClientIp(event);
 }
 
 /**

src/server/security/rate-limit.test.ts

@@ -150,29 +150,100 @@ describe("Rate Limiting", () => {
   });
 
   describe("getClientIP", () => {
-    it("should extract IP from x-forwarded-for header", () => {
+    // FRE-371: the read is spoof-resistant now. In the pinned topology
+    // (client → Cloudflare → origin proxy → app) both proxies APPEND, so
+    // x-forwarded-for arrives as `<spoof…>, <true client>, <CF edge>` and the
+    // leftmost hop is whatever the sender typed. Trust order:
+    // cf-connecting-ip, then x-forwarded-for rightmost-minus-one, then the
+    // socket peer — never the leftmost hop, never x-real-ip.
+
+    it("takes x-forwarded-for rightmost-minus-one, never the leftmost hop", () => {
       const event = createMockEvent({
-        headers: { "x-forwarded-for": "192.168.1.1, 10.0.0.1" }
+        headers: {
+          "x-forwarded-for": "6.6.6.6, 192.168.1.1, 10.0.0.1"
+        }
       });
 
       const ip = getClientIP(event);
       expect(ip).toBe("192.168.1.1");
     });
 
-    it("should extract IP from x-real-ip header", () => {
+    it("prefers cf-connecting-ip (Cloudflare overwrites it at the edge)", () => {
+      const event = createMockEvent({
+        headers: {
+          "cf-connecting-ip": "203.0.113.7",
+          "x-forwarded-for": "6.6.6.6, 192.168.1.1, 10.0.0.1"
+        }
+      });
+
+      const ip = getClientIP(event);
+      expect(ip).toBe("203.0.113.7");
+    });
+
+    it("a rotating leftmost x-forwarded-for does not change the resolved client", () => {
+      // The spoof the old read fell for: same Cloudflare-recorded client,
+      // different sender-chosen prefix per request. The key must be stable,
+      // or each rotation mints a fresh rate-limit bucket.
+      const first = getClientIP(
+        createMockEvent({
+          headers: {
+            "cf-connecting-ip": "203.0.113.7",
+            "x-forwarded-for": "1.1.1.1, 203.0.113.7, 10.0.0.1"
+          }
+        })
+      );
+      const second = getClientIP(
+        createMockEvent({
+          headers: {
+            "cf-connecting-ip": "203.0.113.7",
+            "x-forwarded-for": "2.2.2.2, 203.0.113.7, 10.0.0.1"
+          }
+        })
+      );
+
+      expect(first).toBe("203.0.113.7");
+      expect(second).toBe(first);
+    });
+
+    it("ignores x-real-ip entirely (client-settable in this topology)", () => {
       const event = createMockEvent({
         headers: { "x-real-ip": "192.168.1.2" }
       });
 
       const ip = getClientIP(event);
-      expect(ip).toBe("192.168.1.2");
+      expect(ip).toBe("unknown");
     });
 
-    it("should prefer x-forwarded-for over x-real-ip", () => {
+    it("ignores a client-supplied single-hop x-forwarded-for with no trusted proxy above it", () => {
+      // One hop only = the sender's own invention; discounting the trusted
+      // hop leaves nothing to believe.
       const event = createMockEvent({
+        headers: { "x-forwarded-for": "6.6.6.6" }
+      });
+
+      const ip = getClientIP(event);
+      expect(ip).toBe("unknown");
+    });
+
+    it("a non-loopback socket peer is the client and beats every header", () => {
+      const event = createMockEvent({
+        remoteAddress: "198.51.100.23",
         headers: {
-          "x-forwarded-for": "192.168.1.1",
-          "x-real-ip": "192.168.1.2"
+          "cf-connecting-ip": "6.6.6.6",
+          "x-forwarded-for": "6.6.6.6, 192.168.1.1, 10.0.0.1",
+          "x-real-ip": "6.6.6.6"
+        }
+      });
+
+      const ip = getClientIP(event);
+      expect(ip).toBe("198.51.100.23");
+    });
+
+    it("a loopback socket peer lets the forwarded headers speak", () => {
+      const event = createMockEvent({
+        remoteAddress: "127.0.0.1",
+        headers: {
+          "x-forwarded-for": "6.6.6.6, 192.168.1.1, 10.0.0.1"
         }
       });
 
@@ -198,13 +269,23 @@ describe("Rate Limiting", () => {
     it("should handle IPv6 addresses", () => {
       const event = createMockEvent({
         headers: {
-          "x-forwarded-for": "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
+          "x-forwarded-for":
+            "2001:0db8:85a3:0000:0000:8a2e:0370:7334, 10.0.0.1"
         }
       });
 
       const ip = getClientIP(event);
       expect(ip).toBe("2001:0db8:85a3:0000:0000:8a2e:0370:7334");
     });
+
+    it("rejects a candidate hop that is not an address", () => {
+      const event = createMockEvent({
+        headers: { "x-forwarded-for": "not-an-ip, 10.0.0.1" }
+      });
+
+      const ip = getClientIP(event);
+      expect(ip).toBe("unknown");
+    });
   });
 
   describe("rateLimitLogin", () => {

src/server/security/test-utils.ts

@@ -14,12 +14,15 @@ export function createMockEvent(options: {
   cookies?: Record<string, string>;
   method?: string;
   url?: string;
+  /** Socket peer the server observed; omit for a peer-less synthetic event. */
+  remoteAddress?: string;
 }): H3Event {
   const {
     headers = {},
     cookies = {},
     method = "POST",
-    url = "http://localhost:3000/"
+    url = "http://localhost:3000/",
+    remoteAddress
   } = options;
 
   // Build the cookie header string from the cookies object only
@@ -49,7 +52,10 @@ export function createMockEvent(options: {
     headers: headersObj,
     node: {
       req: {
-        headers: allHeaders
+        headers: allHeaders,
+        ...(remoteAddress
+          ? { socket: { remoteAddress } }
+          : {})
       },
       res: {
         cookies: {}

src/server/site-context-server.ts

@@ -38,9 +38,10 @@ export interface ServerSiteEvent {
  * the raw Node request via `event.nativeEvent.node.req.headers`. We try
  * both so this works for API route handlers (`APIEvent`), the SSR document
  * handler (`PageEvent`), and tRPC procedures operating on the underlying
- * `H3Event`.
+ * `H3Event`. Also used by the analytics writers to record the site dimension
+ * (`host` column) on every row (FRE-366).
  */
-function hostFromEventLike(event: ServerSiteEvent | unknown): string | null {
+export function hostFromEventLike(event: ServerSiteEvent | unknown): string | null {
   // 1) Web FetchEvent / APIEvent / PageEvent → standard `Request` headers.
   try {
     const req = (event as { request?: Request } | null)?.request;

src/server/track-download.ts

@@ -1,5 +1,4 @@
 import type { APIEvent } from "@solidjs/start/server";
-import { getRequestIP } from "vinxi/http";
 import {
   logVisit,
   enrichAnalyticsEntry,
@@ -7,6 +6,7 @@ import {
 } from "~/server/analytics";
 import { parseUtm } from "~/server/utm";
 import { downloadPath } from "~/lib/download-asset";
+import { resolveClientIp, requestHost } from "~/server/request-client";
 
 /**
  * Record one download event under the canonical path `/api/downloads/<asset>`.
@@ -15,35 +15,75 @@ import { downloadPath } from "~/lib/download-asset";
  * label per asset to group on: the tRPC click proxy, the S3 file route that
  * serves Sparkle updates, and the Nook door.
  *
+ * The `stage` is what separates the doors within one asset label: "click"
+ * for a door the visitor chose (landing button, tRPC proxy), "served" for
+ * the file route that actually streams the DMG. Until FRE-366 both wrote the
+ * same unlabelled row, so "download click → DMG served" could not be split —
+ * one served click wrote two identical rows. `summariseDownloads()` and the
+ * /analytics downloads block still group on the path alone; the stage is a
+ * separate column precisely so that grouping cannot change.
+ *
  * Best-effort by design — a failed analytics write must never block a
  * download. Flushed rather than merely buffered: a download is low-volume and
  * the 30s batch timer is not guaranteed to survive the response on serverless.
+ */
+export async function trackDownload(
+  event: APIEvent,
+  asset: string,
+  stage: DownloadStage
+): Promise<void> {
+  await trackRequest(event, {
+    path: downloadPath(asset),
+    method: "GET",
+    stage
+  });
+}
+
+export type DownloadStage = "click" | "served";
+
+export interface TrackedRequest {
+  path: string;
+  method: string;
+  /** Funnel stage label; only download rows carry one today. */
+  stage?: string | null;
+}
+
+/**
+ * Record one server-side request event with the shared visitor dimensions:
+ * referrer, campaign tags, edge country, real client address and host.
+ *
+ * This is the one writer every measured door goes through — download doors
+ * via `trackDownload`, the checkout door directly — so the dimensions can
+ * never drift between doors. Same best-effort, flushed-immediately contract
+ * as `trackDownload`.
  *
  * `event.request` is expected to be a Fetch `Request` (true for Vinxi route
  * handlers and browser tRPC calls). A server-side `createCaller` hands over a
  * Node request, whose headers have no `get` — that throw is swallowed below,
- * so such a click is not recorded. No server-side caller downloads today.
+ * so such an event is not recorded. No server-side caller downloads today.
  */
-export async function trackDownload(
+export async function trackRequest(
   event: APIEvent,
-  asset: string
+  tracked: TrackedRequest
 ): Promise<void> {
   const { request } = event;
 
   try {
     const referrer =
       request.headers.get("referer") ?? request.headers.get("referrer");
-    const forwarded = request.headers.get("x-forwarded-for");
 
     await logVisit(
       enrichAnalyticsEntry({
-        path: downloadPath(asset),
-        method: "GET",
+        path: tracked.path,
+        method: tracked.method,
+        stage: tracked.stage ?? null,
         referrer,
         userAgent: request.headers.get("user-agent"),
-        ipAddress:
-          getRequestIP(event.nativeEvent) ??
-          (forwarded ? forwarded.split(",")[0]!.trim() : null),
+        // Behind the production proxy the direct peer is loopback; the real
+        // client address comes from the forwarded header the proxy sets —
+        // see `~/server/request-client` for the trust boundary.
+        ipAddress: resolveClientIp(event),
+        host: requestHost(event),
         // The click carries its own tags when a campaign links straight at the
         // door; otherwise the landing page's tags ride along in the referer.
         ...parseUtm(request.url, referrer),
@@ -56,6 +96,6 @@ export async function trackDownload(
     );
     await flushAnalytics();
   } catch (error) {
-    console.error(`Failed to log download of ${asset}:`, error);
+    console.error(`Failed to log ${tracked.method} ${tracked.path}:`, error);
   }
 }

src/server/trusted-client-ip.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  resolveTrustedClientIp,
+  isIpAddress,
+  isLoopbackAddress,
+  UNKNOWN_CLIENT_IP,
+  type ClientIpEventLike
+} from "./trusted-client-ip";
+
+/**
+ * Unit coverage for the security-path client-IP read (FRE-371). The caller
+ * suites (rate-limit.test.ts, report.test.ts) pin the behaviour through
+ * getClientIP and the route; this file pins the helper's own edges: the peer
+ * forms a real socket can present, the APIEvent wrapper, and failing closed.
+ */
+function event(opts: {
+  headers?: Record<string, string>;
+  remoteAddress?: string;
+  wrapped?: boolean;
+}): ClientIpEventLike {
+  const inner: ClientIpEventLike = {
+    ...(opts.remoteAddress
+      ? { node: { req: { socket: { remoteAddress: opts.remoteAddress } } } }
+      : {}),
+    request: { headers: new Headers(opts.headers ?? {}) }
+  };
+  // An APIEvent wraps its H3Event as `nativeEvent` (routes/api/* shape).
+  return opts.wrapped ? { nativeEvent: inner } : inner;
+}
+
+describe("resolveTrustedClientIp", () => {
+  it("trust order: non-loopback peer, then cf-connecting-ip, then rightmost-minus-one x-forwarded-for", () => {
+    // Peer wins.
+    expect(
+      resolveTrustedClientIp(
+        event({
+          remoteAddress: "198.51.100.23",
+          headers: {
+            "cf-connecting-ip": "203.0.113.7",
+            "x-forwarded-for": "6.6.6.6, 203.0.113.7, 10.0.0.1"
+          }
+        })
+      )
+    ).toBe("198.51.100.23");
+
+    // Loopback peer → Cloudflare's record.
+    expect(
+      resolveTrustedClientIp(
+        event({
+          remoteAddress: "127.0.0.1",
+          headers: {
+            "cf-connecting-ip": "203.0.113.7",
+            "x-forwarded-for": "6.6.6.6, 203.0.113.7, 10.0.0.1"
+          }
+        })
+      )
+    ).toBe("203.0.113.7");
+
+    // No CF header → the hop below the trusted proxy.
+    expect(
+      resolveTrustedClientIp(
+        event({
+          remoteAddress: "127.0.0.1",
+          headers: { "x-forwarded-for": "6.6.6.6, 203.0.113.7, 10.0.0.1" }
+        })
+      )
+    ).toBe("203.0.113.7");
+  });
+
+  it("reads the wrapped H3Event of an APIEvent-shaped input", () => {
+    expect(
+      resolveTrustedClientIp(
+        event({
+          wrapped: true,
+          remoteAddress: "127.0.0.1",
+          headers: { "cf-connecting-ip": "203.0.113.7" }
+        })
+      )
+    ).toBe("203.0.113.7");
+  });
+
+  it("never returns a truncated address", () => {
+    // The full /128 is the bucket key; a truncated one would pool attackers
+    // with their neighbours.
+    const ip = resolveTrustedClientIp(
+      event({
+        remoteAddress: "127.0.0.1",
+        headers: { "cf-connecting-ip": "2001:0db8:85a3:0000:0000:8a2e:0370:7334" }
+      })
+    );
+    expect(ip).toBe("2001:0db8:85a3:0000:0000:8a2e:0370:7334");
+  });
+
+  it("fails closed to the stricter unknown key", () => {
+    // One hop = the sender's own invention; a non-address hop; nothing at all.
+    expect(
+      resolveTrustedClientIp(
+        event({ headers: { "x-forwarded-for": "6.6.6.6" } })
+      )
+    ).toBe(UNKNOWN_CLIENT_IP);
+    expect(
+      resolveTrustedClientIp(
+        event({ headers: { "cf-connecting-ip": "not-an-ip" } })
+      )
+    ).toBe(UNKNOWN_CLIENT_IP);
+    expect(resolveTrustedClientIp(event({}))).toBe(UNKNOWN_CLIENT_IP);
+  });
+
+  it("recognises the loopback forms a real peer presents", () => {
+    expect(
+      resolveTrustedClientIp(
+        event({
+          // IPv6-mapped IPv4 loopback from a node socket.
+          remoteAddress: "::ffff:127.0.0.1",
+          headers: { "cf-connecting-ip": "203.0.113.7" }
+        })
+      )
+    ).toBe("203.0.113.7");
+    expect(
+      resolveTrustedClientIp(
+        event({
+          remoteAddress: "::1",
+          headers: { "cf-connecting-ip": "203.0.113.7" }
+        })
+      )
+    ).toBe("203.0.113.7");
+    // A non-loopback peer that merely looks odd is still the client.
+    expect(
+      resolveTrustedClientIp(
+        event({
+          remoteAddress: "::ffff:203.0.113.7",
+          headers: { "cf-connecting-ip": "6.6.6.6" }
+        })
+      )
+    ).toBe("203.0.113.7");
+  });
+
+  it("never believes x-real-ip", () => {
+    expect(
+      resolveTrustedClientIp(
+        event({ headers: { "x-real-ip": "203.0.113.7" } })
+      )
+    ).toBe(UNKNOWN_CLIENT_IP);
+  });
+});
+
+describe("address helpers", () => {
+  it("isIpAddress", () => {
+    expect(isIpAddress("203.0.113.7")).toBe(true);
+    expect(isIpAddress("::1")).toBe(true);
+    expect(isIpAddress("::ffff:203.0.113.7")).toBe(true);
+    expect(isIpAddress("2001:db8::1")).toBe(true);
+    expect(isIpAddress("not-an-ip")).toBe(false);
+    expect(isIpAddress("256.1.1.1")).toBe(false);
+    expect(isIpAddress("")).toBe(false);
+    expect(isIpAddress(null)).toBe(false);
+    expect(isIpAddress(undefined)).toBe(false);
+  });
+
+  it("isLoopbackAddress", () => {
+    expect(isLoopbackAddress("127.0.0.1")).toBe(true);
+    expect(isLoopbackAddress("127.255.0.3")).toBe(true);
+    expect(isLoopbackAddress("::1")).toBe(true);
+    expect(isLoopbackAddress("::ffff:127.0.0.1")).toBe(true);
+    expect(isLoopbackAddress("203.0.113.7")).toBe(false);
+    expect(isLoopbackAddress("::2")).toBe(false);
+    // Unparseable input is not loopback — fails closed.
+    expect(isLoopbackAddress("garbage")).toBe(false);
+  });
+});

src/server/trusted-client-ip.ts

@@ -0,0 +1,250 @@
+/**
+ * The client address, resolved for security decisions (FRE-371).
+ *
+ * This is the ONLY client-IP read allowed to feed a security decision — rate
+ * limiting, abuse quotas, account lockout, audit trails. It exists separately
+ * from `request-client.ts`'s `resolveClientIp` (the analytics read) on
+ * purpose:
+ *
+ *   - `resolveClientIp` carries a standing rule (FRE-369 review, 1d9287a):
+ *     it never feeds a security decision. Its blast radius is a poisoned
+ *     analytics row; ours is granting or denying access.
+ *   - Rate limiting needs the UN-truncated address; the analytics module only
+ *     ever hands out truncated prefixes.
+ *   - `request-client.ts` ships on FRE-366's branch, which is under review;
+ *     a security fix must not merge-depend on an analytics diff.
+ *
+ * The address-parsing primitives below are therefore a deliberate port of the
+ * reviewed ones, not an import. If the two ever drift, this file's version is
+ * the one security paths follow.
+ *
+ * WHY the old read was spoofable: `security.ts`'s `getClientIP` took the
+ * LEFTMOST `x-forwarded-for` hop, believing the header "cannot be spoofed".
+ * In the pinned topology — client → Cloudflare → same-host origin proxy →
+ * app — both proxies *append*, so the header arrives as
+ * `<client-supplied spoof…>, <true client>, <Cloudflare edge>` and the
+ * leftmost hop is exactly the one the sender chose. Rotating
+ * `X-Forwarded-For: <random>` per request minted a fresh rate-limit bucket
+ * and unlimited bug-report quota. `x-real-ip` was read unconditionally too;
+ * nothing in this topology overwrites it, so it is equally client text and is
+ * no longer read at all.
+ *
+ * Trust order (matches the convention FRE-366 landed after its security
+ * review, re-derived here for security stakes):
+ *
+ *   1. The direct socket peer, when it is a real routable address: it IS the
+ *      client (dev, direct hit), and any forwarded header from it is the
+ *      client describing itself — ignored.
+ *   2. `cf-connecting-ip` — reachable only when the peer is the loopback
+ *      origin proxy (or unreadable, e.g. a synthetic event in tests).
+ *      Cloudflare *overwrites* this header at the edge, so a client-supplied
+ *      value never survives. Must parse as an address.
+ *   3. `x-forwarded-for` counted from the RIGHT: drop the rightmost hop (the
+ *      Cloudflare edge address the origin proxy appended) and take the hop
+ *      before it. Never the leftmost. Must parse as an address.
+ *   4. "unknown" — callers give unknown-IP keys stricter shared limits, so
+ *      an unresolvable client fails toward a tighter bucket, never a looser
+ *      one.
+ *
+ * Deploy-side precondition this code cannot verify (same as the analytics
+ * read): the origin must be reachable only through Cloudflare and the
+ * same-host proxy. If the app is directly internet-reachable, a client can
+ * set every header read here and no in-app read can recover the truth.
+ */
+
+/** Cloudflare's "who actually connected" header: overwritten at the edge. */
+const CF_CONNECTING_IP = "cf-connecting-ip";
+const X_FORWARDED_FOR = "x-forwarded-for";
+
+/**
+ * Hops discounted from the right of `x-forwarded-for` before the value is
+ * taken: the Cloudflare edge address the origin proxy appended. Pinned to 1
+ * because there is exactly one trusted proxy between Cloudflare and the app;
+ * raise it only if the topology gains a trusted hop.
+ */
+const FORWARDED_HOPS_TO_DISCOUNT = 1;
+
+/** Returned when no trustworthy address exists. Callers rate-limit it harder. */
+export const UNKNOWN_CLIENT_IP = "unknown";
+
+/**
+ * The shapes this module reads: an H3Event (`security.ts` callers) or a
+ * SolidStart APIEvent (`routes/api/*`), which wraps its H3Event as
+ * `nativeEvent`. Every field is optional because test doubles are minimal;
+ * anything unreadable simply falls through to the next trust step.
+ */
+export interface ClientIpEventLike {
+  request?: { headers?: unknown };
+  headers?: unknown;
+  node?: {
+    req?: {
+      headers?: Record<string, unknown>;
+      socket?: { remoteAddress?: string };
+    };
+  };
+  nativeEvent?: ClientIpEventLike;
+}
+
+/**
+ * The client address for a security decision, per the trust order above.
+ * Never truncated: rate-limit buckets are per-address, and truncating would
+ * let an attacker share a bucket with the innocents behind their /24.
+ */
+export function resolveTrustedClientIp(event: ClientIpEventLike): string {
+  // An APIEvent's socket and (authoritative) headers live on the wrapped
+  // H3Event; a bare APIEvent-shaped double without one is read as-is.
+  const source = event.nativeEvent ?? event;
+
+  const peer = directPeer(source);
+  if (peer && isIpAddress(peer) && !isLoopbackAddress(peer)) return peer;
+
+  // The peer is the loopback origin proxy (or unreadable): forwarded headers
+  // may be believed, in the order above.
+  const connecting = cleanHop(headerValue(source, CF_CONNECTING_IP));
+  if (isIpAddress(connecting)) return connecting;
+
+  const hops = (headerValue(source, X_FORWARDED_FOR) ?? "")
+    .split(",")
+    .map(cleanHop)
+    .filter(Boolean);
+  const index = hops.length - 1 - FORWARDED_HOPS_TO_DISCOUNT;
+  if (index >= 0 && isIpAddress(hops[index])) return hops[index]!;
+
+  return UNKNOWN_CLIENT_IP;
+}
+
+/** The socket peer, IPv6-mapped IPv4 flattened (`::ffff:1.2.3.4` → `1.2.3.4`). */
+function directPeer(event: ClientIpEventLike): string | null {
+  try {
+    const addr = event.node?.req?.socket?.remoteAddress;
+    return addr ? addr.replace(/^::ffff:/, "") : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Header read tolerant of every event shape in play: Fetch-style
+ * `request.headers.get`, an h3 `event.headers` (Headers or plain object), and
+ * the raw node request headers. Header names are case-insensitive per HTTP;
+ * the plain-object fallbacks lowercase to match how node and the test doubles
+ * store them.
+ */
+function headerValue(event: ClientIpEventLike, name: string): string | null {
+  try {
+    const fromHeaders = (h: unknown): string | null => {
+      if (!h) return null;
+      if (typeof (h as Headers).get === "function") {
+        return (h as Headers).get(name) ?? null;
+      }
+      if (typeof h === "object") {
+        const record = h as Record<string, unknown>;
+        const value = record[name] ?? record[name.toLowerCase()];
+        return typeof value === "string" ? value : null;
+      }
+      return null;
+    };
+
+    return (
+      fromHeaders(event.request?.headers) ??
+      fromHeaders(event.headers) ??
+      fromHeaders(event.node?.req?.headers)
+    );
+  } catch {
+    return null;
+  }
+}
+
+function cleanHop(value: string | null | undefined): string {
+  return (value ?? "").trim();
+}
+
+// ── Addresses: parse and validate ───────────────────────────────────────────
+// Ported from the reviewed `request-client.ts` (FRE-366 @ 1d9287a); see the
+// header comment for why this is a copy and not an import.
+
+/** Any address this file understands: a dotted quad or an IPv6 literal. */
+export function isIpAddress(value: string | null | undefined): boolean {
+  return value !== null && value !== undefined && addressBytes(value) !== null;
+}
+
+/**
+ * Whether an address is the loopback the production proxy presents.
+ *
+ * Parses rather than string-matches, so the forms a real peer can present in —
+ * `::ffff:127.0.0.53`, `0:0:0:0:0:0:0:1`, an IPv4-mapped literal — are all
+ * recognised. An address this does not parse is *not* loopback, which fails
+ * closed: forwarded headers from an unrecognised peer are ignored rather than
+ * believed (a non-loopback peer short-circuits before headers are read).
+ */
+export function isLoopbackAddress(ip: string): boolean {
+  const bytes = addressBytes(ip);
+  if (!bytes) return false;
+  if (bytes.length === 4) return bytes[0] === 127;
+
+  // IPv6 loopback ::1 — and ::ffff:127/8, which is loopback too.
+  const mapped = ipv4FromBytes(bytes);
+  if (mapped) return isLoopbackAddress(mapped);
+  const tail = bytes[15]!;
+  return bytes.slice(0, 15).every((byte) => byte === 0) && tail === 1;
+}
+
+function isIpv4(value: string): boolean {
+  const parts = value.split(".");
+  if (parts.length !== 4) return false;
+  return parts.every(
+    (part) => /^\d{1,3}$/.test(part) && Number(part) <= 255 && !/^0\d/.test(part)
+  );
+}
+
+/** 4 bytes for IPv4, 16 for IPv6 (including `::ffff:a.b.c.d`), else null. */
+function addressBytes(value: string): number[] | null {
+  const raw = value.trim().replace(/^\[|\]$/g, "").split("%")[0]!;
+  if (isIpv4(raw)) return raw.split(".").map(Number);
+  if (!raw.includes(":")) return null;
+
+  const halves = raw.split("::");
+  if (halves.length > 2) return null;
+  const compressed = halves.length === 2;
+
+  const head = groupsToBytes(halves[0] ?? "");
+  const tail = groupsToBytes(halves[1] ?? "");
+  if (!head || !tail) return null;
+
+  const total = head.length + tail.length;
+  if (compressed) {
+    if (total > 8) return null;
+    return [...head, ...new Array(8 - total).fill(0), ...tail].flatMap(split16);
+  }
+  if (total !== 8) return null;
+  return [...head, ...tail].flatMap(split16);
+}
+
+/** One side of `::` as 16-bit groups; a trailing `1.2.3.4` counts as two. */
+function groupsToBytes(side: string): number[] | null {
+  if (side === "") return [];
+  const out: number[] = [];
+  for (const part of side.split(":")) {
+    if (/^[0-9a-fA-F]{1,4}$/.test(part)) {
+      out.push(parseInt(part, 16));
+    } else if (isIpv4(part)) {
+      const o = part.split(".").map(Number);
+      out.push((o[0]! << 8) | o[1]!, (o[2]! << 8) | o[3]!);
+    } else {
+      return null;
+    }
+  }
+  return out;
+}
+
+function split16(group: number): number[] {
+  return [(group >> 8) & 0xff, group & 0xff];
+}
+
+/** The embedded IPv4 of an IPv4-mapped IPv6 address (`::ffff:1.2.3.4`), else null. */
+function ipv4FromBytes(bytes: number[]): string | null {
+  const prefix = bytes.slice(0, 10).every((byte) => byte === 0);
+  const marker = bytes[10] === 0xff && bytes[11] === 0xff;
+  if (!prefix || !marker) return null;
+  return `${bytes[12]}.${bytes[13]}.${bytes[14]}.${bytes[15]}`;
+}

src/server/weekly-metrics.test.ts

@@ -0,0 +1,520 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import { Database } from "bun:sqlite";
+import {
+  VISITOR_ANALYTICS_ADDED_COLUMNS,
+  VISITOR_ANALYTICS_COLUMNS,
+  VISITOR_ANALYTICS_DDL,
+  VISITOR_ANALYTICS_INSERT
+} from "./analytics-schema";
+import {
+  NOOK_CHECKOUT_PATH,
+  NOOK_DOWNLOAD_PATH,
+  NOOK_HOST,
+  ensureAnalyticsSchema,
+  getWeeklyReport,
+  pickMover,
+  readCampaigns,
+  readFunnel,
+  readTraffic,
+  renderWeeklyMarkdown,
+  windowsFor,
+  type Connections,
+  type FunnelCounts,
+  type MetricsConn
+} from "./weekly-metrics";
+
+// Same reasoning as the backfill suite: the queries run real SQL, so an
+// in-memory SQLite shaped like production is the only honest stand-in. A stub
+// that returned canned rows would pass with a column or a label the live table
+// does not have.
+
+const NOOK_DDL = [
+  `CREATE TABLE trials (
+     fingerprint TEXT PRIMARY KEY,
+     started_at TEXT NOT NULL,
+     email TEXT
+   )`,
+  `CREATE TABLE licenses (
+     id TEXT PRIMARY KEY,
+     key TEXT UNIQUE NOT NULL,
+     email TEXT NOT NULL,
+     stripe_session_id TEXT UNIQUE NOT NULL,
+     created_at TEXT NOT NULL,
+     revoked INTEGER NOT NULL DEFAULT 0
+   )`,
+  `CREATE TABLE activations (
+     id TEXT PRIMARY KEY,
+     license_id TEXT NOT NULL,
+     device_fingerprint TEXT NOT NULL,
+     device_name TEXT NOT NULL,
+     activated_at TEXT NOT NULL,
+     deactivated_at TEXT
+   )`
+];
+
+function adapter(db: Database): MetricsConn {
+  return {
+    async execute(query) {
+      const args = (query.args ?? []) as never[];
+      const statement = db.query(query.sql);
+      if (/^\s*(select|pragma|with)\b/i.test(query.sql)) {
+        return { rows: statement.all(...args) as unknown[], rowsAffected: 0 };
+      }
+      return {
+        rows: [] as unknown[],
+        rowsAffected: statement.run(...args).changes
+      };
+    }
+  };
+}
+
+let analyticsDb: Database;
+let nookDb: Database;
+let conns: Connections;
+
+const NOW = new Date("2026-10-29T16:00:00Z");
+
+// A row as the post-FRE-366 writers record it: real client address, the host
+// it addressed, and a stage label where the row is a download.
+const row = (
+  overrides: Record<string, unknown>
+): Record<string, unknown> => ({
+  id: crypto.randomUUID(),
+  user_id: null,
+  path: "/",
+  method: "GET",
+  referrer: null,
+  user_agent: "Mozilla/5.0 (Macintosh)",
+  // What the writers store since the FRE-369 privacy floor: a /24 (or /56 for
+  // IPv6), never the address itself.
+  ip_address: "203.0.113.0",
+  country: "GB",
+  device_type: "desktop",
+  browser: "safari",
+  os: "macos",
+  utm_source: null,
+  utm_medium: null,
+  utm_campaign: null,
+  duration_ms: null,
+  fcp: null,
+  lcp: null,
+  cls: null,
+  fid: null,
+  inp: null,
+  ttfb: null,
+  dom_load: null,
+  load_complete: null,
+  stage: null,
+  host: NOOK_HOST,
+  ...overrides
+});
+
+function insertAnalytics(overrides: Record<string, unknown>): void {
+  const values = row(overrides);
+  analyticsDb
+    .prepare(VISITOR_ANALYTICS_INSERT)
+    .run(...(VISITOR_ANALYTICS_COLUMNS.map((column) => values[column]) as never[]));
+
+  // `created_at` is not in VISITOR_ANALYTICS_COLUMNS (it defaults to now), so
+  // the window each row belongs to has to be set after the insert.
+  if (values.created_at) {
+    analyticsDb
+      .prepare(`UPDATE VisitorAnalytics SET created_at = ? WHERE id = ?`)
+      .run(values.created_at as string, values.id as string);
+  }
+}
+
+// Inside the current window for NOW - 7 days: 2026-10-22 16:00 → 2026-10-29 16:00.
+const THIS_WEEK = "2026-10-27 10:00:00";
+// Inside the previous window: 2026-10-15 16:00 → 2026-10-22 16:00.
+const LAST_WEEK = "2026-10-18 10:00:00";
+
+beforeEach(() => {
+  analyticsDb = new Database(":memory:");
+  analyticsDb.run(VISITOR_ANALYTICS_DDL);
+  nookDb = new Database(":memory:");
+  for (const ddl of NOOK_DDL) nookDb.run(ddl);
+  conns = { analytics: adapter(analyticsDb), nook: adapter(nookDb) };
+});
+
+describe("windowsFor", () => {
+  it("puts the previous window directly before the current one", () => {
+    const windows = windowsFor(NOW, 7);
+    expect(windows.current).toEqual({
+      start: "2026-10-22 16:00:00",
+      end: "2026-10-29 16:00:00"
+    });
+    expect(windows.previous).toEqual({
+      start: "2026-10-15 16:00:00",
+      end: "2026-10-22 16:00:00"
+    });
+  });
+});
+
+describe("readFunnel", () => {
+  it("counts each stage by its own label inside its window", async () => {
+    // Page views on the Nook host count; other sites, API calls, legacy
+    // rows with no host, and the other window do not.
+    insertAnalytics({ path: "/", created_at: THIS_WEEK });
+    insertAnalytics({ path: "/downloads", created_at: THIS_WEEK });
+    insertAnalytics({ path: "/", host: "freno.me", created_at: THIS_WEEK });
+    insertAnalytics({ path: "/", host: null, created_at: THIS_WEEK });
+    insertAnalytics({ path: "/api/trpc/anything", created_at: THIS_WEEK });
+    insertAnalytics({ path: "/", created_at: LAST_WEEK });
+    // The old checkout proxy: a /checkout page view is a visit, not a
+    // started checkout.
+    insertAnalytics({ path: "/checkout", created_at: THIS_WEEK });
+
+    // The download label splits by stage; a row with no stage predates the
+    // split and counts in neither.
+    insertAnalytics({ path: NOOK_DOWNLOAD_PATH, stage: "click", created_at: THIS_WEEK });
+    insertAnalytics({ path: NOOK_DOWNLOAD_PATH, stage: "served", created_at: THIS_WEEK });
+    insertAnalytics({ path: NOOK_DOWNLOAD_PATH, stage: "served", created_at: THIS_WEEK });
+    insertAnalytics({ path: NOOK_DOWNLOAD_PATH, stage: null, created_at: THIS_WEEK });
+
+    // A created Stripe session, recorded by the checkout route itself.
+    insertAnalytics({
+      path: NOOK_CHECKOUT_PATH,
+      method: "POST",
+      created_at: THIS_WEEK
+    });
+
+    // The licence DB stores ISO-8601 with milliseconds.
+    nookDb
+      .prepare(`INSERT INTO trials (fingerprint, started_at) VALUES (?, ?)`)
+      .run("fp-1", "2026-10-28T20:28:46.806Z");
+    nookDb
+      .prepare(`INSERT INTO trials (fingerprint, started_at) VALUES (?, ?)`)
+      .run("fp-old", "2026-08-26T19:26:12.791Z");
+    nookDb
+      .prepare(
+        `INSERT INTO licenses (id, key, email, stripe_session_id, created_at)
+         VALUES (?, ?, ?, ?, ?)`
+      )
+      .run("lic-1", "NOOK-1", "buyer@example.com", "cs_1", "2026-10-25T12:00:00.000Z");
+    nookDb
+      .prepare(
+        `INSERT INTO activations (id, license_id, device_fingerprint, device_name, activated_at)
+         VALUES (?, ?, ?, ?, ?)`
+      )
+      .run("act-1", "lic-1", "device-1", "Hermes", "2026-10-25T12:05:00.000Z");
+
+    const window = windowsFor(NOW, 7).current;
+    const funnel = await readFunnel(conns, window);
+
+    expect(funnel).toEqual({
+      visit: 3, // "/", "/downloads" and the "/checkout" page view on the Nook host
+      downloadClick: 1,
+      dmgServed: 2,
+      trial: 1,
+      checkout: 1,
+      purchase: 1,
+      activation: 1
+    });
+  });
+
+  it("reports zeros against an empty database", async () => {
+    const window = windowsFor(NOW, 7).current;
+    expect(await readFunnel(conns, window)).toEqual({
+      visit: 0,
+      downloadClick: 0,
+      dmgServed: 0,
+      trial: 0,
+      checkout: 0,
+      purchase: 0,
+      activation: 0
+    });
+  });
+});
+
+describe("readTraffic", () => {
+  it("separates legacy rows, live loopback and automation from clean traffic", async () => {
+    // Post-instrumentation rows: host set. Two of them still loopback — in the
+    // truncated shapes the privacy floor writes — which is the shape the report
+    // must flag as "the fix is not live".
+    insertAnalytics({
+      path: NOOK_DOWNLOAD_PATH,
+      stage: "click",
+      created_at: THIS_WEEK
+    });
+    insertAnalytics({
+      path: NOOK_DOWNLOAD_PATH,
+      stage: "served",
+      ip_address: "127.0.0.0",
+      user_agent: "The Nook/0.13.4 Sparkle/2.9.6",
+      created_at: THIS_WEEK
+    });
+    insertAnalytics({
+      path: "/",
+      ip_address: "0:0:0:0:0:0:0:0",
+      created_at: THIS_WEEK
+    });
+    insertAnalytics({ path: "/", created_at: THIS_WEEK });
+
+    // Pre-instrumentation rows: no host, proxy's address — legacy, never
+    // counted as "the fix is not live".
+    insertAnalytics({
+      path: NOOK_DOWNLOAD_PATH,
+      stage: null,
+      host: null,
+      ip_address: "127.0.0.1",
+      user_agent: "curl/8.7.1",
+      created_at: THIS_WEEK
+    });
+    insertAnalytics({
+      path: "/",
+      host: null,
+      ip_address: "::1",
+      created_at: THIS_WEEK
+    });
+
+    const traffic = await readTraffic(conns, windowsFor(NOW, 7).current);
+
+    expect(traffic).toEqual({
+      analyticsRows: 6,
+      hostRows: 4,
+      legacyRows: 2,
+      hostLoopbackRows: 2,
+      downloadRows: 3,
+      downloadClickRows: 1,
+      downloadServedRows: 1,
+      downloadUnstagedRows: 1,
+      downloadNonBrowserRows: 2
+    });
+  });
+});
+
+describe("readCampaigns", () => {
+  it("groups tagged rows, excludes untagged, and orders by volume", async () => {
+    insertAnalytics({
+      path: "/",
+      utm_source: "hn",
+      utm_medium: "post",
+      utm_campaign: "launch",
+      created_at: THIS_WEEK
+    });
+    insertAnalytics({
+      path: "/",
+      utm_source: "hn",
+      utm_medium: "post",
+      utm_campaign: "launch",
+      created_at: THIS_WEEK
+    });
+    insertAnalytics({
+      path: "/",
+      utm_source: "r_macapps",
+      utm_campaign: "week2",
+      created_at: THIS_WEEK
+    });
+    insertAnalytics({ path: "/", created_at: THIS_WEEK });
+
+    const campaigns = await readCampaigns(conns.analytics, windowsFor(NOW, 7).current);
+
+    expect(campaigns).toEqual([
+      { source: "hn", medium: "post", campaign: "launch", count: 2 },
+      { source: "r_macapps", medium: null, campaign: "week2", count: 1 }
+    ]);
+  });
+
+  it("caps the list at ten rows", async () => {
+    for (let i = 0; i < 12; i += 1) {
+      insertAnalytics({
+        path: "/",
+        utm_source: `source-${i}`,
+        created_at: THIS_WEEK
+      });
+    }
+
+    const campaigns = await readCampaigns(conns.analytics, windowsFor(NOW, 7).current);
+    expect(campaigns.length).toBe(10);
+  });
+});
+
+describe("ensureAnalyticsSchema", () => {
+  it("adds the post-hoc columns to a table that predates them, idempotently", async () => {
+    // The table as production held it before any post-hoc column existed.
+    // (`created_at` is not in the insert column list — it defaults DB-side —
+    // so the simulated table has to name it explicitly.)
+    const oldDb = new Database(":memory:");
+    const withoutAdded = [
+      ...VISITOR_ANALYTICS_COLUMNS.filter(
+        (c) => !VISITOR_ANALYTICS_ADDED_COLUMNS.some((a) => a.name === c)
+      ),
+      "created_at"
+    ];
+    oldDb.run(
+      `CREATE TABLE VisitorAnalytics (${withoutAdded.map((c) => `${c} TEXT`).join(", ")})`
+    );
+    const oldConn = adapter(oldDb);
+
+    await ensureAnalyticsSchema(oldConn);
+    await ensureAnalyticsSchema(oldConn); // a second run is a no-op
+
+    // The writers' full INSERT — stage and host included — now works.
+    const values = row({ stage: "click", path: NOOK_DOWNLOAD_PATH });
+    expect(() =>
+      oldDb
+        .prepare(VISITOR_ANALYTICS_INSERT)
+        .run(
+          ...(VISITOR_ANALYTICS_COLUMNS.map((c) => values[c]) as never[])
+        )
+    ).not.toThrow();
+    oldDb
+      .prepare(`UPDATE VisitorAnalytics SET created_at = ? WHERE id = ?`)
+      .run(THIS_WEEK, values.id as string);
+
+    // And the funnel reads its stage split from the migrated table.
+    const funnel = await readFunnel(
+      { analytics: oldConn, nook: conns.nook },
+      windowsFor(NOW, 7).current
+    );
+    expect(funnel.downloadClick).toBe(1);
+  });
+});
+
+describe("pickMover", () => {
+  const base: FunnelCounts = {
+    visit: 0,
+    downloadClick: 0,
+    dmgServed: 0,
+    trial: 0,
+    checkout: 0,
+    purchase: 0,
+    activation: 0
+  };
+
+  it("picks the stage with the largest absolute change", () => {
+    const mover = pickMover(
+      { ...base, visit: 61, dmgServed: 156, trial: 2 },
+      { ...base, visit: 56 }
+    );
+    expect(mover).toEqual({
+      key: "dmgServed",
+      label: "DMG served",
+      now: 156,
+      before: 0,
+      delta: 156
+    });
+  });
+
+  it("breaks ties toward the earlier stage", () => {
+    const mover = pickMover(
+      { ...base, visit: 5, downloadClick: 5 },
+      { ...base, visit: 0, downloadClick: 0 }
+    );
+    expect(mover?.key).toBe("visit");
+  });
+
+  it("returns null when nothing moved", () => {
+    expect(pickMover({ ...base, visit: 3 }, { ...base, visit: 3 })).toBeNull();
+  });
+});
+
+describe("getWeeklyReport / renderWeeklyMarkdown", () => {
+  it("renders seven distinct stages with no merged-label or proxy caveats", async () => {
+    insertAnalytics({ path: "/", created_at: THIS_WEEK });
+    insertAnalytics({ path: NOOK_DOWNLOAD_PATH, stage: "click", created_at: THIS_WEEK });
+    insertAnalytics({
+      path: NOOK_DOWNLOAD_PATH,
+      stage: "served",
+      created_at: THIS_WEEK
+    });
+    insertAnalytics({
+      path: NOOK_DOWNLOAD_PATH,
+      stage: "served",
+      created_at: THIS_WEEK
+    });
+    insertAnalytics({ path: NOOK_CHECKOUT_PATH, method: "POST", created_at: THIS_WEEK });
+    nookDb
+      .prepare(`INSERT INTO trials (fingerprint, started_at) VALUES (?, ?)`)
+      .run("fp-1", "2026-10-28T20:28:46.806Z");
+
+    const report = await getWeeklyReport(conns, { now: NOW, days: 7 });
+    const markdown = renderWeeklyMarkdown(report);
+
+    expect(markdown).toContain(
+      "Window: **2026-10-22 16:00:00 → 2026-10-29 16:00:00 UTC** (7 days)"
+    );
+    expect(markdown).toContain(`| visit (${NOOK_HOST} page views) | 1 | 0 | +1 |`);
+    expect(markdown).toContain("| download click | 1 | 0 | +1 |");
+    expect(markdown).toContain("| DMG served | 2 | 0 | +2 |");
+    expect(markdown).toContain("| checkout started (Stripe session) | 1 | 0 | +1 |");
+
+    const order = [
+      `visit (${NOOK_HOST} page views)`,
+      "download click",
+      "DMG served",
+      "trial started",
+      "checkout started (Stripe session)",
+      "purchase (licence issued)",
+      "activation"
+    ];
+    for (let i = 1; i < order.length; i += 1) {
+      expect(markdown.indexOf(order[i - 1]!)).toBeLessThan(
+        markdown.indexOf(order[i]!)
+      );
+    }
+
+    // The caveats this issue retired stay retired.
+    expect(markdown).not.toContain("one label");
+    expect(markdown).not.toContain("not recorded");
+    expect(markdown).not.toContain("no host dimension");
+    expect(markdown).not.toContain("†");
+
+    expect(report.mover?.key).toBe("dmgServed");
+    expect(markdown).toContain("**DMG served: 0 → 2 (+2).**");
+  });
+
+  it("states what pre-instrumentation rows cannot say, computed from the window", async () => {
+    insertAnalytics({ path: "/", created_at: THIS_WEEK });
+    // Legacy rows: no host, proxy's address, no stage label.
+    insertAnalytics({ path: "/", host: null, ip_address: "127.0.0.1", created_at: THIS_WEEK });
+    insertAnalytics({
+      path: NOOK_DOWNLOAD_PATH,
+      stage: null,
+      host: null,
+      ip_address: "127.0.0.1",
+      user_agent: "curl/8.7.1",
+      created_at: THIS_WEEK
+    });
+
+    const report = await getWeeklyReport(conns, { now: NOW, days: 7 });
+    const markdown = renderWeeklyMarkdown(report);
+
+    expect(markdown).toContain(
+      "2 of 3 rows in the window predate the FRE-366 instrumentation"
+    );
+    expect(markdown).toContain("predate the click/served stage label");
+    // Legacy loopback is not "the fix is not live".
+    expect(markdown).not.toContain("still carry a loopback address");
+  });
+
+  it("flags loopback only when rows recorded since the instrumentation carry it", async () => {
+    // Both spellings a live writer can produce: the raw proxy address, and the
+    // /24 the privacy floor stores instead of it.
+    insertAnalytics({ path: "/", ip_address: "127.0.0.1", created_at: THIS_WEEK });
+    insertAnalytics({ path: "/", ip_address: "127.0.53.0", created_at: THIS_WEEK });
+
+    const report = await getWeeklyReport(conns, { now: NOW, days: 7 });
+    const markdown = renderWeeklyMarkdown(report);
+
+    expect(markdown).toContain(
+      "2 rows recorded since the instrumentation still carry a loopback address"
+    );
+  });
+
+  it("says nothing moved rather than inventing a winner", async () => {
+    const report = await getWeeklyReport(conns, { now: NOW, days: 7 });
+    const markdown = renderWeeklyMarkdown(report);
+
+    expect(report.mover).toBeNull();
+    expect(markdown).toContain("_Nothing moved: every stage held its previous-week value._");
+    expect(markdown).toContain("_No tagged traffic in the window._");
+  });
+
+  it("rejects a window that is not a positive number of days", async () => {
+    await expect(getWeeklyReport(conns, { now: NOW, days: 0 })).rejects.toThrow(
+      "days must be a positive number"
+    );
+  });
+});

src/server/weekly-metrics.ts

@@ -0,0 +1,647 @@
+/**
+ * The weekly funnel reading: `marketing/metrics/weekly.md`'s data half.
+ *
+ * The funnel the marketing cluster agreed on is
+ *
+ *   visit → download click → DMG served → trial started → checkout started
+ *         → purchase → activation
+ *
+ * and this module reads it from the two live databases, plus the campaign
+ * dimension the /analytics page already exposes through
+ * `getAnalyticsSummary.topCampaigns`.
+ *
+ * Two properties matter more than the numbers:
+ *
+ *  - It takes both connections as arguments. `~/server/analytics` imports the
+ *    full server env (Stripe keys, Apple secret, licence key …); the weekly
+ *    job only needs the two databases, and must be runnable from a checkout
+ *    whose `.env` carries nothing else. The SQL here is the same shape as the
+ *    analytics summaries, so the weekly read and the dashboard cannot drift
+ *    into different label sets.
+ *  - Every stage is measured by its own label. FRE-366 gave the funnel that:
+ *    the download door and the DMG file route record distinct `stage` values
+ *    (`click` / `served`), a created Stripe checkout session records its own
+ *    row, and every row carries the real client address and the host it
+ *    addressed, so the visit stage scopes to the Nook. Rows that predate
+ *    that instrumentation are stated next to the numbers, never silently
+ *    counted (see `renderWeeklyMarkdown`).
+ *
+ * No `~/env`, no `~/server/database`: the caller owns the connections, the
+ * tests own an in-memory SQLite, and the script owns the libsql clients.
+ */
+
+import { DOWNLOAD_PATH_PREFIX } from "~/lib/download-asset";
+import {
+  VISITOR_ANALYTICS_ADDED_COLUMNS,
+  VISITOR_ANALYTICS_DDL
+} from "~/server/analytics-schema";
+
+/** The one asset key the Nook lands under — `downloadPath("thenook")`. */
+export const NOOK_DOWNLOAD_PATH = `${DOWNLOAD_PATH_PREFIX}thenook`;
+
+/** The host the visit stage scopes to. Recorded per row since FRE-366. */
+export const NOOK_HOST = "nook.freno.me";
+
+/** The path a created Stripe checkout session records (FRE-366). */
+export const NOOK_CHECKOUT_PATH = "/api/the-nook/checkout";
+
+/** An `execute`-shaped connection: the libsql client and the test adapter both fit. */
+export interface MetricsConn {
+  execute(query: {
+    sql: string;
+    args?: any[];
+  }): Promise<{ rows: unknown[]; rowsAffected?: number }>;
+}
+
+export interface Connections {
+  /** freno.me Turso DB — VisitorAnalytics. */
+  analytics: MetricsConn;
+  /** the-nook Turso DB — trials, licenses, activations. */
+  nook: MetricsConn;
+}
+
+export type StageKey =
+  | "visit"
+  | "downloadClick"
+  | "dmgServed"
+  | "trial"
+  | "checkout"
+  | "purchase"
+  | "activation";
+
+export interface StageDef {
+  key: StageKey;
+  label: string;
+}
+
+/**
+ * The seven agreed stages, each with its own label in the data:
+ * `downloadClick` and `dmgServed` split what used to be one merged download
+ * label (the `stage` column, FRE-366), and `checkout` reads created Stripe
+ * sessions instead of the /checkout page-view proxy.
+ */
+export const STAGES: StageDef[] = [
+  { key: "visit", label: `visit (${NOOK_HOST} page views)` },
+  { key: "downloadClick", label: "download click" },
+  { key: "dmgServed", label: "DMG served" },
+  { key: "trial", label: "trial started" },
+  { key: "checkout", label: "checkout started (Stripe session)" },
+  { key: "purchase", label: "purchase (licence issued)" },
+  { key: "activation", label: "activation" }
+];
+
+export interface FunnelCounts {
+  visit: number;
+  downloadClick: number;
+  dmgServed: number;
+  trial: number;
+  checkout: number;
+  purchase: number;
+  activation: number;
+}
+
+export interface CampaignRow {
+  source: string | null;
+  medium: string | null;
+  campaign: string | null;
+  count: number;
+}
+
+/** Traffic-shape facts the report has to state next to the funnel. */
+export interface WindowTraffic {
+  analyticsRows: number;
+  /** Rows carrying a host — written since the FRE-366 instrumentation. */
+  hostRows: number;
+  /** Rows with no host — pre-FRE-366; their address is the proxy's loopback. */
+  legacyRows: number;
+  /** Post-instrumentation rows still recording loopback: the fix is not live. */
+  hostLoopbackRows: number;
+  downloadRows: number;
+  downloadClickRows: number;
+  downloadServedRows: number;
+  /** Download rows with no stage label — they predate FRE-366 and cannot be split. */
+  downloadUnstagedRows: number;
+  downloadNonBrowserRows: number;
+}
+
+export interface Mover {
+  key: StageKey;
+  label: string;
+  now: number;
+  before: number;
+  delta: number;
+}
+
+export interface WeeklyReport {
+  window: { start: string; end: string; days: number };
+  previous: { start: string; end: string };
+  counts: FunnelCounts;
+  previousCounts: FunnelCounts;
+  campaigns: CampaignRow[];
+  taggedRows: number;
+  traffic: WindowTraffic;
+  mover: Mover | null;
+  generatedAt: string;
+}
+
+/**
+ * A recorded address that is not a visitor, in every spelling the column can
+ * hold: the proxy the request came through (`127.0.0.1`, `::1`, an IPv4-mapped
+ * form) *and* the prefixes the FRE-369 privacy floor writes instead of them
+ * (`127.0.0.0`, all-zero IPv6). Whole `127/8` because truncation keeps the first
+ * three octets, so `127.0.53.1` and `127.0.53.0` are the same non-visitor.
+ */
+const LOOPBACK_SQL = `(ip_address LIKE '127.%'
+     OR ip_address LIKE '::ffff:127.%'
+     OR ip_address IN ('::1', '0:0:0:0:0:0:0:1', '0:0:0:0:0:0:0:0'))`;
+
+/** SQLite's `datetime()` string, UTC: `YYYY-MM-DD HH:MM:SS`. */
+export function sqlTime(date: Date): string {
+  return date.toISOString().slice(0, 19).replace("T", " ");
+}
+
+export interface Windows {
+  current: { start: string; end: string };
+  previous: { start: string; end: string };
+}
+
+/**
+ * The current window is `[now - days, now)` and the previous one sits directly
+ * before it, so a weekly read always compares like with like. Boundaries are
+ * passed as SQL parameters rather than `datetime('now', …)` so the file a run
+ * writes is reproducible and the two queries cannot straddle a second.
+ */
+export function windowsFor(now: Date, days: number): Windows {
+  const span = days * 24 * 60 * 60 * 1000;
+  const end = now;
+  const start = new Date(end.getTime() - span);
+  const previousEnd = start;
+  const previousStart = new Date(previousEnd.getTime() - span);
+
+  return {
+    current: { start: sqlTime(start), end: sqlTime(end) },
+    previous: { start: sqlTime(previousStart), end: sqlTime(previousEnd) }
+  };
+}
+
+function toNumber(value: unknown): number {
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string") return Number(value) || 0;
+  return 0;
+}
+
+async function scalar(
+  conn: MetricsConn,
+  sql: string,
+  args: any[]
+): Promise<number> {
+  const result = await conn.execute({ sql, args });
+  const row = result.rows[0] as Record<string, unknown> | undefined;
+  if (!row) return 0;
+  return toNumber(Object.values(row)[0]);
+}
+
+/**
+ * Bring the analytics table up to the schema the readers expect, through the
+ * same idempotent bootstrap path the app server uses (`analytics.ts`): the
+ * DDL is a no-op against the live table and each post-hoc column is ALTERed
+ * in only when absent. The weekly job runs against databases the app may not
+ * have migrated yet — a fresh checkout, a restored backup, or production
+ * before the next deploy — and must render its seven stages regardless.
+ */
+export async function ensureAnalyticsSchema(conn: MetricsConn): Promise<void> {
+  await conn.execute({ sql: VISITOR_ANALYTICS_DDL });
+
+  const info = await conn.execute({
+    sql: `PRAGMA table_info(VisitorAnalytics)`
+  });
+  const present = new Set(info.rows.map((row) => String((row as any).name)));
+  for (const column of VISITOR_ANALYTICS_ADDED_COLUMNS) {
+    if (!present.has(column.name)) {
+      await conn.execute({ sql: column.ddl });
+    }
+  }
+}
+
+async function countInWindow(
+  conn: MetricsConn,
+  sql: string,
+  start: string,
+  end: string
+): Promise<number> {
+  return scalar(conn, sql, [start, end]);
+}
+
+/** One window's funnel. Two databases, one call. */
+export async function readFunnel(
+  conns: Connections,
+  window: { start: string; end: string }
+): Promise<FunnelCounts> {
+  const { analytics, nook } = conns;
+  const { start, end } = window;
+
+  // Scoped to the Nook host (FRE-366): before the host column existed, a
+  // page view of `/` on nook.freno.me was the same row as freno.me's root.
+  // Pre-instrumentation rows carry no host and are excluded — the traffic
+  // section states how many.
+  const visit = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ?
+     AND path NOT LIKE '/api/%'
+     AND host = ?`,
+    [start, end, NOOK_HOST]
+  );
+
+  const downloadClick = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ?
+     AND path = ? AND stage = 'click'`,
+    [start, end, NOOK_DOWNLOAD_PATH]
+  );
+
+  const dmgServed = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ?
+     AND path = ? AND stage = 'served'`,
+    [start, end, NOOK_DOWNLOAD_PATH]
+  );
+
+  // Created Stripe checkout sessions, recorded by the checkout route itself
+  // (FRE-366) — not the /checkout page view that used to proxy for them.
+  const checkout = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ?
+     AND path = ?`,
+    [start, end, NOOK_CHECKOUT_PATH]
+  );
+
+  // The licence DB stores ISO-8601 (`2026-10-28T20:28:46.806Z`); the analytics
+  // DB stores `YYYY-MM-DD HH:MM:SS`. `datetime()` normalises both sides so a
+  // boundary seconds apart cannot include or drop a row on string comparison.
+  const trial = await scalar(
+    nook,
+    `SELECT COUNT(*) AS n FROM trials
+     WHERE datetime(started_at) >= datetime(?) AND datetime(started_at) < datetime(?)`,
+    [start, end]
+  );
+
+  const purchase = await scalar(
+    nook,
+    `SELECT COUNT(*) AS n FROM licenses
+     WHERE datetime(created_at) >= datetime(?) AND datetime(created_at) < datetime(?)`,
+    [start, end]
+  );
+
+  const activation = await scalar(
+    nook,
+    `SELECT COUNT(*) AS n FROM activations
+     WHERE datetime(activated_at) >= datetime(?) AND datetime(activated_at) < datetime(?)`,
+    [start, end]
+  );
+
+  return {
+    visit,
+    downloadClick,
+    dmgServed,
+    trial,
+    checkout,
+    purchase,
+    activation
+  };
+}
+
+/**
+ * Traffic shape for one window: how much of it predates the FRE-366
+ * instrumentation (no host, proxy's address), whether rows recorded since
+ * still see loopback (which would mean the forwarded-header fix is not
+ * live), and how the download label splits. Without these facts the numbers
+ * read as demand, which they are not.
+ */
+export async function readTraffic(
+  conns: Connections,
+  window: { start: string; end: string }
+): Promise<WindowTraffic> {
+  const { analytics } = conns;
+  const { start, end } = window;
+
+  const analyticsRows = await countInWindow(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ?`,
+    start,
+    end
+  );
+
+  const hostRows = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ?
+     AND host IS NOT NULL`,
+    [start, end]
+  );
+
+  const legacyRows = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ?
+     AND host IS NULL`,
+    [start, end]
+  );
+
+  const hostLoopbackRows = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ?
+     AND host IS NOT NULL
+     AND ${LOOPBACK_SQL}`,
+    [start, end]
+  );
+
+  const downloadRows = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ? AND path = ?`,
+    [start, end, NOOK_DOWNLOAD_PATH]
+  );
+
+  const downloadClickRows = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ? AND path = ? AND stage = 'click'`,
+    [start, end, NOOK_DOWNLOAD_PATH]
+  );
+
+  const downloadServedRows = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ? AND path = ? AND stage = 'served'`,
+    [start, end, NOOK_DOWNLOAD_PATH]
+  );
+
+  const downloadUnstagedRows = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ? AND path = ? AND stage IS NULL`,
+    [start, end, NOOK_DOWNLOAD_PATH]
+  );
+
+  // Anything whose UA is not a browser engine: curl, Sparkle's updater,
+  // link-preview crawlers. A real install click arrives as `Mozilla/5.0 …`.
+  const downloadNonBrowserRows = await scalar(
+    analytics,
+    `SELECT COUNT(*) AS n FROM VisitorAnalytics
+     WHERE created_at >= ? AND created_at < ? AND path = ?
+     AND (user_agent IS NULL OR user_agent NOT LIKE 'Mozilla/%')`,
+    [start, end, NOOK_DOWNLOAD_PATH]
+  );
+
+  return {
+    analyticsRows,
+    hostRows,
+    legacyRows,
+    hostLoopbackRows,
+    downloadRows,
+    downloadClickRows,
+    downloadServedRows,
+    downloadUnstagedRows,
+    downloadNonBrowserRows
+  };
+}
+
+/**
+ * The campaign dimension, grouped exactly as `getAnalyticsSummary.topCampaigns`
+ * groups it: top 10 by volume, untagged rows excluded (the untagged bucket is
+ * a different question and would otherwise swallow the list).
+ */
+export async function readCampaigns(
+  analytics: MetricsConn,
+  window: { start: string; end: string }
+): Promise<CampaignRow[]> {
+  const result = await analytics.execute({
+    sql: `SELECT utm_source, utm_medium, utm_campaign, COUNT(*) AS count
+          FROM VisitorAnalytics
+          WHERE created_at >= ? AND created_at < ?
+          AND (utm_source IS NOT NULL OR utm_medium IS NOT NULL OR utm_campaign IS NOT NULL)
+          GROUP BY utm_source, utm_medium, utm_campaign
+          ORDER BY count DESC
+          LIMIT 10`,
+    args: [window.start, window.end]
+  });
+
+  return result.rows.map((raw) => {
+    const row = raw as Record<string, unknown>;
+    return {
+      source: (row.utm_source as string | null) ?? null,
+      medium: (row.utm_medium as string | null) ?? null,
+      campaign: (row.utm_campaign as string | null) ?? null,
+      count: toNumber(row.count)
+    };
+  });
+}
+
+/**
+ * "The one thing that moved": the stage with the largest absolute change
+ * against the previous window. Ties go to the earlier stage, so a week when
+ * nothing moved returns null rather than a made-up winner.
+ */
+export function pickMover(
+  current: FunnelCounts,
+  previous: FunnelCounts
+): Mover | null {
+  let best: Mover | null = null;
+
+  for (const stage of STAGES) {
+    const delta = current[stage.key] - previous[stage.key];
+    if (delta === 0) continue;
+    if (!best || Math.abs(delta) > Math.abs(best.delta)) {
+      best = {
+        key: stage.key,
+        label: stage.label,
+        now: current[stage.key],
+        before: previous[stage.key],
+        delta
+      };
+    }
+  }
+
+  return best;
+}
+
+export interface ReportOptions {
+  /** End of the current window; defaults to the wall clock. */
+  now?: Date;
+  /** Window length in days; defaults to 7. */
+  days?: number;
+}
+
+/** Read everything `.md` needs, in one call. */
+export async function getWeeklyReport(
+  conns: Connections,
+  options: ReportOptions = {}
+): Promise<WeeklyReport> {
+  const days = options.days ?? 7;
+  if (!Number.isFinite(days) || days <= 0) {
+    throw new Error(`days must be a positive number, got ${days}`);
+  }
+
+  const now = options.now ?? new Date();
+  const windows = windowsFor(now, days);
+
+  const [counts, previousCounts, traffic, campaigns] = await Promise.all([
+    readFunnel(conns, windows.current),
+    readFunnel(conns, windows.previous),
+    readTraffic(conns, windows.current),
+    readCampaigns(conns.analytics, windows.current)
+  ]);
+
+  return {
+    window: { ...windows.current, days },
+    previous: windows.previous,
+    counts,
+    previousCounts,
+    campaigns,
+    taggedRows: campaigns.reduce((sum, row) => sum + row.count, 0),
+    traffic,
+    mover: pickMover(counts, previousCounts),
+    generatedAt: now.toISOString().replace(/\.\d{3}Z$/, "Z")
+  };
+}
+
+function cell(value: string | null): string {
+  return value === null || value === "" ? "—" : value;
+}
+
+function signed(value: number): string {
+  if (value === 0) return "0";
+  return value > 0 ? `+${value}` : `−${Math.abs(value)}`;
+}
+
+/**
+ * Render the weekly file. Interpretation lives in the CMO's read; this renderer
+ * only states what the data is, what moved, and what the numbers cannot say.
+ * The Gaps section is not boilerplate: each bullet is computed from the window
+ * it describes, so it empties itself if the underlying hole is ever fixed.
+ */
+export function renderWeeklyMarkdown(report: WeeklyReport): string {
+  const { counts, previousCounts, traffic } = report;
+  const lines: string[] = [];
+
+  lines.push("# Weekly funnel snapshot");
+  lines.push("");
+  lines.push(
+    `Window: **${report.window.start} → ${report.window.end} UTC** (${report.window.days} days). ` +
+      `Previous: ${report.previous.start} → ${report.previous.end} UTC.`
+  );
+  lines.push("");
+  lines.push(
+    "Generated by `bun --env-file=.env scripts/weekly-metrics.ts`; regenerated " +
+      "weekly, never hand-edited. The analysis is the CMO's."
+  );
+  lines.push("");
+
+  lines.push("## Funnel");
+  lines.push("");
+  lines.push("| Stage | This week | Last week | Change |");
+  lines.push("|---|---:|---:|---:|");
+  for (const stage of STAGES) {
+    const now = counts[stage.key];
+    const before = previousCounts[stage.key];
+    lines.push(`| ${stage.label} | ${now} | ${before} | ${signed(now - before)} |`);
+  }
+  lines.push("");
+
+  lines.push("## Campaigns");
+  lines.push("");
+  if (report.campaigns.length === 0) {
+    lines.push("_No tagged traffic in the window._");
+  } else {
+    lines.push(
+      "Top 10 by volume, untagged excluded — the same grouping " +
+        "`getAnalyticsSummary.topCampaigns` returns."
+    );
+    lines.push("");
+    lines.push("| Source | Medium | Campaign | Rows |");
+    lines.push("|---|---|---|---:|");
+    for (const row of report.campaigns) {
+      lines.push(
+        `| ${cell(row.source)} | ${cell(row.medium)} | ${cell(row.campaign)} | ${row.count} |`
+      );
+    }
+  }
+  lines.push("");
+  lines.push(
+    `${report.taggedRows} of ${traffic.analyticsRows} rows in the window carry ` +
+      `campaign tags; the rest are untagged and therefore unattributed.`
+  );
+  lines.push("");
+
+  lines.push("## The one thing that moved");
+  lines.push("");
+  if (!report.mover) {
+    lines.push("_Nothing moved: every stage held its previous-week value._");
+  } else {
+    const mover = report.mover;
+    lines.push(
+      `**${mover.label}: ${mover.before} → ${mover.now} (${signed(mover.delta)}).**`
+    );
+  }
+  lines.push("");
+
+  lines.push("## Before acting on these numbers");
+  lines.push("");
+
+  if (traffic.legacyRows > 0) {
+    lines.push(
+      `- **${traffic.legacyRows} of ${traffic.analyticsRows} rows in the window predate the FRE-366 instrumentation.** ` +
+        `They carry no host, and their recorded address is the production proxy's loopback ` +
+        `(127.0.0.1 / ::1) — the writers then recorded the direct peer, not the visitor. ` +
+        `They are excluded from every host-scoped stage above (visits, and the download ` +
+        `click/served split), and "unique visitors" over them still collapses to one host. ` +
+        `Rows recorded since carry the site they addressed and the visitor's address ` +
+        `truncated to a prefix (/24, or /56 for IPv6 — the FRE-369 privacy floor), so ` +
+        `"unique visitors" counts networks, not machines.`
+    );
+  }
+
+  if (traffic.hostLoopbackRows > 0) {
+    lines.push(
+      `- **${traffic.hostLoopbackRows} rows recorded since the instrumentation still carry a ` +
+        `loopback address** — the forwarded-header fix is not taking effect in production ` +
+        `(no \`cf-connecting-ip\`, and no usable \`x-forwarded-for\` hop). Do not trust ` +
+        `per-channel reach until this is zero.`
+    );
+  }
+
+  if (traffic.downloadRows > 0) {
+    lines.push(
+      `- **Download rows are automation-heavy.** Of this window's ${traffic.downloadRows} ` +
+        `download rows, ${traffic.downloadClickRows} are clicks and ` +
+        `${traffic.downloadServedRows} are served files` +
+        (traffic.downloadUnstagedRows > 0
+          ? `; the remaining ${traffic.downloadUnstagedRows} predate the click/served stage ` +
+            `label and cannot be split, so they count in neither stage`
+          : "") +
+        `. ${traffic.downloadNonBrowserRows} of all ${traffic.downloadRows} are not browser ` +
+        `user agents (curl, Sparkle, link-preview crawlers).`
+    );
+  }
+
+  lines.push(
+    `- **No conversion rate before the cohort matures.** Trial→paid belongs to the mature ` +
+      `Day 28–35 read (FRE-197); a ratio from a partial cohort is not a metric.`
+  );
+  lines.push("");
+  lines.push("## Sources");
+  lines.push("");
+  lines.push("- `VisitorAnalytics` (freno.me Turso DB) — visits, downloads, campaigns.");
+  lines.push("- `trials`, `licenses`, `activations` (the-nook Turso DB) — the paid funnel.");
+  lines.push(`- Generated ${report.generatedAt}.`);
+  lines.push("");
+
+  return lines.join("\n");
+}

vercel.json

@@ -57,6 +57,7 @@
     }
   ],
   "crons": [
+    { "path": "/api/analytics-retention", "schedule": "0 12 * * *" },
     { "path": "/api/the-nook/lifecycle", "schedule": "0 13 * * *" }
   ]
 }