Context.dev Magical Onboarding free

reviewed by skillbay: we re-ran the example ourselves and the skill changed the answer. see our run

Turn one work email into a branded, useful first-run experience with Context.dev.

before and after

the same prompt, answered without the skill and then with it.

example 1 · claude-opus-5

prompt:

Redesign Context.dev's current onboarding. It has three steps: coding agent, language, and project description, followed by completion with a generated API key and setup prompt. The user's work email is already known after signup. Keep the agent, language, and project choices because they power the generated prompt. The goal is to make onboarding feel magical and demonstrate Context.dev's own value without adding another blocking step. Give a concrete build specification, states, data and API usage, interface copy, and measurement. Do not invent metrics. Keep the answer under 1,200 words.

without the skill

# Context.dev Onboarding Redesign — Build Spec

*Assumption: Context.dev's value is visibility into what coding agents actually do. The redesign makes the install itself the first observed session, so the product demonstrates itself with zero added steps.*

---

## 1. Core concept

Three questions stay. Two things change:

1. **The three steps become one scrolling composer** with a live preview pane. As the user answers, the setup prompt writes itself on the right. Perceived steps: one.
2. **Completion becomes a live receiver.** The user pastes the prompt into their agent; the screen streams the real agent session — tool calls, files touched, duration — as it happens. First value is delivered before the user ever reaches the dashboard.

Everything expensive (key minting, prompt render, description suggestions) is **prefetched or optimistic**. Nothing new blocks.

---

## 2. Screens and states

### Screen A — Composer (`/onboarding`)

Two-column, 60/40. Left: three question blocks, all mounted at once, non-answered blocks dimmed at 40% opacity and non-interactive until the prior is answered. Right: sticky `PromptPreview`.

**Header (personalized, not a step):**
> **Let's wire up acme.com**
> Three questions. Your setup prompt writes itself as you answer.

Org name and domain come from the known work email. If domain is a public mail provider (gmail, outlook, icloud, proton), fall back to: *"Let's wire up your first project."*

**Block 1 — Agent.** Six logo tiles (Claude Code, Cursor, Codex, Copilot, Cline, Other). Single click advances; no Next button.
Label: `Which agent are you running?`

**Block 2 — Language.** Chips, single select, ordered by prior. Label: `Primary language?` Helper: `Used to tailor the install steps.`

**Block 3 — Description.** Textarea, immediately focusable, plus three suggestion chips generated from domain + language + agent.
Label: `What are you building?` Placeholder: `A Rails API for warehouse inventory`
Chips render with a 700 ms budget; if the call is slower or fails, chips never appear and the textarea is untouched. Chip click fills the textarea in editable form.
Under chips: `From acme.com · edit anything`

**PromptPreview states:**

| State | Trigger | Render |
|---|---|---|
| `skeleton` | 0 answers | Ghosted prompt lines, monospace, shimmering |
| `partial` | 1–2 answers | Real lines typed in at ~30 ms/line for answered sections; rest ghosted |
| `complete` | 3 answers | Full prompt, `Copy prompt` button enabled |
| `error` | render API fails | Locally templated fallback prompt, no error shown |

CTA (bottom of left column, sticky): `Get my setup prompt →`. Enabled after Block 1; a user can skip 2 and 3 — defaults `language: unspecified`, `description: ""`. Never gate.

### Screen B — Live receiver (`/onboarding/connect`)

Left: API key + prompt. Right: `LiveSession` panel.

**Left copy:**
> **Paste this into Claude Code**
> [Copy prompt] [Copy key] [Download .env]
> Your key is shown once. It's already in the prompt above.
> Prefer manual? `npm i @context/sdk` → [3-line snippet]

**LiveSession states:**

