# Landing Page

## Marketing Copy Guidelines

- Lead with user outcomes: less tab-switching, faster file discovery, safer backups.
- Keep copy confident and concrete; avoid unverifiable superlatives.
- Match the product truth in billing and quota behavior.
- Reuse the approved homepage headlines/CTAs before introducing new variants.
- Keep the hero product preview honest: show current supported providers and describe backups as cross-service only where that is true.
- The homepage hero uses the approved "Your cloud storage. One place." message, a compact provider-connection strip, and one real-product preview. Keep the composition focused rather than repeating provider or feature signals across multiple mock cards.
- Name Google Drive, OneDrive, and Dropbox as the current provider set. Do not use “and more” as current availability or quote an unverified setup time.
- Dot provider logos in a few high-signal areas only: hero, support proof points, and account-connection flows. Avoid turning every pricing or feature card into a logo wall.

## Homepage Visual Language

- The current direction is a horizon-led workspace: a deep navy hero, a fine
  luminous horizon, restrained cyan accents, and large Geist typography. The
  approved headline remains “Your cloud storage. One place.”
- The homepage narrative is deliberate: promise and one wide interactive
  product demo; three practical workflows; account connection; canonical plan
  choice; balanced article discovery; focused FAQs; a final sign-up link.
- Public surfaces share the navigation, mobile menu, and footer. The secondary
  routes are `/welcome`, `/about`, `/articles`, `/articles/[slug]`,
  `/legal/privacy`, `/legal/terms`, `/docs/privacy-architecture`, and
  `/docs/fair-use-policy`. Policy wording and article source content remain in
  their existing canonical sources.
- Homepage styles are scoped below `.sf-home`; shared public styles are scoped
  below `.marketing-public`. They do not restyle authenticated application
  screens. The demo owns a separate `.sf-demo` theme boundary.
- Take visual cues from the StratoFusion social banner: deep navy surfaces, a luminous horizon, restrained cyan/violet glow, and orbital lines.
- Recreate those cues with responsive CSS or lightweight SVG decoration. Do not use the complete social banner as a homepage background because its embedded lockup and tagline duplicate page content and crop poorly across viewports.
- Keep the hero as a consistently dark branded surface in both themes while allowing the remainder of the marketing page to follow the selected theme.
- Use the deterministic product presentation scenes for the primary product
  preview. Keep decorative effects behind content and out of the accessibility
  tree. Do not mount the original slideshow captures on public marketing pages:
  they contain identifying accounts and obsolete product states.
- Use a consistent product icon family for feature summaries instead of emoji.
- Keep decorative motion restrained and respect reduced-motion preferences there.
  The homepage product slideshow explicitly autoplays on load, with visible Pause controls.
- Use the `StratoFusion` brand capitalization on public marketing surfaces and their accessible labels.

## Privacy & Security Claims

- DO NOT claim zero-knowledge, end-to-end encryption, or that StratoFusion never sees file content.
- DO NOT imply that server-side orchestration is equivalent to a local-only or client-only architecture.
- DO emphasize encrypted OAuth token storage, HTTPS/TLS in transit, and secure server-side transfers.
- DO describe StratoFusion as a control plane that does not keep a long-term hosted copy of file content.
- For transfer-integrity copy, describe checksum verification as an optional setting for copy, move, backup, and sync flows; when enabled, it uses provider-supported hashes (MD5 or SHA-1) instead of implying a universal always-on guarantee.
- For move-safety copy, make it clear the source is left in place until the destination copy succeeds; do not imply delete-first behavior.
- Keep homepage FAQ framing product-first; avoid leading the section with privacy/security language.
- Keep heavier privacy, architecture, and self-deployment details off the main homepage flow unless a specific campaign needs them.

## Auth Routing

- Marketing CTAs should link directly to `/sign-up` and `/sign-in`.
- During the infrastructure migration, `/sign-up` and `/sign-in` render the
  public pause notice instead of Clerk signup/login forms while preserving the
  same canonical links.
