diff --git a/docs/cloud-invite-next.md b/docs/cloud-invite-next.md new file mode 100644 index 00000000..4cb57855 --- /dev/null +++ b/docs/cloud-invite-next.md @@ -0,0 +1,33 @@ +# Next scope: an invitation with a plan inside + +Status: proposed follow-up, not implemented. The founder chose to finish the landing page first on 25 October 2026. + +## What exists + +- `hosted/control/handles.go`: `/@handle` renders a profile/connection page and sends the recipient to `/me?add=handle`. Its preview is a generic puppy-pair card. There is no proposed time or guest response action on that page. +- `hosted/control/invites.go`: email invitations accept a short note. `/i/token` shows the inviter and note, then takes the recipient to sign-in. The existing token represents an invitation to join; it is not a plan, calendar permission, or confirmation. +- `hosted/control/web/index.html`: the share button shares a handle link; the sender can queue a message until a friend accepts. Agent check-in depends on the connected AI running/checking in. A hosted node alone does not guarantee an instant AI reply. + +The read-only inspection found no existing guest plan-response path in these flows. The hosted repo has no `.context/overview.md`; read its README and relevant control-plane code before implementing there. + +## Proposed first version + +One sender, one recipient, one proposed plan. The sender reviews the proposed time, time zone, place (optional), and message before sharing a new plan link. A plan invitation stays distinct from the permanent `/@handle` identity link. + +The recipient sees “Priya suggests dinner Thursday at 7:30” and two actions: **Works for me** and **Suggest another time**. This is a proposal until the recipient agrees; do not claim the recipient is free without information they actually supplied. Both actions should work without an account. Offer Pilot signup after the response has been saved, with the plan preserved if the recipient joins later. + +The reply is stored server-side and shown to the sender even if neither AI is currently running. A guest’s reply must not accept a friendship, grant access to private conversation history, create an account, or silently book a venue/calendar event. Those are separate actions with their existing consent requirements. + +## Work needed before shipping + +1. A small plan record with sender, recipient capability, proposal revision, explicit time zone, expiry, and response state. Treat the response token as access to this plan only; keep account identifiers and email addresses out of the share preview. +2. A recipient page, server-side reply endpoints, and a sender status view. Handle repeat submissions, changed proposals, declined/revoked/expired links, and attempts to reply to an old revision. “Suggest another time” returns a counterproposal for the sender to accept; it must not silently confirm both people. +3. A preview that carries the value of the plan while avoiding private details in crawler-visible metadata. Decide which details the sender knowingly makes visible to anyone holding the link; default the OG card to sender + general plan type until that decision is made. +4. Sender-triggered sharing first. Reuse email delivery only after the plan flow is sound and its sending behavior has been reviewed. No automatic reminders or invitation sends are part of this landing-page work. +5. Outcome measurement: invitation viewed → response saved → plan agreed; optional signup happens after response. Then measure invite completion into a Pilot pair, useful pair activity at day 30, and adding a third person. Log event IDs/statuses, not private plan text. + +## Review bar + +A person with no Pilot account can open the invitation, understand the proposed plan, respond, reload, and still see their saved response. The sender sees the same state without relying on an AI being online. A repeat tap cannot duplicate an event; an old proposal cannot be accepted after a change; a forwarded link cannot grant broader account access. Only after this works should the landing page claim an account-free recipient experience. + +Research basis: [Arranged Thing](../../research_notes/software-websites/viral.md), [cold-start analysis](../../research_notes/software-websites/cold-start.md), and [activation](../../research_notes/software-websites/activation.md). These support the hypothesis to test, not a guaranteed conversion lift. diff --git a/docs/cloud-landing-research.md b/docs/cloud-landing-research.md new file mode 100644 index 00000000..9d03ad5d --- /dev/null +++ b/docs/cloud-landing-research.md @@ -0,0 +1,160 @@ +# Landing pages for a hard decision — research brief + +> **25 October 2026:** The current audience, message hierarchy, claim checks, and preview copy are in [cloud-messaging.md](cloud-messaging.md). This older brief is retained as research history. Its third-party conversion figures are not forecasts for Pilot, and its implementation notes no longer describe the current warm preview. + +Prepared for the Pilot Cloud (`/cloud`) landing page. Goal: find website experiences that +convert better when the visitor has a difficult decision to make, and turn the findings into +a page that is calmer and more focused than the current one. + +Current state of `/cloud` (`website/src/pages/cloud.astro`, 280 lines, ~9 sections): + +- full site `Nav` (5 mega-menu groups, 30+ links) and the full `Footer` (4 columns + fine print); +- two hero CTAs ("Get started", "See how it works"); +- seven more CTAs down the page (install Pilot, MCP + Pilot, status, see how it works, privacy); +- three separate "fork" points: hosted vs self-host, 9 AI apps to choose from, and circles/plans; +- 6 FAQ entries, 4 use cases, 3 platform rows. + +That is a lot of exits. Every extra link is a way to leave. + +--- + +## 1. What the evidence says + +| Finding | Evidence | What it means here | +|---|---|---| +| Removing navigation from a dedicated landing page lifted conversion **+16.5%** | GrowthLayer experiment `landing-remove-navigation-from-landing-pages-tunnel` | The single highest-leverage change. "Convert or leave" is the standard for dedicated pages. | +| High-converting landing pages have **one CTA and no global nav**; they are "a stand alone web page with a single goal" | Copyhackers, CXL, Apexure (12-element framework) | `/cloud` currently has ~9 CTAs. | +| A simple one-page site out-converted a full site by **~6x** | Swipefile, "The Website Complexity Trap" | Fewer choices, one CTA, less perceived effort. | +| Two signup forms → one form converted better; users asked "which one should I use?" | Indie Hackers thread; Mert Topal, "Your SaaS Homepage Has Four Next Steps. Visitors Need One." | Two doors is already risky; nine is a maze. | +| **Defaults** are among the most effective choice-architecture tools (meta-analysis, 58 studies, n=73,675) | Jachimowicz, Duncan, Weber, Johnson — "When and why defaults influence decisions" | Pre-select the recommended path instead of presenting a neutral fork. | +| **Reframing a choice** (not adding options) lifted paid subscriptions **+19%** | Conversion Rate Experts / Mobbin win report | Copy and framing, not more features, moves the number. | +| **Paradox of choice / Hick's law**: more options → slower, worse decisions | Riley Log, choice architecture; Columbia, "Nudging App Adoption" (n=594,997) | Nine app logos + circles + platforms is decision fatigue. | +| A **multi-step quiz beat a single form by 61%** completion; quiz funnels report 2–4x | Conversion Sciences A/B test; GetFunnelAI | If there *is* a real decision, ask it one step at a time with big answer tiles. | +| Put the **first question on the first screen**; a button that jumps to a quiz is one more click | 99takes, quiz funnel guide | Don't hide the decision behind "Get started". | +| **Email gate after 5+ answered questions** lifts submission (sunk cost) | Heyflow, logic-based guided selling | Only relevant if we adopt a quiz variant. | +| Explain the recommendation, name its source, keep it adjustable | ScreensDesign, personalized onboarding | Trust comes from "here's why", not from confidence. | +| **Security/trust callouts** at the form reduce anxiety and lift sign-up | NextAfter experiment | Keep one quiet reassurance line, not a privacy block. | +| **Calm, plain-spoken, editorial** pages convert by feeling honest: no nav bar, an index of links, a signed letter, real numbers | Basecamp teardowns (PageProofer, Attention to Detail) | The "chill" register the brief asks for already has a proven model. | +| Show the product **early**, keep distractions out; signup feels like the obvious next step | Ploy, Linear landing page breakdown | One screenshot of the real thing beats three device frames. | + +### The pattern + +Sites that convert on a hard decision all do the same four things: + +1. **Remove the exits.** No global nav, no footer sitemap, no "see also". One door out, or the back button. +2. **Name the decision in the headline.** Not "here is a product", but "which of these two things are you?" The visitor should recognise their own question in the H1. +3. **Make one option the default.** A recommendation with a reason ("we suggest this because…"), not a neutral table. The unchosen path stays visible but quiet. +4. **Lower the stakes of choosing.** "You can change this later", "nothing to install", "takes a minute" — the decision feels reversible, so it gets made. + +### The register ("more chill") + +Basecamp is the reference: plain sentences, almost no decoration, one link colour, white cards +on a pale field, a short page that reads like a confident letter. Practically: + +- cut the section count roughly in half; +- one screenshot, not three device frames; +- no emoji in headings, no marquee, no gradient hero; +- generous whitespace, one accent colour, body text at a comfortable measure (~60ch); +- short sentences, second person, no superlatives. + +--- + +## 2. The four framings considered + +These were the candidate "one decisions". They are not mutually exclusive in principle, but a +page can only lead with one. All four were built as switchable previews first; A was kept as a +section rather than a fork, and the page now leads with the promise (see §3). + +### A — "Hosted or yours" + +The page's one question: **should Pilot run your agent, or do you?** +Pilot Cloud pre-selected as the default, self-hosting a single quiet line. +Matches `/plans` ("two paths, one protocol"). + +### B — "Start, or don't" + +No fork. One promise, one button. App choice happens after sign-in. + +### C — "Which AI app?" + +Centre the page on the app the visitor already uses; nine logos become one tap. + +### D — "Yours, or your team's" + +Fork between an individual and a team, mirroring the personal/enterprise split. + +### What we settled on instead + +The user asked for a **sales page that sells the whole thing**, with one message: coordinating +with people is admin, and Pilot removes it — "this is the last chore of this type you'll ever +do." So the page leads with the **promise**, not a fork, and adopts the Pain → Dream → Fix +structure (Amy Hoy / JTBD): + +1. **Hero** — the promise in one sentence, one CTA, three quiet proof points. +2. **The chore** — the pain, shown as four concrete before/after pairs rather than adjectives. +3. **Install once** — the dream: the last time you are the messenger. +4. **What happens** — the fix: three steps, once, with three real screens. +5. **Fair questions** — objections in the order they occur. +6. **Works with** — quiet compatibility row. +7. **Rather run it yourself** — the single fork, near the end, quiet. +8. **Close** — the same promise, the same button. + +Framing A survives as section 7 (hosted vs self-host), which is where it belongs: after the +promise has landed, not before it. + +--- + +## 3. What was built + +`website/src/pages/cloud-landing.astro` — a **standalone** sales page. Not a variant of `/cloud`: +it shares the design tokens and nothing else. Verified in the browser: **zero `