Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

docs(seo): voice kit for blog drafting (#1246)

Goldflaga552e8eed0eb
diff --git a/ops/seo/voice/opinions.md b/ops/seo/voice/opinions.md
new file mode 100644
index 000000000..d6265b557
--- /dev/null
+++ b/ops/seo/voice/opinions.md
@@ -0,0 +1,70 @@
+# Positions Rybbit takes
+
+> Used by /blog-post: a post may argue a position only if it's listed here with `status: approved`. Candidates can be drafted into a post only after Bill flips them to approved.
+> Each position must stay true to the product as described in [stats.md](stats.md); if the code changes, update or retire the position.
+
+All entries below are `status: candidate`, drafted 2026-09-28 for Bill's review. "Where the site says it" points to existing copy, so an approved position is already consistent with live pages.
+
+## Privacy and tracking
+
+### Analytics shouldn't need a cookie banner
+- status: candidate
+- Why: a consent banner hides the visitors who decline, so cookie-based analytics undercounts exactly the traffic you're trying to measure; cookieless tracking avoids the banner for analytics.
+- Where the site says it: homepage subtitle, "Rybbit is open-source, cookieless analytics. No consent banner needed." (`docs/src/app/[locale]/(home)/page.tsx:33`); `blog/best-google-analytics-alternatives.mdx:46`.
+- Guardrail: don't quote a specific "% of traffic lost to banners" unless it comes from a cited study.
+
+### Privacy defaults should be honest about their trade-offs
+- status: candidate
+- Why: Rybbit's daily salt is opt-in because it breaks multi-day retention and returning-visitor counts; saying so plainly beats implying maximum anonymity by default.
+- Where the site says it: `features/retention/feature-data.tsx:136` and `compare/umami/comparison-data.tsx:288` describe the opt-in salt correctly. Several other pages don't (see "Known drift" in stats.md).
+
+### Don't store what you don't need
+- status: candidate
+- Why: IP storage is off by default and inputs are masked in replay by default; the default should be the safe setting and the risky one should be a deliberate choice.
+- Where the site says it: `blog/hotjar-alternatives.mdx` ("Input values are masked by default"). Defaults verified in stats.md.
+
+## Product
+
+### One dashboard should answer the first question in seconds
+- status: candidate
+- Why: GA4 buries simple questions under report menus; most sites need traffic, sources, pages and conversions on one screen, with depth one click down.
+- Where the site says it: PRODUCT.md "Answer first, depth on demand"; homepage FAQ "one dashboard instead of 150+ reports"; `blog/best-google-analytics-alternatives.mdx:10`.
+
+### Web analytics and product analytics belong in one tool
+- status: candidate
+- Why: the question "why did signups drop" crosses traffic, funnels, errors, replay and Web Vitals; switching tools loses the thread.
+- Where the site says it: homepage section "One connected workspace: Go from signal to explanation without changing tools." (`LandingPageTemplate.tsx`).
+
+### Analytics should be operable by AI agents, with the same permissions as a teammate
+- status: candidate
+- Why: a read-write MCP server on the same REST API lets an agent answer questions and manage goals without screenshots or exports; permission parity keeps it safe.
+- Where the site says it: homepage MCP section, "A hosted MCP server on top of Rybbit's full REST API..." (`LandingPageTemplate.tsx:310`); `/features/mcp`.
+
+### A small script is a feature
+- status: candidate
+- Why: the tracker loads on every page of every customer site; about 11 KB gzipped (stats.md) is part of the product's performance promise.
+- Where the site says it: many pages, but with the outdated "18 KB" figure. Approve only together with fixing that drift.
+
+## Open source and business
+
+### Open source keeps an analytics vendor honest
+- status: candidate
+- Why: under AGPL-3.0 anyone can read exactly what the script collects and self-host if the vendor changes terms; that's a stronger privacy promise than a policy page.
+- Where the site says it: homepage FAQ "Every single line of code, including for our cloud/enterprise offerings, is available on GitHub under the AGPL 3.0 license."
+
+### Self-hosting should be first-class, not a crippled edition
+- status: candidate
+- Why: self-hosted Rybbit includes session replay and the rest of the feature set; people who can run Docker shouldn't have to pay to see their own data.
+- Where the site says it: `blog/hotjar-alternatives.mdx` ("self-hosting is free with replay included"); `/docs/self-hosting`.
+- Guardrail: the Search Console panel is cloud-only (stats.md). Don't claim full parity without that caveat.
+
+### Recommend a competitor when it fits better
+- status: candidate
+- Why: readers trust a comparison that sometimes picks someone else; Rybbit has no heatmaps or surveys, and saying so sends the right people elsewhere and keeps the rest.
+- Where the site says it: `blog/hotjar-alternatives.mdx` Rybbit section; `blog/best-web-analytics-tools.mdx` "What we'd actually do".
+
+### Price by events, with no surprise overage bills
+- status: candidate
+- Why: event tiers are published on a slider and ingestion pauses at the limit instead of billing overage, so a traffic spike can't produce an unexpected invoice.
+- Where the site says it: pricing page "Set your traffic. See your price." (`PricingSection.tsx:245`). Over-limit behavior verified in stats.md.
+- Guardrail: the flip side is lost data during a spike. If a post makes this argument, it must also say that.
diff --git a/ops/seo/voice/stats.md b/ops/seo/voice/stats.md
new file mode 100644
index 000000000..5d761c65a
--- /dev/null
+++ b/ops/seo/voice/stats.md
@@ -0,0 +1,105 @@
+# Verified numbers
+
+> Used by /blog-post: every Rybbit number in a draft must appear in the verified tables here, quoted as written. A number that isn't here gets verified in code (and added) or cut.
+> Re-verify any row older than a month before quoting it; the "Known drift" and "Unverified" lists are things never to repeat until resolved.
+
+All rows checked 2026-09-28 against `origin/master` at `63e8198c` unless the source is a URL. Paths are relative to the repo root.
+
+## Tracking script
+
+| Fact | Value | Source | Checked |
+| --- | --- | --- | --- |
+| Script size, as served | 11,177 bytes gzipped (about 11 KB); 34,006 bytes uncompressed | `curl https://app.rybbit.io/api/script.js` with and without `Accept-Encoding: gzip` | 2026-09-28 |
+| On by default | Initial pageview, SPA navigations, URL parameters, outbound link clicks | `server/src/db/postgres/schema.ts:96-99` | 2026-09-28 |
+| Off by default | Web Vitals, error tracking, button clicks, copy events, form interactions, session replay, storing IP addresses | `server/src/db/postgres/schema.ts:93-95,100-103` | 2026-09-28 |
+| Visitor ID | SHA-256 of IP address + user agent (version numbers stripped), first 12 hex characters. Datacenter egress IPs are bucketed so rotating proxies don't split one visitor | `server/src/services/userId/userIdService.ts:96-116` | 2026-09-28 |
+| Daily salt | Optional per-site setting (`saltUserIds`), **off by default**. When on, visitors can't be linked across days | `server/src/db/postgres/schema.ts:80`, `server/src/lib/siteConfig.ts:111` | 2026-09-28 |
+| AI referral sources mapped | 11 AI operators (OpenAI, Anthropic, Google, Microsoft, Perplexity, Meta, Mistral, xAI, You.com, Cursor, Cohere) | `shared/src/aiOperators.ts:20-35` | 2026-09-28 |
+
+## Plans and pricing (Rybbit Cloud)
+
+| Fact | Value | Source | Checked |
+| --- | --- | --- | --- |
+| Standard | From $19/month for 100k events; $249 at 10M; $849 at 50M | `docs/src/components/PricingSection.tsx:42,48,52` | 2026-09-28 |
+| Pro | From $39/month for 100k events; $499 at 10M; $1,699 at 50M | `docs/src/components/PricingSection.tsx:56,62,66` | 2026-09-28 |
+| Event tiers on the slider | 100k, 250k, 500k, 1M, 2M, 5M, 10M, 20M, 30M, 40M, 50M, then Custom | `docs/src/components/PricingSection.tsx:15-28` | 2026-09-28 |
+| Annual billing | 8 times the monthly price (4 months free): $13/month and $26/month at 100k | `docs/src/components/PricingSection.tsx:71`, `docs/src/app/[locale]/(home)/pricing/components/ComparisonSection.tsx:267,273` | 2026-09-28 |
+| Standard limits | 5 sites, 3 team members, 3-year data retention | `docs/src/lib/const.ts:6-7`, `server/src/lib/const.ts:36-37`, `docs/src/components/PricingSection.tsx:122` | 2026-09-28 |
+| Pro limits | Unlimited sites and team members, session replay, 5-year data retention | `docs/src/components/PricingSection.tsx:129-132` | 2026-09-28 |
+| Enterprise | Custom price; pricing copy lists "Infinite data retention" | `docs/src/components/PricingSection.tsx:140,203` | 2026-09-28 |
+| Trial | 7 days; card collected at checkout, no charge until the trial ends | `server/src/api/stripe/createCheckoutSession.ts:109`, `docs/src/components/PricingSection.tsx:256` | 2026-09-28 |
+| Over the monthly limit | New events are skipped ("over_limit"), not billed as overage; the owner gets an email | `server/src/services/tracker/ingestEvent.ts:64-67`, `server/src/services/usageService.ts:358-366` | 2026-09-28 |
+| Events that count toward the limit | pageview, custom_event, performance (Web Vitals), outbound, button_click, copy, form_submit, input_change. Errors, replays and identify calls don't count | `server/src/lib/const.ts:21-30` | 2026-09-28 |
+| Self-hosting | Free, AGPL-3.0, all features including replay | `LICENSE.md`; GitHub API `license.spdx_id` = AGPL-3.0 | 2026-09-28 |
+
+## Session replay
+
+| Fact | Value | Source | Checked |
+| --- | --- | --- | --- |
+| Plan on Rybbit Cloud | Pro only (Standard doesn't list it) | `docs/src/components/PricingSection.tsx:131` | 2026-09-28 |
+| Monthly quota | 10% of the event allowance: 10,000 replays at 100k events, 1,000,000 at 10M | `server/src/lib/const.ts:358-363,466-471` | 2026-09-28 |
+| Retention | 30 days (ClickHouse TTL, so self-hosted too unless changed) | `server/src/db/clickhouse/schema/core.ts:298,348,432` | 2026-09-28 |
+| Input masking | All inputs masked by default; password and email always masked | `server/src/analytics-script/sessionReplay.ts:164-165` | 2026-09-28 |
+| Console and network capture | None. The rrweb recorder is started without plugins | `server/src/analytics-script/sessionReplay.ts:147-176` | 2026-09-28 |
+| Mobile replay | None. The React Native SDK (`@rybbit/react-native` 0.1.1) tracks screens, events, errors and users | `react-native/package.json:2-3` | 2026-09-28 |
+
+## API and MCP
+
+| Fact | Value | Source | Checked |
+| --- | --- | --- | --- |
+| API daily request limit | Standard 5,000; Pro 25,000 (5x) | `server/src/lib/const.ts:52-53` | 2026-09-28 |
+| API burst limit | 50 requests per 10 seconds on every plan | `server/src/lib/const.ts:50-51` | 2026-09-28 |
+| API keys per owner | Standard 5, Pro 20, self-hosted 50 | `server/src/lib/const.ts:62-64` | 2026-09-28 |
+| MCP tools | 44 tools, read and write, including Search Console | `server/src/mcp/tools/*.ts` (count of `registerTool(`), `server/src/mcp/tools/searchConsole.ts:46-60` | 2026-09-28 |
+| MCP clients with setup docs | Claude Code, Claude Desktop, Codex, Cursor, VS Code, opencode | `docs/src/components/LandingPageTemplate.tsx:25-32` | 2026-09-28 |
+
+## Data, hosting, integrations
+
+| Fact | Value | Source | Checked |
+| --- | --- | --- | --- |
+| Importers | Umami, Simple Analytics, Plausible. No Google Analytics, Fathom or Matomo importer | `server/src/db/postgres/schema.ts:850` | 2026-09-28 |
+| Cloud hosting | Hetzner, Germany and Finland (EU); analytics data stored in the EU | `docs/src/app/[locale]/(home)/subprocessors/page.tsx:30-34,174` | 2026-09-28 |
+| Search Console panel | Rybbit Cloud only (hidden on self-hosted) | `client/src/app/[site]/main/page.tsx:92-94` | 2026-09-28 |
+| Heatmaps | None (click or scroll). The only "heatmap" in the client is a calendar chart type in custom dashboards | `client/src/app/[site]/dashboards/utils.ts:341` | 2026-09-28 |
+| Feature flags and experiments | Code exists but the dashboard entries are commented out. Treat as unreleased; don't claim them | `client/src/app/[site]/components/Sidebar/Sidebar.tsx:164-179` | 2026-09-28 |
+
+## Open source and community
+
+| Fact | Value | Source | Checked |
+| --- | --- | --- | --- |
+| GitHub stars | 13,070 | `gh api repos/rybbit-io/rybbit` | 2026-09-28 |
+| GitHub forks | 753 | `gh api repos/rybbit-io/rybbit` | 2026-09-28 |
+| License | AGPL-3.0 | `LICENSE.md`, GitHub API | 2026-09-28 |
+
+## Historical, as published
+
+Numbers Rybbit already published in `docs/content/blog/5k-stars.mdx` (2025-05-26). Quote them as "at launch in May 2025", never as current.
+
+- About 110 days of work before launch (started January 2025).
+- 5,000 GitHub stars in 9 days; 5.8k three weeks after launch.
+- Around 700 signups and $900 total revenue in the first three weeks.
+- Around 150k impressions from about four Reddit posts (r/SideProject, r/selfhosted and smaller subs).
+- Built because the founder's gaming stats site got around 1.5 million visits a month.
+
+That post calls the hosted version "freemium". That's no longer accurate; don't repeat it.
+
+## Known drift on the site
+
+Claims live on rybbit.com that the code contradicts. Don't copy them into posts; fix the pages separately.
+
+- **"18 KB" script.** The real figure is about 11 KB gzipped (see above). Appears in `docs/src/app/[locale]/(home)/page.tsx:7` (homepage meta), the homepage FAQ JSON-LD (`docs/src/components/LandingPageTemplate.tsx:51`), web-analytics feature page, seven compare pages, `compare/data/competitors.ts`, `docs/src/lib/agent-markdown.ts` and `proxy-guide/get-started.mdx`.
+- **Daily salt described as the default.** The code default is off. Wrong on: homepage FAQ (`LandingPageTemplate.tsx:43`, "We salt user IDs daily"), `features/page.tsx:293`, `for-european-companies/page.tsx:40,77`, compare pages for Plausible (`comparison-data.tsx:123`), Simple Analytics (`:137`) and Cloudflare (`:139`), and `blog/best-google-analytics-alternatives.mdx:46`. Stated correctly on `compare/umami/comparison-data.tsx:288` and `features/retention/feature-data.tsx:136`.
+- **"Capture every interaction automatically"** (`LandingPageTemplate.tsx:219`). Button, copy and form capture are off by default.
+- **AI operator table** in `blog/track-chatgpt-traffic.mdx` lists 10 operators; the registry now has 11 (Cohere).
+
+## Unverified: ask Bill
+
+Claims used on the site that couldn't be verified from the repo. Don't use them in posts until Bill confirms and a source is added above.
+
+- "Trusted by 10,000+ organizations worldwide" (`docs/src/app/[locale]/(home)/enterprise/page.tsx:133`).
+- Naming logo-bar customers (Bosch, GOV.UK, Royal Caribbean, OP.GG and others) in articles: is there permission beyond the logo bar?
+- "Most sites are collecting data in under 5 minutes" (`LandingPageTemplate.tsx:67`).
+- GA4's script is "371KB" (`LandingPageTemplate.tsx:51`): needs a fresh measurement with a date.
+- "No sampling at any traffic level" (`blog/best-google-analytics-alternatives.mdx:46`): plausible given raw ClickHouse queries, but no code or doc states it.
+- "Fully compliant with GDPR, CCPA" (`LandingPageTemplate.tsx:43`): a legal claim. Safer wording until confirmed: "designed so analytics runs without cookies or a consent banner".
+- The dashboard's unpaid 3,000-event state (`DEFAULT_EVENT_LIMIT`, `server/src/lib/const.ts:17`) is labeled "Free plan" in the app, while marketing says there is no free tier. Until Bill decides, posts say "7-day trial" and "free to self-host", never "free plan".
diff --git a/ops/seo/voice/stories.md b/ops/seo/voice/stories.md
new file mode 100644
index 000000000..377c8f0a4
--- /dev/null
+++ b/ops/seo/voice/stories.md
@@ -0,0 +1,73 @@
+# Stories Rybbit can tell
+
+> Used by /blog-post: when a post needs a real example, take it from here instead of inventing one, and keep to the "Publishable" line for that story.
+> Customers stay anonymous unless Bill records permission here. Anything marked "do not publish without Bill's approval" is off-limits to automated drafting.
+
+All entries are candidates drafted 2026-09-28 from engineering notes. Numbers are from Rybbit's own production data or code at the time of each incident; re-check any number you quote against the current code or data, and give the date it was measured.
+
+## Lead with these
+
+### 1. The crawler that paced itself under every bot rule
+- Facts (July 2026): a distributed scraper sent about 5.2M events a day to a large self-hosted Rybbit deployment. It ran a real headless browser from residential proxy IPs, so it executed the tracking script and passed four of the five detection layers. It paced each identity at roughly one event every five minutes and rotated user agents, so no per-identity rate rule fired. Its tell was a cohort fingerprint: one uncommon screen size (1280x1200), en-US language, a Shanghai timezone, and Chrome versions drawn evenly from 16 old releases, where real users cluster on the current one. A screen-size rule shipped first; a cohort-uniformity rule followed.
+- Angle: "Why rate limits don't catch modern scrapers" or "What a bot fleet looks like in your analytics". Strong fit for bot-traffic and AI-crawler posts.
+- Publishable: the mechanism, the fingerprint shape, the event volume, the fix. Rybbit's detection layers by name.
+- Sensitivities: the deployment is a customer's self-hosted instance. Say "a large gaming site" at most; don't name it or its domains. Don't publish exact thresholds that would help a scraper tune under them.
+
+### 2. When one browser update doubled a site's user count
+- Facts (August 2026): on a desktop app built with Electron, every auto-update changed three version numbers in the user agent across the whole install base within a day or two. Because visitor IDs hash IP and user agent, every machine became a new visitor on release day: any date range spanning a release roughly doubled "users", while daily active users stayed correct. Rybbit now strips version numbers from the user agent before hashing (`normalizeUserAgentForIdentity`). Measured merge after the fix over 10 hours: 0.6% and 0.4% on two sites. A short 2-minute sample had suggested 34%, which overstated the effect about 50x.
+- Angle: "How cookieless analytics counts visitors, and where it goes wrong". Also a good honest post on measuring your own fixes.
+- Publishable: the mechanism, the fix, the before/after numbers, the lesson about short-window measurements.
+- Sensitivities: the app belongs to a customer; keep it anonymous ("a desktop app with a large install base").
+
+### 3. Real customers blocked as bots, and how we found it
+- Facts (July 2026): an audit found the rate-anomaly layer diverting roughly 100k to 480k events a day from a motorcycle maker's site. They were real buyers clicking through a bike configurator, dozens of clicks in seconds, which crossed thresholds tuned for crawlers. Pageviews survived but engagement data was cut. Two wrong theories came first; an outside traffic estimate is what broke them. Fix: interaction events got their own beyond-human threshold (100 per 10 seconds), crowd-level rules became supporting-only, and the script collapses repeat clicks on one element within a second.
+- Angle: "False positives in bot detection" or "Your bot filter might be deleting your best customers".
+- Publishable: the mechanism, the event ranges, the fix, the false leads.
+- Sensitivities: customer site, keep anonymous ("a vehicle configurator on a manufacturer's site").
+
+### 4. Launch: 5,000 GitHub stars in 9 days
+- Facts: already published in `blog/5k-stars.mdx` (May 2025). GitHub stars were 13,070 on 2026-09-28 (stats.md).
+- Angle: a follow-up, "Rybbit at 13k stars: what happened after the launch spike", in the founder's voice.
+- Publishable: everything already in the post plus current public GitHub numbers.
+- Sensitivities: revenue and signup numbers beyond what's already public need Bill's approval. The old post says "freemium"; the follow-up must not.
+
+## More candidates
+
+### 5. The one-shot bot fleet that no per-visitor rule can see
+- Facts (August 2026): across 14 days, detection caught 14.5% of traffic during spike hours against 48% at rest. One small site (normally about 4 events an hour) took 26k events in 20 hours from about 20,500 identities sending roughly one event each, from about 3,900 mostly residential networks. The fix compares each site to its own weekly baseline and convicts cohorts that are both a flood and uniform. Backtest: 22 sites flagged, all the same fleet; real product launches weren't flagged.
+- Angle: "Detecting bot floods by comparing a site to itself".
+- Publishable: aggregate numbers, the baseline approach, the backtest result.
+- Sensitivities: no site names or domains. Note honestly that the first residential-volume rule blocked two real power users and was removed the next day.
+
+### 6. Every ClickHouse timestamp pinned to UTC
+- Facts (September 2026, issue #1205, PR #1207): a self-hoster whose ClickHouse ran on Europe/Berlin time saw events stored two hours off. Every time column is now declared `DateTime('UTC')` and writers send explicit-UTC timestamps. An automatic repair of already-shifted rows was built and then removed because it can't be made correct; the docs give a manual SQL recipe instead.
+- Angle: a technical post for self-hosters and ClickHouse users: "Why your analytics timestamps drift, and why we didn't auto-fix old data".
+- Publishable: all of it; the issue and PR are public.
+- Sensitivities: low. The issue is public, but ask before naming the reporter.
+
+### 7. When a proxy split one visitor into seven
+- Facts (July 2026): after a change to client-IP resolution, traffic through rotating proxy egress (CloudFront, Fly.io, corporate proxies, iCloud Private Relay) resolved to the proxy's IP. Visitors split into several users, sessions ran 2 to 4 times high, and one customer's excluded IP showed up as 7 users. Fixes: IP exclusion matches every candidate IP, sites can declare a first-party proxy, datacenter egress IPs are bucketed for identity, and a short-lived re-attachment step joins a visitor whose proxy IP rotated.
+- Angle: "Why your analytics counts one visitor twice" for proxy and CDN setups.
+- Publishable: the mechanism and the fixes.
+- Sensitivities: this was a production regression that affected paying customers, and data from that week stays split. Needs Bill's approval before publishing. Never name the customer.
+
+### 8. The homepage redesign that lost
+- Facts (September 2026): Rybbit ran an A/B test of a new homepage design against the existing one using its own tags; the existing design won and the new one was retired (PR #1180). The scaffold for future tests stayed.
+- Angle: dogfooding post, "How we A/B test with Rybbit tags, and why we kept the old homepage".
+- Publishable: the method and the outcome.
+- Sensitivities: conversion numbers from the test aren't in these notes; get them from Bill or leave them out.
+
+### 9. A slow dashboard that turned out to be one script
+- Facts (September 2026): a large self-hosted instance (about 25M events a day) hit sustained high CPU. Sampling ClickHouse's running queries showed nearly all of it came from one internal script calling the raw overview endpoint per country over a year-to-date range, about 1,000 calls an hour, not from background aggregation.
+- Angle: "Before tuning ClickHouse, look at what's actually running", practical for self-hosters.
+- Publishable: the diagnostic method and the lesson.
+- Sensitivities: customer deployment and their staff's script. Anonymize fully; needs Bill's approval.
+
+## Do not publish without Bill's approval
+
+### Custom SQL query validator bypass (fixed August 2026)
+- Facts: Rybbit's custom query feature had validator bypasses via comment and string syntax that could allow cross-tenant reads; fixed 2026-08-27 with lexer fixes, a dedicated read-only ClickHouse user and read-only constraints.
+- Status: security incident. Do not draft, reference or hint at this in any post unless Bill explicitly approves a disclosure write-up.
+
+### Internal business metrics
+- Onboarding funnel rates, trial-to-paid conversion, MRR, subscriber counts and referral conversion rates exist in engineering notes. None of them are public. Don't use them in posts unless Bill approves each number.
diff --git a/ops/seo/voice/voice.md b/ops/seo/voice/voice.md
new file mode 100644
index 000000000..5963777bc
--- /dev/null
+++ b/ops/seo/voice/voice.md
@@ -0,0 +1,120 @@
+# How Rybbit writes
+
+> Used by /blog-post: read this before drafting, and check the finished draft against "Never write" before running `npm run lint:blog`.
+> Facts come from [stats.md](stats.md), positions from [opinions.md](opinions.md), anecdotes from [stories.md](stories.md). This file covers how to say things, not what is true.
+
+Drawn on 2026-09-28 from the homepage (`docs/src/components/LandingPageTemplate.tsx`, `docs/src/app/[locale]/(home)/page.tsx`), `PRODUCT.md`, and five blog posts. The blog earned 2 organic clicks in the 90 days to 26 Sep 2026 (GSC via Ahrefs, project 9053952), so clicks can't pick the models. These five were chosen for impressions and for passing the September fact-check:
+
+| Post | Why it's a model |
+| --- | --- |
+| `best-google-analytics-alternatives.mdx` | Most impressions on the blog (3,628). Per-tool sections, honest limits in the Rybbit section. |
+| `best-web-analytics-tools.mdx` | "What we'd actually do" verdicts that sometimes pick a competitor. |
+| `track-chatgpt-traffic.mdx` | Opens with the answer, explains the mechanism, cites every external claim inline. |
+| `posthog-pricing.mdx` | Numbers first, disclosure line, sources and dates stated up front. |
+| `hotjar-alternatives.mdx` | Rybbit section leads with what Rybbit lacks and says who should pick something else. |
+
+For build-in-public posts, `5k-stars.mdx` is the model for the founder's first-person voice.
+
+## Who reads this
+
+People who run a website or product and want to know what's happening on it without Google Analytics' weight or cookie banner (PRODUCT.md, "Users"). In order: indie developers and self-hosters, small teams and startups, agencies managing many client sites. They're technical enough to paste a script tag and often comfortable with Docker and SQL. Write for someone who will check your numbers.
+
+## Tone
+
+- **Explain, don't sell.** PRODUCT.md: "it explains, it doesn't sell." A post earns trust by being the most accurate page on the topic, then mentions Rybbit where it genuinely fits.
+- **Friendly, precise, trustworthy.** Warmth comes from clarity. No jokes that cost precision; no mascot whimsy in articles.
+- **Relief over impressive.** "This just makes sense" beats "this is impressive." Describe what a person sees and does, not how amazing it is.
+- **Plainly confident.** State facts without hedging stacks ("may potentially help"). When something is uncertain, say what's unknown once.
+
+## Voices
+
+- **Default: "we", byline "Rybbit Team".** Guides, comparisons, pricing breakdowns, explainers. "We build Rybbit" in disclosures; "we checked" for verification.
+- **Founder: "I", byline Bill.** Only for build-in-public posts (launch stories, growth numbers, lessons). Casual is fine here: `5k-stars.mdx` says "Literally nobody reads these." Never mix the two voices in one post.
+
+## Sentence habits
+
+- **Open with the answer.** The first two sentences define the thing or give the number. `posthog-pricing.mdx` opens with how billing works; `track-chatgpt-traffic.mdx` opens with the two meanings of "AI traffic". No scene-setting intro, no "In this post we'll cover".
+- **Explain the mechanism.** "It records the DOM, not pixels" and "Referral attribution rests on one HTTP header" are the house style. Readers are technical; show how it works, then what it means.
+- **Plain copulas.** "is" and "has", not "serves as", "boasts", "offers".
+- **Numbers with units and a date.** "$39/month for 100k events", "30 days", "as of September 2026". Round only when the exact figure adds nothing ("about 11 KB gzipped").
+- **Source next to the claim.** Link the vendor page or spec in the same sentence as the fact, the way `track-chatgpt-traffic.mdx` cites MDN and OpenAI inline. No "studies show".
+- **Short paragraphs.** Two to four sentences. Vary sentence length; let some sentences be short and flat.
+- **Sentence-case headings.** Question headings for explainers ("How does session replay work?"), plain nouns for sections ("Pricing at a glance").
+- **Name the product.** Say "Rybbit" every time, not "the platform", "the tool", "the solution".
+
+## Product vocabulary
+
+| Use | Avoid | Note |
+| --- | --- | --- |
+| Rybbit, Rybbit Cloud, self-hosted Rybbit | "the platform", "our solution" | Cloud and self-hosted differ (replay plan gating, Search Console UI is cloud-only). Say which. |
+| cookieless | "cookie-free tracking solution" | Pair with the concrete result: no consent banner for analytics. |
+| events | hits, "data points" | Events are the billing unit. List which count from stats.md. |
+| sites | properties, domains | "Properties" is GA vocabulary. |
+| session replay | "session recording" in prose | Use "session recording" only where the keyword needs it. |
+| Standard, Pro, Enterprise | "free plan", "free tier" | Rybbit Cloud has a 7-day trial and free self-hosting. Never write "free tier". |
+| MCP server | "AI integration" | Name the clients (Claude Code, Cursor, Codex...) and the fact it can read and write. |
+| Web Vitals, funnels, goals, user journeys, retention, user profiles, error tracking | capitalized feature names mid-sentence | Link each to `/features/*` on first mention. |
+| visitor ID | "fingerprint" | Rybbit hashes IP and user agent; the daily salt is opt-in. See stats.md before describing it. |
+
+## Trade-offs and competitors
+
+- **Disclose.** Any post that ranks or prices competitors carries a line like `posthog-pricing.mdx`'s: "Disclosure: we build Rybbit, an open-source analytics tool that appears in the comparison near the end."
+- **Say what Rybbit lacks, in the Rybbit section.** No click or scroll heatmaps, no surveys, no GA4 importer, no mobile session replay, no console or network capture in replay, replay needs Pro on Rybbit Cloud. Then say who should pick something else, as `hotjar-alternatives.mdx` does: "If heatmaps are why you open Hotjar, Clarity or Mouseflow will serve you better."
+- **Credit competitors' strengths.** "The free tier is genuinely generous" (`posthog-pricing.mdx`). A verdict section may recommend a competitor for some readers (`best-web-analytics-tools.mdx` sends $0-budget sites to Umami).
+- **Competitor facts from the vendor, dated.** Pricing, limits and features come from the vendor's own rendered page, checked the week the post ships, with "(September 2026)" next to the number. Pricing pages are often JS-rendered; render them rather than trusting a text fetch. Never from memory, a listicle, or an older Rybbit page.
+- **No punching down.** State the fact ("Umami rotates its session salt monthly by default") and let the reader judge. No "clunky", "outdated", "bloated" unless you give the measurement.
+
+## Post structure that works here
+
+- One H1. Title under ~62 characters, primary keyword near the front.
+- Comparisons: a "short version" or "at a glance" table near the top, then one section per tool.
+- Per-tool fact blocks may use bold labels (`**Covers:**`, `**Missing or limited:**`, `**Pricing (September 2026):**` with a source). This is an accepted house pattern for structured facts; don't use bold-label bullets for prose arguments.
+- End comparisons with a verdict in "we" ("What we'd actually do"), not a recap.
+- FAQ at the end with direct answers; never restate the question.
+- CTA, if any, is one plain sentence with a link ("Rybbit has a 7-day trial; self-hosting is free"). No "Ready to get started?".
+
+## Never write
+
+Pulled from `~/.claude/skills/humanize-copy/REFERENCE.md`. Density is the tell, but the first three rows are absolute.
+
+- **Em dashes.** Zero, including in tables. Use a comma, colon, parentheses, or two sentences.
+- **Invented facts.** No made-up numbers, customers, quotes or reviewer claims to sound specific. If the honest version is weaker, ship the honest version.
+- **"Free tier" or "free plan" for Rybbit Cloud.**
+- **Inflation verbs:** unlock, supercharge, elevate, empower, streamline, leverage, harness, revolutionize, transform, turbocharge, delve, foster, showcase, underscore, bolster.
+- **Vague adjectives:** seamless, effortless, robust, powerful, cutting-edge, game-changing, innovative, comprehensive, holistic, pivotal, crucial, world-class, industry-leading, best-in-class, state-of-the-art.
+- **Nouns of nothing:** solution(s), journey (except the feature "user journeys"), landscape, ecosystem, testament, synergy, "actionable insights", capabilities, offerings, game-changer.
+- **Stock phrases:** "in today's fast-paced world", "look no further", "all-in-one", "take X to the next level", "the power of X", "peace of mind", "we've got you covered", "at your fingertips", "everything you need to", "like never before", "hassle-free".
+- **Constructions:** "It's not just X, it's Y" and "isn't just about"; "Say goodbye to"; "Whether you're X or Y"; rhetorical-question openers ("Tired of...?", "Ready to...?"); benefit tails ("...so you can focus on what matters"); "From startups to enterprises" ranges.
+- **Essay furniture:** intros that preview the post, "In conclusion" or "The bottom line" recaps, a summary sentence closing each section, FAQ answers that restate the question.
+- **Puffery:** "trusted by thousands", "loved by teams", "experts agree". Use a verified number from stats.md with its source, or cut.
+- **Exclamation marks and emoji** in article prose.
+
+Run `node ~/.claude/skills/humanize-copy/scripts/scan.mjs <file>` before lint. It flags candidates; bold-label bullets in per-tool fact blocks are expected hits.
+
+## Before and after
+
+Real sentences from existing posts, rewritten to the rules above.
+
+**1. Puffery into specifics** (`ecommerce-analytics.mdx:13`)
+
+> Before: This is where Rybbit Analytics comes in. Unlike traditional analytics platforms that overwhelm you with data you don't need, Rybbit gives you actionable insights into your e-commerce metrics while respecting your customers' privacy and keeping your data under your control.
+
+> After: Rybbit puts the store owner's questions on one dashboard: which channels send visitors who reach checkout, where the checkout funnel loses them, and which product pages load slowly. It sets no cookies, so analytics needs no consent banner, and you can self-host it if the data has to stay on your own servers.
+
+What changed: "actionable insights" became three named questions, each backed by a real feature (channels, [funnels](/features/funnels), [Web Vitals](/features/web-vitals)); "respecting privacy" became the concrete consequence.
+
+**2. Negative parallelism and a benefit tail** (`content-marketing-funnel.mdx:497`)
+
+> Before: Your content marketing isn't just about traffic. It's about building a machine that turns awareness into customers. Rybbit helps you see how that machine is performing and provides the data you need to improve it at every stage.
+
+> After: Judge content by what readers do next. Set signup as a [goal](/features/goals), build a [funnel](/features/funnels) from blog post to pricing page to signup, and fix the step with the biggest drop first.
+
+What changed: the "isn't just X, it's Y" frame and the machine metaphor are gone; the paragraph now tells the reader exactly what to set up.
+
+**3. Em dash, audience hedging, vague payoff** (`geographic-segmentation.mdx:9`)
+
+> Before: Geographic segmentation divides your audience by location—country, region, city, or neighborhood. For marketers, it's one of the most practical segmentation strategies because location data reveals real behavioral differences across markets. Whether you're optimizing landing pages, adjusting ad spend, or localizing content, geographic insights drive better decisions.
+
+> After: Geographic segmentation splits your visitors by location: country, region or city. It pays off when behavior differs by market, like a landing page that converts in the US and stalls in Germany, or a page that loads slowly for visitors far from your servers. Rybbit resolves all three levels from the visitor's IP address and doesn't store the IP unless you turn that on.
+
+What changed: the em dash became a colon, "Whether you're..." became two concrete cases, "drive better decisions" was cut, and the Rybbit line states a verified default (`trackIp` is off, see stats.md).