- The pause is governed by the `AUTH_ACCESS_PAUSED` environment variable (read
  via `src/lib/auth/auth-access-pause.ts`). Unset or `true` keeps the notice
  active; set `AUTH_ACCESS_PAUSED=false` to render the normal Clerk entry
  points. Restart the deployment so the Next.js server picks up the change.
- Treat `/auth/signup` and `/auth/signin` as legacy compatibility paths only.
- `/welcome` is the Google Ads campaign route. It is public for anonymous visitors and redirects authenticated users to the app home.
- `/about` and `/articles` are public owned-content routes. Public routes render without waiting for Clerk client initialisation so crawlers receive meaningful HTML; account-setup redirects apply only to protected routes.
- `/about` displays Richard's LinkedIn portrait above the founder note, beside the bio on desktop and stacked on mobile. The original 800px image is stored at `public/images/richard-hounslow.png` and served through Next.js Image; no expiring LinkedIn CDN URL is used at runtime.
- `/welcome` plan CTAs link directly to the canonical sign-up routes: Free uses `/sign-up`, while Pro and Unlimited use `/sign-up?startTrial=pro|unlimited`.
- Campaign attribution parameters are preserved only from the approved allowlist: `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `gclid`, `gbraid`, `wbraid`, and `msclkid`.

## Campaign Landing Page

- Route: `src/app/welcome/page.tsx`.
- Render shell: `src/components/marketing/WelcomeLandingPage.tsx`.
- Data and conversion hooks: `src/lib/marketing/welcome-page.ts`.
- Billing-plan facade: `src/lib/billing/plans.ts`, backed by `src/lib/billing/plan-details.ts` and `src/lib/subscription.ts`.
- Keep Free, Pro, and Unlimited prices and CTAs in the first section so paid-search visitors see plan choice immediately.
- Use `data-campaign-surface="welcome"`, `data-experiment`, and per-plan `data-plan-tier` attributes for analytics and A/B test targeting.
- Keep social proof product-truth based: supported providers, trial window, visible job progress, and provider-approved OAuth access.

## Operations Reel

The homepage embeds one `ScreenshotShowcase` in the hero. Explorer, search,
and copy are the first three choices; a labelled select exposes all nine
scenes. Workflow links select the appropriate scene on the same public page,
so they do not depend on the local-only capture route.

| Scene ID     | Demonstrated story                                                                        |
| ------------ | ----------------------------------------------------------------------------------------- |
| `explorer`   | View three providers, narrow to an account, return and select files.                      |
| `search`     | Type a Basic filename query, show searching, results, and account filtering.              |
| `copy`       | Review source, destination and rename policy; complete two copies and preserve originals. |
| `move`       | Complete destination copies before starting source cleanup.                               |
| `download`   | Prepare three providers' files, advance individual progress, finish with 24 MB.           |
| `jobs`       | Advance a distinct backup and one-way sync with reconciled summary counts.                |
| `activity`   | Introduce start/completion events, filter Copy, reveal completion details.                |
| `storage`    | Show identical 240 GB used / 4 TB capacity in actual Bars, Donut and Table views.         |
| `properties` | Select three files and inspect the reconciled 12 + 8 + 4 MB total.                        |

Fixtures and deterministic timeline functions live in `ScreenshotShowcaseData.ts`. They use
the fictional Studio, Projects, and Archive accounts with `example.com`
addresses. Storage views, service icons, file icons, log rows, operation colors,
and UI primitives reuse product presentation components. Responsive scene
compositions isolate components whose normal containers require authentication
or live provider hooks. No demo imports transfer or account mutation services.

Playback orchestration lives in `useShowcasePlayback`. All nine demos have tabs
across the top, scrolling horizontally on smaller screens. Each scene autoplays
for ten illustrative seconds, holds its final frame for one second, then advances;
the sequence loops after the ninth demo. Arrow keys, Home, and End navigate tabs
without moving page scroll. Automatic advancement never moves keyboard focus.
Subtle circular Previous/Next arrows sit at the sides of the frame, outside the
inert product image. They wrap in both directions, remain visible on touchscreens,
and start the chosen animation just like the tabs. Play/pause and replay are labelled.
Selecting a tab by pointer or keyboard starts
that demo from the beginning and resumes the slideshow, including after a manual
pause. Workflow links behave the same way. The animated product UI is presentation
only: its body is inert to pointer and keyboard interaction, and has no interaction
callbacks. Clicking the frame does not pause playback. Only the surrounding tabs,
playback controls and theme buttons are interactive. A labelled image role exposes
the current scene and caption to assistive technology without announcing every frame.
Side arrows are part of the surrounding slideshow controls, not the product UI.
The clock, including the closing hold, pauses offscreen and in hidden tabs without
catching up. The homepage sets `motionPolicy="autoplay"`, starting its product
animation on initial load even with reduced motion enabled. Other showcase
embeddings default to the system preference and an informative final frame;
explicit Play or scene selection opts into their animated sequence. The persistent Product demo
label identifies the fictional preview without a playback/status disclaimer below
the controls. Sample timelines remain illustrative, not performance claims. Animated counters
are not live announcements. Fixed-progress previews and captures remain timer-free.

The hero provider strip keeps Google Drive, OneDrive and Dropbox in full colour.
Box, pCloud, MEGA, iCloud Drive, Proton Drive and Nextcloud appear in a separate muted
"Coming soon" group ending with an ellipsis, as requested
for the public roadmap presentation; this does not enable their integrations.
Tabs show names without numbers. The control bar uses an icon-only pause/play button
and omits Replay, "Up next" and the visible theme label to reduce clutter.
Selecting the active tab restarts its demo and continues the slideshow.

The preview follows the page theme by default. The accessibly labelled Preview theme
buttons choose Light or Dark independently without restarting the timeline
or changing the page. Both themes render the same scene definitions with the
real product CSS tokens; no flattened screenshots are recoloured or inverted.
Inactive scene modules load on demand; playback waits for the scene to mount so
slow chunk loads cannot skip its opening frames. Exports are not downloaded by the live
showcase.

### Deterministic preview and generated assets

Use the existing `/demo/operations` route on a local development server:

```text
/demo/operations?scene=move&theme=dark&progress=0.75
/demo/operations?scene=storage&theme=light&progress=0.5&capture=1
```

`progress` is clamped to 0–1; omit it for normal playback. `capture=1` renders
only the product frame. Legacy `scene=search|transfer|visibility` links continue
to work; `transfer` maps to copy and `visibility` to activity. The route retains
the repository's production denial. An exact loopback-only anonymous allowance
supports capture without a provider account; it does not make `/demo/*` public.

Keep the nine originals in `public/slide-show/` unchanged. Generated marketing
assets belong in `public/marketing-demos/`: one PNG poster and one VP8 WebM per
scene and theme, plus `manifest.json` mapping files, dimensions, frame rate,
duration, and source references. Regenerate from the same rendered scenes:

```powershell
pnpm env:guard
pnpm casa:e2e:preflight
# In a separate PowerShell terminal, start the local anonymous preview:
.\scripts\marketing\start-preview.ps1
# With that server running:
pnpm exec tsx scripts/marketing/export-demos.ts --base-url=http://localhost:3101
pnpm exec tsx scripts/marketing/verify-demo-exports.ts --base-url=http://localhost:3101
pnpm exec tsx scripts/marketing/write-demo-gallery.ts
```

The preview launcher sets the repository's anonymous test placeholders and
disables Clerk development keyless telemetry in its own process; it does not
edit environment files. The generated `/marketing-demos/index.html` gallery
loads a selected theme's posters and plays each WebM on request.
The generated asset namespace is public, including WebM and JSON files that
otherwise pass through authentication middleware. The live capture route
retains its separate local-development restriction.

The preflight distinguishes a missing production build or account prerequisite
from development-only visual inspection. The capture route intentionally needs
a development server because production builds deny nonproduction surfaces.
The exporter accepts `--scene=copy`, `--theme=dark`, `--fps=24`, and an optional
`--ffmpeg=...` path. It discovers Playwright's bundled Windows encoder when
available, blocks external and mutating requests, verifies scene changes, and
checks original-file hashes. Beginning/middle/final QA frames are written under
`output/playwright/marketing-scenes/`. Sample timing is not measured product
performance. Do not deploy these local results as part of asset generation.

### Focused verification

Run marketing components, timeline/playback tests, article tests, welcome
attribution tests, public-route tests and middleware regression tests. On
workspaces with nested temporary checkouts, constrain Vitest discovery:

```powershell
pnpm exec vitest run --exclude '**/.tmp/**' src/components/marketing src/components/articles src/lib/marketing src/lib/__tests__/public-routes.test.ts src/middleware.test.ts
```

Inspect mobile, tablet, and desktop in both themes; all scene themes at the
beginning, middle and end; pause/resume, replay, hidden-tab/offscreen behavior,
reduced motion, keyboard navigation, overflow, CTA destinations, and article
interactions. Run TypeScript and the production build after stopping any dev
server that shares `.next`. Report measured browser conditions and any blocked
authenticated prerequisites rather than implying live account verification.

The local inspection tools record route/theme/viewport screenshots, demo
interactions, and computed text contrast. Against the local preview, run
`pnpm exec tsx scripts/marketing/verify-demo-interactions.ts` for real elapsed
autoplay, closing-hold pause, tab navigation, looping and reduced-motion opt-in;
`verify-slideshow-layout.ts` checks fresh homepage autoplay and layout at
320, 390, 834 and 1440px in both themes. Pass `--reduced-motion` to verify the
homepage autoplay policy, Pause, and absence of the removed footnote under that
preference; this writes to `output/playwright/marketing-autoplay/`.
`verify-preview-contrast.ts` checks all
scene/page/preview theme combinations, including the tab and theme controls.
These scripts write evidence under `output/playwright/marketing-slideshow/`.
After a production build is running
locally, `pnpm exec tsx scripts/marketing/measure-public-pages.ts` records native
Chromium paint and layout-shift measurements for the homepage and welcome page
at desktop and mobile sizes. This is an unthrottled local lab sample with remote
and mutating requests blocked, not a Lighthouse score or real-user measurement.
`verify-built-marketing.ts --base-url=http://localhost:3102` checks the generated
gallery, canonical campaign links, and production restrictions on a separately
running local production build. It verifies that inactive videos are not
downloaded and that the source capture route still returns 404 in production.

## Updating Pricing

1. Update tier capabilities in `src/lib/subscription.ts`.
2. Update shared marketing plan labels and prices in `src/lib/billing/plans.ts`.
3. Ensure card rendering still derives capabilities from `src/lib/billing/plan-details.ts` (`PLAN_CONFIGS`, `getFeatureList`, `getLimitsList`).
4. Verify any provider-limit disclaimer changes remain aligned with `PROVIDER_API_LIMITS_DISCLAIMER`.
5. Validate rendered marketing prices against Stripe checkout configuration before deploy.

## SEO Optimization Checklist

- [ ] Page metadata includes title, description, Open Graph, and Twitter fields.
- [ ] JSON-LD structured data is present and valid for pricing offers.
- [ ] Canonical URLs use `https://stratofusion.io`; Atom, sitemap, and robots metadata resolve without authentication.
- [ ] No social `sameAs` links are emitted until profile ownership is verified.
- [ ] Repository drafts are not rendered by public routes or included in the feed.
- [ ] Single `h1` in hero; section headings follow semantic order (`h2`, `h3`).
- [ ] Internal CTA links are crawlable and descriptive.
- [ ] Hero illustration includes accessible text alternatives.
- [ ] Images below the fold use lazy loading (default behavior for `next/image`).
- [ ] Campaign routes preserve allowed attribution parameters without retaining personal data.

## Public Article Library

- The harness article leads with the software-factory workflow and lessons from
  five trials, using the September public-page redesign as its visual example.
  Images show the original homepage message and redesigned desktop view. Capture conditions,
  source revisions and asset hashes live in `public/articles/harness/evidence.json`.
  It explicitly separates the completed pilot from the later non-harness redesign.
  To reproduce, serve the exact recorded revisions locally on ports 3112 (before)
  and 3111 (after), using anonymous preview settings. Run
  `scripts/marketing/capture-article-evidence.ts` from the publication checkout
  with `--before-checkout=<path>` and `--after-checkout=<path>`. The script checks
  their revisions, crops the earlier hero copy with a checked boundary excluding
  the account screenshot, and hides the development toolbar. Captions label the
  before image as a message detail, not a matched full-page comparison.
  `scripts/marketing/verify-harness-article.ts` checks the published article on
  local port 3111 at 390/1440px in both themes, including image loading and
  user-started video playback. Its screenshots and report remain ignored.
- `MarkdownContent` renders only the exact reviewed `/marketing-demos/copy-light.webm`
  and `/marketing-demos/search-light.webm` image references as silent videos with
  controls, matching posters and `preload="none"`.
  Other images retain their existing rendering; raw HTML remains disabled.
  Include a short adjacent description; the player includes a direct-link fallback.
  Keep capture details in the evidence manifest and captions concise. Do not
  describe demo playback as measured transfer performance or the non-harness
  redesign as another pilot trial.

- `/articles` is one public library with reader-facing audience filters:
  `Cloud storage guides` for prospective users and `Engineering notes` for
  engineers, technical founders, and other builders.
- Audience is a primary editorial classification. Topic tags such as
  reliability, transfers, architecture, or deployment remain a separate
  dimension so the same topic can support different reader needs.
- Published source files live under `content/articles/published/`. Each file
  uses validated JSON frontmatter, a filename-matching safe slug, an explicit
  `published` status, one supported audience, topic labels, ISO dates, and the
  exact StratoFusion canonical URL.
- Drafts stay under `content/articles/drafts/` and are never loaded by public
  article routes, the Atom feed, static parameters, or the sitemap.
- Article detail pages derive metadata and BlogPosting structured data from the
  same validated source used by the library, feed, and sitemap. Each detail
  page also exposes a generated 1200x630 Open Graph image derived from that
  article's title, summary, audience, and author.
- The homepage discovery section selects the newest article from each audience
  before filling any remaining slots. This prevents a burst of one content
  type from hiding the other audience.
- Related reading is deterministic: shared topic labels rank first, then the
  same audience, publication date, and title. The current article is always
  excluded.
- Detail-page conversion panels are audience-specific. Cloud storage guides
  lead to `/sign-up` with the approved `utm_*` attribution fields; Engineering
  notes lead to `/about` and the public privacy architecture document.
- Article engagement uses the public `POST /api/analytics/articles` endpoint.
  The server accepts only named events and allowlisted editorial dimensions
  (audience, safe article slugs, source, and fixed CTA destination). It
  intentionally does not record account identifiers, email addresses, query
  strings, referrers, request headers, or client-generated identifiers.
- Article-to-signup attribution is held only in browser `sessionStorage`, is
  restricted to the article UTM source and supported audiences, and is deleted
  after the signed-in state records signup completion. Analytics delivery is
  best-effort and must never block reading, navigation, or authentication.
- Customer-facing pieces must lead with practical outcomes and avoid unverified
  reliability, privacy, availability, setup-time, or provider claims.
- Engineering pieces may explain implementation and trade-offs but must not
  publish secrets, private management URLs, host access instructions, customer
  data, public VM addresses, or sensitive operational evidence.

## A/B Testing Recommendations

- Test hero headline variants focused on speed vs. control outcomes.
- Compare CTA text: "Start Free" vs "Start Free Now" in high-intent sections.
- Test social proof placement (above vs below pricing).
- Run pricing-card emphasis experiments (highlight Pro vs. Unlimited).
- Track conversion funnel events: hero CTA click → signup page view → completed signup.