| State | Enter condition | UI |
|---|---|---|
| `waiting` | screen mount | Pulsing dot. `Listening for your first agent session…` Below: dimmed ghost rows of what will appear (tool call, file edit, duration) |
| `key_seen` | first authenticated request on the key | `Key authenticated — acme-api.` Dot turns amber |
| `streaming` | ≥1 span received | Rows animate in top-down: tool name, target file, ms. Counter: `4 tool calls · 2 files · 11s` |
| `verified` | session.completed received | Green check. `You just watched your first session. That was Context.dev recording your agent installing Context.dev.` CTA: `Open dashboard →` |
| `idle` | 120 s in `waiting` | Add card: `Not in front of your terminal? [Email me the prompt] · [Skip to dashboard]` — both non-blocking |
| `stalled` | 90 s since last span, not completed | `Session still open — last event 90s ago.` Keep rows visible |
| `error` | auth failure on key | `That key was rejected. [Regenerate]` |

`Skip to dashboard` is present in the top-right from mount. The dashboard shows the same live panel as a dismissible banner, so nothing is lost by leaving.

---

## 3. Data and API

**Already known:** work email → `domain`, `org_id`.

| Call | When | Purpose |
|---|---|---|
| `GET /v1/me` | Screen A mount | `{ email, domain, org_name, existing_keys }` |
| `PATCH /v1/onboarding/draft` | debounced 400 ms per answer | Persists `{ agent, language, description }` so refresh/device-switch resumes |
| `POST /v1/keys` | **on Block 1 answer** (prefetch) | `{ name: "Onboarding – Claude Code", scopes: ["ingest:write"] }` → plaintext key returned once, held in memory |
| `POST /v1/setup-prompt` | debounced after each answer | `{ agent, language, description, key_id }` → `{ prompt, template_version }`. Server-rendered so prompt copy ships without a client release |
| `POST /v1/onboarding/suggestions` | Block 2 answered | `{ domain, language, agent }` → 3 descriptions. Server fetches only the public site `<meta description>`; **never sends the user's email address off-platform.** 700 ms timeout, no retry |
| `GET /v1/streams/onboarding?draft_id=` (SSE) | Screen B mount | Events: `key.first_use`, `session.started`, `span.created`, `session.completed`. Reconnect with exponential backoff, cap 30 s |

Ingest path is the existing SDK endpoint — no new receiver. `draft_id` is stamped on the key's metadata so spans route to the right stream.

Store on completion: `onboarding_completed_at`, `template_version`, `activation_source ∈ {live_verified, skipped, manual_snippet}`.

---

## 4. Failure and edge behavior

- **Key prefetch fails:** silently retry once on CTA click; if still failing, Screen B shows the prompt with a `[Generate key]` button inline.
- **User already has keys** (returning/second project): skip minting, reuse selected key, headline becomes `Let's wire up a second project.`
- **SSE blocked by corporate proxy:** fall back to 5 s polling of `GET /v1/sessions?draft_id=`.
- **Prompt copy blocked** (no clipboard permission): reveal a selectable `<pre>` with `Select all`.
- **Accessibility:** each block is a `fieldset`; focus moves to the next block's first control on answer; `LiveSession` rows announce via `aria-live="polite"`; the pulsing dot respects `prefers-reduced-motion`.

---

## 5. Measurement

Instrument with Context.dev's own event pipeline. Report as funnel conversion and medians; **set no targets until two weeks of baseline exists on the new flow.**

**Events:** `onboarding_started`, `agent_selected`, `language_selected`, `description_submitted {source: typed|chip|skipped}`, `prompt_copied`, `key_first_use`, `first_span_received`, `session_verified`, `onboarding_skipped {state}`, `dashboard_first_view`.

**Primary funnel:** `onboarding_started → prompt_copied → key_first_use → session_verified`.
**Activation definition:** `session_verified` within 24 h of `onboarding_started`.

**Supporting:**
- Time-to-first-span (median, p90) — the number the redesign is built to move.
- Drop-off by block: share reaching each `*_selected` event.
- Suggestion usefulness: `description_submitted.source` distribution; chip usage vs. typed length.
- `onboarding_skipped` by state — a spike in `waiting` means people aren't at a terminal; that's a routing problem, not a copy problem.

**Guardrails:** key-prefetch failure rate; orphaned keys (minted, never used) as a share of keys issued; suggestion API p95 latency and timeout rate; SSE fallback rate.

**Ship as an A/B against the current 3-step flow**, split at signup, primary metric = activation rate, secondary = time-to-first-span.

with the skill

## Magic contract

