---
assumes: []
packages:
  runtime: []
  dev: []
files: []
env:
  server: []
  client: []
ci_placeholders: {}
clean:
  files: []
  dirs: []
gitignore: []
---

# Co-located Surface

The acquisition surface lives within the product deployment — same server,
same domain, same deploy pipeline.

## web-app

The landing page IS the surface. It is generated by the landing-page subagent
(see `scaffold-landing.md`) for maximum creative quality.
`visit_landing` is defined in experiment/EVENTS.yaml.
`frontend-design` is the recommended visual executor (see `## Quality bar`
below and `.claude/patterns/design.md`).

## service

Create a root route handler (`GET /`) that returns a complete HTML marketing
page. The route path depends on the framework stack file (e.g.,
`src/app/route.ts` for Next.js, root handler in entry point for Hono).

**Content inventory from experiment.yaml** (raw material — page architecture is a
creative decision by `frontend-design`, not a fixed mapping):
- `name` — product identity
- `description` — value proposition and what the product does
- `behaviors` — capabilities to showcase
- `target_user` — who the product is for
- Payment/pricing info from `stack.payment` (if present)
- CTA — API docs link, first endpoint, or waitlist

`frontend-design` decides which sections to include, in what order, and with
what visual treatment. A conversion-optimized page may need pain points,
social proof, pricing, or comparison sections that don't directly map to a
single experiment.yaml field. The content inventory is input, not structure.

**Inline analytics snippet (if `stack.analytics` is present):** Embed a
`<script>` tag in the surface HTML's `<head>` (or just before `</body>`) that
first checks for misconfiguration, then fires `visit_landing` with UTM
properties on page load. The snippet template uses a literal placeholder
`<%POSTHOG_KEY%>` that `scaffold-landing` replaces at bootstrap time with the
analytics stack file's `POSTHOG_KEY` value (which may itself still be the
`phc_TEAM_KEY` placeholder if the fork hasn't been customized — that's fine,
the runtime check below catches it and matches the analytics stack file's
`## Production Observability` Layer 2 contract).

```html
<script>
(function() {
  var key = "<%POSTHOG_KEY%>";
  if (!key || key === "phc_TEAM_KEY") {
    var host = window.location.hostname;
    var isLocal =
      host === "localhost" || host === "127.0.0.1" || host === "0.0.0.0" || host === "[::1]" ||
      host.indexOf(".local", host.length - 6) !== -1;
    if (!isLocal) {
      console.error(
        "[analytics] PostHog is not configured for this surface — visit_landing will not be sent. " +
        "Set NEXT_PUBLIC_POSTHOG_KEY in your hosting platform OR replace 'phc_TEAM_KEY' in src/app/route.ts before launching ads."
      );
    }
    return;
  }
  // ... existing posthog snippet (init + capture('visit_landing', { utm_*, gclid, ... })) goes here
})();
</script>
```

If `stack.analytics` is absent, skip the entire script — the surface page still
works as a marketing page, just without visit tracking.

**CSS:** Inline `<style>` — no build step, no framework dependency.

**Favicon:** Include `<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,...">` in the `<head>` -- an inline SVG monogram (first letter of product name, primary color fill, white text) so the browser tab shows a branded icon.

## Quality bar

The surface is the first thing a potential user sees. It must be
**world-class** — visually equivalent to a $50K agency landing page.

`frontend-design` has full creative authority AND full creative
responsibility. The expectation is not "use nice colors." The expectation
is: custom color palette, considered typography (Google Fonts via `<link>`),
meaningful animations (CSS keyframes, scroll-triggered reveals, staggered
transitions), textured depth (subtle gradients, noise overlays, backdrop
effects), responsive layout, dark/light mode (`prefers-color-scheme`).

Not a template. Not adequate. Exceptional — a unique page that makes the
founder proud to share the URL.

See `design.md` Quality mechanics for checkable structural constraints
(typography tension, layout diversity, depth layers, interactive hero,
section differentiation).

> _Mirrors `.claude/patterns/design.md` Quality bar — keep in sync._

## Analytics wiring

When `stack.analytics` is present, the inline snippet captures `visit_landing` with:
- `referrer`
- `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`
- `click_id`
- Global properties: `project_name`, `project_owner`
