read-only

Add Vercel Web Analytics to the public marketing landing (a cookieless demand signal — landing surface only, not the KB or product)

0027-vercel-web-analytics-on-landing

decision read as Explain confidence verified status active 2026-06-16 owner product-owner
Reversibility
two-way door

DEC-0027 — Vercel Web Analytics on the public marketing landing

Reversibility: two-way door — deleting the single <Analytics /> component and the @vercel/analytics dependency removes it entirely; the durable commitment is only that we measure landing demand with a cookieless, no-lock-in tool (the specific provider is swappable).

Context

Ship the landing publicly behind a docs-gate flag, capture demand through two honest doors, into a list we own shipped Dossier's marketing landing publicly and built the demand-capture funnel into it: two honest doors — a broad single-field early-access email and a higher-intent design-partner door for agencies — plus the GitHub build-in-public CTA, all feeding a list we own. The landing's whole purpose is demand capture (built off Recalibrate the Dossier brand identity — demote color, promote type + restraint + craft — then build the showcase landing's recalibrated brand; opened to every organization, not just agencies, by Market to every organization; agencies are the highest-leverage channel, not a gate).

But we had no measurement on it. We could see signups arriving in the owned list, yet we were flying blind on traffic — no count of visits, no view of the funnel into those capture doors. You can't reason about a demand funnel you can't see the top of. This decision adds that basic demand signal. Built and verified this session (2026-06-16); committed in 44a1a7c on main, pushed the same day; deploys automatically via the project's existing Vercel↔GitHub integration (no Vercel CLI link).

Options considered

1. Whether to measure the landing at all — stay blind vs. add basic analytics.

  • (a) Ship no analytics, infer demand from signups alone. Rejected: signups are the bottom of the funnel; without a visit count you can't tell a low-traffic problem from a low-conversion one, and the landing exists precisely to capture demand (Ship the landing publicly behind a docs-gate flag, capture demand through two honest doors, into a list we own). A demand surface with no demand signal is half-built.
  • (b) Add a basic web-analytics signal (chosen). Visits + the conversion funnel into the two capture doors — the minimum needed to reason about the funnel.

2. Which analytics — a heavyweight/cookie-based tool vs. Vercel Web Analytics.

  • (a) A full product-analytics or cookie-based tool (e.g. a tag-managed GA-class stack). Rejected for this surface: it's more infra than a marketing landing needs, and cookie-based cross-site tracking would require a consent banner and put user data somewhere we'd then have to govern — disproportionate to "how many people visit and click the door."
  • (b) Vercel Web Analytics (chosen). It's cookieless and privacy-friendly (aggregate, no PII, no cross-site tracking, no cookie-consent banner required) and zero-config because we already host the landing on Vercel — one component, no extra infrastructure, no second vendor relationship.

3. Where it lives — site-wide vs. the marketing landing only.

  • (a) Instrument the whole site (landing + the docs/KB surface). Rejected: telemetry has no business on an institutional-memory KB. The sovereignty thesis (Adopt OKF as Dossier's canonical knowledge format) is that a client's KB is plain files in git carrying nothing but the knowledge.
  • (b) Marketing landing only (chosen). <Analytics /> is added solely to packages/site/src/pages/index.astro's <head> — the marketing/funnel surface — never the docs/KB or the product/runtime.

Decision

Add Vercel Web Analytics to the public marketing landing only, to get a cookieless basic demand signal on the capture funnel.

  • What shipped. Installed @vercel/analytics (^2.0.1) in @dossier/site; added import Analytics from '@vercel/analytics/astro'; and an <Analytics /> component to the <head> of packages/site/src/pages/index.astro — the marketing landing only, not the docs/KB surface or the product/runtime.
  • Behavior. The component injects the insights script only in the Vercel production environment; it no-ops under local astro dev/build, so local builds stay clean. Verified via a landing-only (DOCS_ENABLED=false, per Ship the landing publicly behind a docs-gate flag, capture demand through two honest doors, into a list we own's docs-gate) production build: the build succeeds and the insights script is present in the rendered index.html.
  • Operational dependency. Data collection requires a one-time "Enable Web Analytics" toggle in the Vercel dashboard; the code alone does not collect.
  • Scope held. The OKF KB and the product/runtime carry zero telemetry; only the funnel surface is instrumented.

This measures the funnel Ship the landing publicly behind a docs-gate flag, capture demand through two honest doors, into a list we own built, on the surface Recalibrate the Dossier brand identity — demote color, promote type + restraint + craft — then build the showcase landing designed and Market to every organization; agencies are the highest-leverage channel, not a gate opened to all organizations.

Rationale

  • You can't manage the funnel you can't see. Signups alone are the bottom of the funnel; a visit count + the click-through into the two doors is the minimum to tell a traffic problem from a conversion problem. The landing's purpose is demand capture, so a demand signal is part of finishing it, not scope creep.
  • Cookieless/aggregate is congruent with the thesis, where a tracking stack would not be. Vercel Web Analytics collects aggregate, cookieless metrics with no PII and no cross-site tracking — so it needs no consent banner and creates no user-data store to govern. That's the lightest tool that answers the question, and it doesn't contradict at the funnel what the product sells about data.
  • Zero-config because we already host here. The landing is already on Vercel; this is one component and no new infrastructure or vendor relationship — the lowest-overhead way to get the signal.
  • The sovereignty tension is real but bounded, and acceptable. This is a third-party script and a hosting-provider dependency, which sits against Adopt OKF as Dossier's canonical knowledge format's no-lock-in stance. It's acceptable because: (1) it lives on the marketing landing surface only — not the knowledge base or the product/runtime; the OKF KB stays plain files in git with zero telemetry, and sovereignty applies to a client's institutional memory, not to our own marketing-funnel metrics. (2) It's cookieless/aggregate — there's no user data to be locked into. (3) It's trivially reversible — deleting one component removes it — the same reversibility/no-lock-in principle the funnel already follows (the email capture deliberately chose an exportable provider behind a swappable seam — Ship the landing publicly behind a docs-gate flag, capture demand through two honest doors, into a list we own).
  • verified, not asserted. The mechanism was reproduced this session: a landing-only (DOCS_ENABLED=false) production build succeeds and the insights script is present in the rendered index.html; the component no-ops under local astro dev/build. This verifies the mechanism (the script ships in prod, stays out of local builds, lives only on the landing) — not that it has yet recorded a single live visit (that needs the dashboard toggle + real traffic), which is the open item below, not the confidence claim.

Consequences

  • The landing now has a cookieless demand signal — visits + the funnel into the early-access and design-partner doors — once the Vercel dashboard toggle is on. We can finally reason about the top of the funnel, not just the signups at the bottom.
  • Scope stays clean. Telemetry is on the marketing landing only; the docs/KB surface and the product/runtime carry none — sovereignty (Adopt OKF as Dossier's canonical knowledge format) holds where it matters (a client's memory), and no sovereign knowledge/ file is touched.
  • A new build-time dependency (@vercel/analytics ^2.0.1) and a small third-party script on the landing — accepted as build/funnel-side; not added to the client-facing plugin subset, and absent from local builds.
  • A manual operational step exists. Collection is gated on the one-time "Enable Web Analytics" dashboard toggle; until it's flipped, the script ships but no data is collected (no silent assumption that data is flowing).
  • Two-way vs. durable. Removing the single <Analytics /> component and the dependency removes it entirely (two-way door). The only durable commitment is that we measure landing demand with a cookieless, no-lock-in tool — the specific provider is swappable.

Review

Promote toward a funnel judgment only once the dashboard toggle is on and real traffic has arrived — confirm visits and the door click-through are actually recorded in production (the mechanism is verified; that it measures anything depends on the toggle + traffic). Revisit the provider if we ever want richer/self-hosted/cookieless analytics, or if Vercel Analytics' scope or pricing changes — the component is one-file reversible. If the KB surface is ever made public (Ship the landing publicly behind a docs-gate flag, capture demand through two honest doors, into a list we own's DOCS_ENABLED re-entry), explicitly re-decide whether any telemetry belongs there; the default answer is no.