| Element | Value |
|---|---|
| One input | The work email already captured at signup — no new field |
| Recognition | "We found Linear" with correct logo, domain, description |
| Work removed | The project description step becomes prefilled and optional; agent and language steps arrive preselected |
| Relevance created | Agent/language defaults, the generated setup prompt, and a first brand-lookup artifact all change |
| First earned outcome | First successful authenticated API call from the new key (unchanged) |
| Correction path | "Not your company?" → domain field, in place, no restart |

Context.dev is a developer tool, so recognition must not delay the first API response. Branding is the hook; the runtime result is activation.

## Architecture

**Trigger.** Immediately after signup commits, server-side, fire-and-forget. Never on the client; `CONTEXT_DEV_API_KEY` stays server-only.

```ts
const r = await context.brand.retrieve({ type: "by_email", email: normalized });
// 422 → needs_domain, 400 → not_found, else resolved
```

Cache by normalized domain (not user id) with default Brand TTL; store `retrieved_at` and `source: "context.dev/brand"`. Deduplicate in-flight requests per domain. Onboarding step 1 renders instantly; the job result arrives over SSE or a poll on the `/onboarding/context` route, which returns only: `name`, `domain`, `logo_url`, `logo_mode`, `accent_hex`, `accent_on_color`, `description`, `industry`, `status`. Cancel/supersede if the user edits the domain; discard any response whose domain no longer matches current state.

**Second call, conditional.** Only when Brand resolves *and* the user has not already advanced past step 2, run `context.ai.products({ domain, maxProducts: 3 })` in parallel with step rendering. It costs 10 credits and higher rate weight, so it is gated: skip if the brand has no website content or if step 3 is already submitted. Its one job is to give the project description a concrete first line. No Styleguide, Screenshot, or Extract calls — this onboarding themes one card, not a design system, so they would not earn their latency.

## States

**Step 1 — Coding agent.** Neutral on first paint. If Brand resolves before interaction, a compact card appears above the choices via a 180 ms fade+rise on three semantic chunks (logo, name, fact line), respecting `prefers-reduced-motion`:

> **We found Linear** · linear.app
> Issue tracking and project management for software teams.
> Built from your public website with Context.dev
> [Use this profile] [Not your company?]

Agent tiles stay in fixed order — no reordering, which would cause layout jump — but if the resolved company's public docs, or the signup referrer, indicate an agent, that tile carries a "Suggested for Linear" caption and preselected radio. The user can still pick any agent in one click. The reveal is an accent border and logo on one card only; no full-page repaint.

**Step 2 — Language.** Preselected from the company's primary public stack when Products or the brand description makes it unambiguous, otherwise unchanged. Caption: "Preselected from your public site — change anytime."

**Step 3 — Project description.** This is where work disappears. The textarea arrives prefilled and editable:

> Linear is an issue tracking and project management tool for software teams. I'm integrating Context.dev to enrich company records from work-email domains at signup.

Label: "Drafted from your public site. Edit or replace it." Button copy changes from "Continue" to "Looks right — continue". Character count and validation unchanged; the field remains user-owned data on save, stored with `source: "context_dev_suggested"` so an edited value is never overwritten.

**Completion.** The existing screen keeps the API key and setup prompt, and gains one artifact: a live result from their own key, run server-side against their own domain at the moment the page renders.

> **Your first lookup is already done.**
> We ran `brand.retrieve({ type: "by_email", email })` on your account email using your new key.
> [Linear logo] Linear · linear.app · #5E6AD2 · SaaS / developer tools
> 1 request · 10 credits · 240 ms
> [Copy setup prompt] [Open in docs]

That is the reveal completing its own loop: the thing that recognized them is the thing they just bought. The setup prompt itself is templated with their agent, language, and description, so all three retained steps still do their job.

**Dashboard.** The destination shows the completed lookup in the request log with a "from onboarding" tag, and the project description on the workspace card. Nothing from onboarding evaporates.

## Miss and edge states

| Condition | Behavior |
|---|---|
| Gmail/personal (`422`) | No card. Inline, optional: "Add your company website to personalize your setup prompt." + Skip. Steps 1–3 run exactly as today. |
| `400 NOT_FOUND` | "We couldn't identify that company from your email." + website field + "Continue without company". Not billed. |
| Slow/cold | Steps render neutral; status line "Finding your company…" then "Preparing your setup prompt…"; if it lands after step 3, show the card at completion only. Never blocks. |
| Wrong company / subsidiary | "Not your company?" opens a domain input in place; re-resolves, replaces prefill *only if the user has not edited it*, keeps agent/language selections. |
| Late/stale response | Dropped by domain match check. |
| Refresh/back | Server-cached result rehydrates; no second billing. |
| Products call fails | Description prefill falls back to brand `description` alone. |

Logo is scored by type (wordmark for the card, icon for the avatar), mode against the light surface, aspect ratio, and resolution — never `logos[0]`, with a company-initial fallback. Accent is picked for chroma, rejected if near-white/near-black or under 4.5:1, then derived into hover/pressed/focus/border roles; error and success colors stay semantic. At 320 px the card stacks above the step and "Not your company?" stays visible.

## Measurement

Existing funnel unchanged. Add a separate enrichment funnel: `company_context_requested`, `company_context_resolved`, `company_context_missed`, `company_context_revealed`, `company_context_accepted`, `company_context_corrected` — each with `lookup_mode`, `latency_ms`, `cache_hit`, `result_status`, `correction_reason`, and never the raw email.

Report:

- signup → reveal p50/p90
- reveal acceptance vs. correction rate
- fields removed per completed onboarding (description prefill retained unedited vs. edited vs. cleared)
- step 3 completion rate and time-on-step, prefilled vs. neutral
- onboarding completion rate
- **first successful authenticated API call from the user's key** — the authoritative activation event
- Context.dev credits per activated account (10, or 20 when Products fires)

`company_context_revealed` is not activation and must not appear in any activation chart.

## Visual evidence required before ship

This spec is prose, which does not satisfy the quality gate. Before review, capture rendered UI: (1) today's three-step flow, (2) neutral post-signup state, (3) the recognition card on step 1, (4) prefilled step 3 plus the completion screen with the live lookup, (5) step 3 at 375 px with the correction control visible, and (6) the Gmail path. Label any mocked brand response as a representative fixture matching the current API shape.

what changed: Same prompt and model. Without the skill, the response invents an unrelated live-session product, assumes the wrong core value, and uses the known domain mostly for generic personalization. With the skill, Context.dev's Brand API is the causal engine: the work email resolves company context asynchronously, removes project-description work, safely selects brand assets, handles personal-email, NOT_FOUND, slow, wrong-company, and stale-response states, and closes the loop with the user's first authenticated brand lookup. The skilled response also refuses to count the recognition reveal as activation and explicitly requires real rendered UI evidence.

I can't read Context.dev's code or docs from this environment, so this spec assumes the pieces you described exist: a signed-in session with the work email, lists of supported agents and languages, a key-creation call, and a prompt template that takes the three choices. Where I propose something new I label it as new.

**The redesign in one sentence:** one screen with the three choices on the left and the setup prompt rendering live on the right, and completion becomes the moment the page detects your agent's first real request and flips to "Connected."

## Build specification

**Layout.** Two panes on desktop, stacked on mobile. Left pane is a single form: agent picker, language picker, project description. Right pane is the artifact: the setup prompt, then the API key card once issued. The right pane is visible from the first paint, so the user sees what they are building before they finish.

**Live prompt.** Move prompt generation into a pure template function shared by client and server. Every change in the left pane re-renders the prompt in the right pane with a brief highlight on the lines that changed. This turns the three inputs from gates into controls.

**Use the email.** Split the work email on the at sign. Use the domain to prefill the key name and the first line of the project description, both editable. Show the address on the completion card so the user knows where the copy of the prompt was sent. Do not call an enrichment service in the critical path. If one exists later, it may add a suggestion chip and nothing more.

**No blocking description.** Agent and language are required because the prompt is wrong without them. Description is optional. Empty description produces a prompt with a placeholder line the agent can fill in.

**Completion.** Clicking Finish does three things in parallel: creates the key, sends the prompt and key by email, and starts polling for first use of the key. The prompt is already final on screen, so the only thing that loads is the key card.

**The demonstration.** New endpoint: return whether a given key has made any request yet, and if so the timestamp and a short summary of that first request. The completion screen polls this every few seconds while the tab is open. When a request lands, the card animates to Connected and shows what the agent asked for. The user experiences Context.dev working before they leave onboarding, without being asked to do anything extra.

**Fallback demonstration.** A "Test this key" button on the key card runs the product's smallest real request in the browser with the new key and prints the raw response. Pick whichever existing call proves the key works. This is optional and never gates the exit.

**Persistence.** Save the three choices to local storage on every change and to the server on Finish. Returning users land in the correct state instead of at the start.

## States

- **Fresh.** No choices. Right pane shows the prompt skeleton with the three slots marked. Finish disabled.
- **Partial.** At least one choice. Prompt fills in as choices land. Finish enables once agent and language are set.
- **Completing.** Key request in flight. Key card shows a skeleton. Prompt is copyable already.
- **Complete, waiting.** Key shown. Copy buttons live. Status line polls for first request.
- **Connected.** First request detected. Status line shows the time and a one-line summary. Primary button becomes "Go to dashboard."
- **Returning.** Session reload restores choices. If a key already exists for this user, open directly in Complete or Connected.
- **Key error.** Creation failed. Inline error with Retry. Prompt stays visible so the user loses nothing.
- **Polling error.** Silent. Status line changes to a link to the dashboard keys page.
- **Email error.** Small notice on the card with a resend link. Never blocks.

## Data and API usage

**Read on load:** session user with email, existing keys for the user, any saved onboarding draft.

**Existing calls:** list agents, list languages, create key, send email.

**New:** first-use check for a key, keyed by key id, returning used, first_seen_at, and a short request summary. Save-draft for the three choices. If prompt generation lives only on the server today, extract it into a shared template so the client renders it without a round trip.

**Key naming:** default to the email domain plus the agent slug, for example the domain then a hyphen then the agent. Editable before Finish.

**Security:** show the full key once on this page and in the email. Store only the prefix after that, matching whatever the dashboard already does.

## Interface copy

Page title: "Set up Context.dev for your agent"

Subtitle: "Pick your agent and language. The setup prompt on the right updates as you go."

Agent label: "Which coding agent do you use?"

Language label: "Main language of the project"

Description label: "What is the project?" Helper: "Optional. One sentence helps the agent ask better questions." Placeholder uses the domain: "The codebase behind acme.com"

Right pane header, fresh: "Your setup prompt" Sub: "Choose an agent to fill this in."

Right pane header, partial: "Your setup prompt" Sub: "Copy this into your agent once your key is ready."

Finish button: "Create my key"

Key card title: "Your API key" Sub: "Also sent to nick@acme.com. This is the only time it is shown in full."

Copy buttons: "Copy key" and "Copy prompt"

Status, waiting: "Waiting for your agent's first request. Paste the prompt and run it."

Status, connected: "Connected. Your agent made its first request at 2:14 pm." Second line shows the request summary.

Test button: "Test this key"

Key error: "We could not create the key. Nothing else was lost." Button: "Try again"

Email error: "The email did not send." Link: "Resend"

Returning user banner: "Welcome back. Your setup is right where you left it."

## Measurement

Track events, not targets. Baselines come from your current funnel, and I have not seen it.

- onboarding_viewed with device and referrer
- agent_selected, language_selected, description_edited, description_prefill_kept
- prompt_copied and key_copied, each with the state they fired in
- key_created and key_create_failed
- email_sent and email_failed
- test_key_clicked and test_key_result
- first_request_detected with seconds since key_created and whether the tab was still open
- dashboard_clicked from the Connected state
- returned_to_onboarding with restored state

Derived measures to compare before and after: completion rate from view to key created, time from view to key created, share of new keys with a first request within the same session, share of new keys with a first request within one day, and prefill acceptance rate. The first-request measures are the ones that tell you whether the demonstration works, because they capture the agent actually calling Context.dev rather than the user clicking through.

**Design goal restated.** Keep the three choices (agent, language, project) because they drive the generated prompt. Add no new blocking step. Make Context.dev demonstrate itself by using the signup email's domain to recognize the company and quietly do work the user would otherwise do by hand.

## The core move

Fire one Context.dev company lookup on the signup domain the moment the onboarding route loads. Never wait on it. Every step renders immediately with generic defaults, then upgrades in place when the lookup resolves. The final screen turns the same lookup result into the demo: "this is what an agent using your key sees about your own company."

Personal-email domains (gmail, outlook, proton, etc.) skip the lookup entirely and get the generic flow. That path must be as polished as the branded one.

## Flow

**Step 1: Coding agent.** Unchanged choices. Header starts as "Set up Context.dev". When the lookup resolves with a match, the header cross-fades to the company logo plus "Set up Context.dev for {company}". No layout shift. If the user is already on step 2 when it resolves, the upgrade appears there instead.

**Step 2: Language.** Unchanged choices. If the lookup returns a detected tech stack that maps to one of the offered languages, pre-select it and show a small caption: "Picked from {company}'s public stack. Change it if we guessed wrong." The user can still click any option. No detection, no caption.

**Step 3: Project description.** Textarea unchanged. If the lookup returns a company description, pre-fill with a one-line draft: "{company} {short description}. This project uses Context.dev to ..." with the cursor placed after "to". Caption: "Drafted from what we know about {company}. Edit freely." Without a match, the textarea is empty with the current placeholder.

**Completion.** Two panes.

Left pane: API key and the generated setup prompt, as today. The prompt now includes the company name and the user's domain as the example lookup argument, so the first call the agent makes is against their own company.

Right pane, the demo: a card titled "What your agent will know" rendering the raw lookup result for their domain: logo, name, description, industry, size, location, detected stack. Under it: "One request. No forms. This is what your users' agents get too." If there was no match, the card shows a worked example for a well-known domain with the label "Example lookup", and a one-line prompt: "Want to see your company? Enter a work domain" with a single input that re-runs the lookup inline.

## States

Lookup state is a single client value with four settings.

- `pending`: generic copy, no captions, no skeletons. Nothing indicates a lookup is running.
- `matched`: logo header, language pre-select, description draft, personalized completion card.
- `no_match`: generic copy throughout, example card on completion with domain input.
- `error` or timeout: identical to `no_match`. Errors never surface to the user.

Per-field state on steps 2 and 3: `prefilled` versus `user_edited`. Once the user edits a prefilled field, later lookup upgrades never overwrite it.

Timing rule: the lookup upgrades a step only if it resolves before the user leaves that step. A late result still upgrades the completion screen. No step ever waits.

## Data and API usage

**Call.** One server-side call to the Context.dev company lookup with the email domain, made from the onboarding route handler, result streamed to the client over the existing session channel or a short poll. Server-side keeps the platform key private and lets you cache the result on the org.

**Timeout.** Client stops expecting an upgrade after a fixed window set from observed lookup latency in your own logs. Do not pick the number from this document.

**Persist on the org record:**

- lookup status, latency, and the raw response
- selected agent, language, project text
- for language and description: whether the value was prefilled, and whether the user changed it

**Field mapping.** Confirm exact response field names against the current Context.dev docs before wiring. The design needs only: name, logo, description, industry, employee range, location, tech stack. Any missing field hides its row rather than showing a blank.

**Personal-domain list.** Maintain a short server-side denylist of consumer email domains. Extend it from real signup data rather than guessing.

**Generated prompt inputs.** agent, language, project text, company name if matched, domain, API key. The prompt template stays one file with a conditional block for the company name.

## Interface copy

Step 1 header, generic: "Set up Context.dev"
Step 1 header, matched: "Set up Context.dev for {company}"

Step 2 caption, matched with stack: "Picked from {company}'s public stack. Change it if we guessed wrong."

Step 3 caption, matched: "Drafted from what we know about {company}. Edit freely."
Step 3 placeholder, generic: "What are you building, and what should agents know about it?"

Completion, left pane title: "Your key and setup prompt"
Completion, right pane title, matched: "What your agent will know"
Completion, right pane subtitle, matched: "One request. No forms. This is what your users' agents get too."
Completion, right pane title, no match: "Example lookup"
Completion, no-match input label: "Want to see your company? Enter a work domain"
Copy button: "Copy setup prompt"
After copy: "Copied. Paste it into {agent} to finish."

No exclamation marks. No "magic" in the copy. The recognition does the talking.

## Measurement

Instrument events only. Targets come from your current funnel, which this document does not know.

- `onboarding_started` with domain type: work or personal
- `company_lookup_resolved` with status, latency, and which fields were present
- `step_completed` for each step with time on step, and for steps 2 and 3 whether the value was prefilled and whether it was edited
- `completion_viewed` with card variant: matched, example, or re-lookup
- `domain_relookup_submitted` on the no-match input
- `setup_prompt_copied` and `api_key_copied`
- `first_api_call` from the backend when the new key makes its first request, with time since completion

**Questions these answer.** Does recognition reduce time on steps 2 and 3? How often is the language guess kept versus changed, which is a direct accuracy signal for Context.dev's stack detection? Does the matched completion card raise prompt copies and first API calls versus the example card? How many no-match users try the re-lookup input, which tells you whether the demo lands even without recognition?

**Guardrail.** Track lookup error rate and timeout rate. If either climbs, the generic path is carrying the load and the personalized path is invisible, which should show up as a drop in `matched` completion views before it shows up anywhere else.

## Build order

1. Server-side lookup on route load, persisted to the org, streamed to the client.
2. Completion card in both variants. This is the demo and the highest-value piece.
3. Header upgrade on step 1.
4. Language pre-select and description draft with the prefilled and edited flags.
5. Events.

Ship 1 and 2 first. Steps 3 and 4 are polish on the same data and can follow once the card is live.

about this skill

SKILL.md

---
name: context-dev-magical-onboarding
description: Design and build B2B product onboarding that uses Context.dev to recognize a company from an email or domain, remove form fields, apply its brand safely, and create a relevant first artifact. Use for SaaS signup, client portals, demos, empty states, and activation flows that should produce a “how did you know?” moment. Do not use for employee onboarding or generic product tours.
---

# Context.dev Magical Onboarding

The target experience is not “personalized” copy. It is a causal reveal:

> I gave the product one ordinary input. It recognized my company, removed work I expected to do, and prepared something useful for me.

Context.dev is the engine for that reveal. Its Brand API can resolve a work email or domain into company identity, logos, colors, description, industry context, links, and other public brand data. Its Styleguide, Product, Extract, Screenshot, and Web APIs can deepen the first-run experience when that extra context changes the product behavior.

## Start from the product, not a generic wizard

Inspect the existing signup, onboarding routes, empty states, analytics, and any current Context.dev integration. Find the product’s first earned outcome. Preserve required consent, security, billing, and compliance gates.

Write the magic contract before designing screens:

- **One input:** usually a work email, domain, company URL, or invited workspace.
- **Recognition:** the user sees that the correct company was found.
- **Work removed:** name the fields, uploads, or setup steps Context.dev eliminates.
- **Relevance created:** name the next screen, default, example, or generated artifact that changes because of the returned context.
- **First earned outcome:** the real product result after the reveal.
- **Correction path:** how a wrong or missing match is fixed without restarting.

If the enrichment only changes “Welcome, Acme” or paints a logo, it is decoration. Use the returned context to remove work and change what happens next.

## Build the reveal in three layers

### 1. Recognize

Use the earliest identifier the user already supplies. Prefer `by_email` when a work email is available; use `by_domain` when the domain is already known and validated.

Start the Context.dev request server-side after the identifier becomes stable, often on email blur or immediately after signup. Let authentication continue in parallel. Do not make a cold lookup a new blocking gate.

Read [context-dev-integration.md](references/context-dev-integration.md) before implementing the API call, caching, logo selection, or fallback behavior.

### 2. Reveal

Reveal the result as a state transition, not another questionnaire:

- keep the initial surface neutral;
- replace the generic company form with a compact “We found…” card;
- show a correctly selected logo, company name, domain, and a few high-confidence facts;
- introduce one safe brand accent and a restrained branded backdrop;
- label the source plainly: “Built from your public website with Context.dev”;
- offer **Use this profile** and **Not your company?** actions.

The reveal should take one glance. Do not dump raw API fields or make the user review a CRM record.

Never bind `brand.colors[0]` directly to buttons or body text. Derive semantic tokens, preserve contrast, and keep one primary action. Choose a logo by type, mode, aspect ratio, and resolution; do not assume `brand.logos[0]` fits the surface.

### 3. Make it useful

Turn context into product state before asking more questions:

- prefill company name, website, logo, description, industry, and social links where the product already needs them;
- choose examples and templates that match the company’s category or product;
- create the first useful artifact: an account brief, brand kit, portal, campaign draft, research interview, dashboard shell, or setup checklist;
- populate the destination so the dashboard remembers what onboarding accomplished;
- ask for confirmation or correction only where the returned fact materially affects the product.

Use additional Context.dev endpoints only when they earn their latency and credits:

- **Styleguide** for typography, spacing, shadows, and deeper theming;
- **Products** when the user’s catalog changes the generated workspace;
- **Extract** for a small schema of product-specific website facts;
- **Screenshot** when a recognizable visual preview improves trust;
- **Web scraping/crawl** when a first artifact genuinely needs site content.

Read [magic-patterns.md](references/magic-patterns.md) to select a product-specific reveal and first artifact.

## Preserve trust when the magic misses

Design these states explicitly:

- personal, free, or disposable email;
- `422` from an email lookup;
- `400 NOT_FOUND` for an unresolved brand;
- slow or cold response;
- wrong company or subsidiary;
- several usable logos with different modes;
- low-contrast or nearly white/black brand colors;
- missing description, industry, or products;
- user changes the email after a result arrives;
- stale response racing a newer request;
- refresh, back, and resume.

A miss falls back to an optional website field or the normal unbranded path. A wrong match is worse than no match: make correction immediate, preserve the user’s other work, and never imply that public enrichment is verified company-authored data.

Keep the API key server-only. Cache stable results by normalized identifier, deduplicate in-flight requests, avoid logging full emails, and track credit spend per completed reveal. Context.dev Brand data defaults to a long cache window; do not force refreshes for onboarding without a reason.

## Make the interface feel magical, not noisy

The visual transformation should communicate recognition:

- animate the logo, company name, and brand accent as separate semantic chunks only when the result arrives;
- keep the reveal interruptible and respect reduced motion;
- use an honest status line during latency: “Finding your company…” then “Preparing your workspace…”;
- keep the primary action stable so layout does not jump;
- use sentence case, verb-first buttons, real labels, visible focus, and text alongside every status color;
- at 320–375 px, stack the profile and preview without hiding correction controls.

Do not use confetti, a long typewriter effect, an autoplay carousel, or a full-page brand repaint. Recognition is the spectacle.

## Instrument the magic

Track the enrichment path separately from activation:

- `company_context_requested`
- `company_context_resolved`
- `company_context_missed`
- `company_context_revealed`
- `company_context_accepted`
- `company_context_corrected`
- the product’s authoritative first-value event

Include lookup mode, latency, cache status, result status, and correction reason; exclude the raw email. Measure email-stable → reveal p50/p90, reveal acceptance/correction, fields removed, onboarding completion, first-value conversion, and Context.dev credits per activated account.

Do not call `company_context_revealed` activation. The reveal should accelerate the product outcome, not replace it.

## Deliver real visual evidence

For design or build work, produce evidence that shows the actual experience:

1. the generic or current onboarding state;
2. the neutral email/domain capture state;
3. the Context.dev recognition reveal;
4. the useful personalized destination;
5. at least one mobile state when the flow is implemented.

Use real rendered UI with realistic data. Do not submit screenshots of prose as visual evidence. If a Context.dev result is mocked, label it as a representative fixture and keep its shape consistent with the current API.

Finish with the quality gate in [review-rubric.md](references/review-rubric.md). A design does not pass if Context.dev only adds branding, if the result can fail without recovery, or if the “after” evidence does not visibly show work removed and value created.

package contents

post id: an34qxra0tncdclr