diff --git a/web/src/lib/components/icons/Bluesky.svelte b/web/src/lib/components/icons/Bluesky.svelte
new file mode 100644
index 00000000..72be9924
--- /dev/null
+++ b/web/src/lib/components/icons/Bluesky.svelte
@@ -0,0 +1,24 @@
+<script lang="ts">
+	// lucide carries no Bluesky mark, so this is the vector the appview already
+	// ships at appview/pages/static/icons/bluesky.svg — kept identical so both
+	// front ends draw the same butterfly.
+	import type { SVGAttributes } from "svelte/elements";
+
+	let { class: className = "size-4", ...rest }: SVGAttributes<SVGSVGElement> = $props();
+</script>
+
+<svg
+	xmlns="http://www.w3.org/2000/svg"
+	role="img"
+	viewBox="-3 -3 30 30"
+	class={className}
+	{...rest}
+>
+	<title>Bluesky</title>
+	<path
+		fill="none"
+		stroke="currentColor"
+		stroke-width="2.25"
+		d="M12 10.8c-1.087-2.114-4.046-6.053-6.798-7.995C2.566.944 1.561 1.266.902 1.565.139 1.908 0 3.08 0 3.768c0 .69.378 5.65.624 6.479.815 2.736 3.713 3.66 6.383 3.364.136-.02.275-.039.415-.056-.138.022-.276.04-.415.056-3.912.58-7.387 2.005-2.83 7.078 5.013 5.19 6.87-1.113 7.823-4.308.953 3.195 2.05 9.271 7.733 4.308 4.267-4.308 1.172-6.498-2.74-7.078a8.741 8.741 0 0 1-.415-.056c.14.017.279.036.415.056 2.67.297 5.568-.628 6.383-3.364.246-.828.624-5.79.624-6.478 0-.69-.139-1.861-.902-2.206-.659-.298-1.664-.62-4.3 1.24C16.046 4.748 13.087 8.687 12 10.8Z"
+	/>
+</svg>
diff --git a/web/src/lib/components/ui/Field.svelte b/web/src/lib/components/ui/Field.svelte
index 0df26037..0eca6620 100644
--- a/web/src/lib/components/ui/Field.svelte
+++ b/web/src/lib/components/ui/Field.svelte
@@ -1,3 +1,28 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	export const field = tv({
+		slots: {
+			root: "flex flex-col gap-1.5",
+			label: "typography-paragraph-small font-medium text-foreground-default",
+			subtitle: "typography-paragraph-small text-foreground-muted"
+		},
+		variants: {
+			// settings forms label their fields in small caps; the onboarding steps use
+			// sentence case, so the casing is a variant rather than baked into the slot
+			labelCase: {
+				upper: { label: "tracking-wide uppercase" },
+				normal: { label: "" }
+			}
+		},
+		defaultVariants: {
+			labelCase: "upper"
+		}
+	});
+
+	export type FieldVariants = VariantProps<typeof field>;
+</script>
+
 <script lang="ts">
 	import type { Snippet } from "svelte";
 	import type { HTMLAttributes } from "svelte/elements";
@@ -7,6 +32,7 @@
 		subtitle?: string;
 		for?: string;
 		required?: boolean;
+		labelCase?: FieldVariants["labelCase"];
 		class?: string;
 		children: Snippet<[{ id: string }]>;
 	}
@@ -16,21 +42,20 @@
 		subtitle,
 		for: forId,
 		required = false,
-		class: className = "",
+		labelCase = "upper",
+		class: className,
 		children,
 		...rest
 	}: Props = $props();
 
 	const generatedId = $props.id();
 	const id = $derived(forId ?? generatedId);
+	const slot = $derived(field({ labelCase }));
 </script>
 
-<div class={`flex flex-col gap-1.5 ${className}`} {...rest}>
+<div class={slot.root({ class: className })} {...rest}>
 	{#if label}
-		<label
-			for={id}
-			class="typography-paragraph-small font-medium tracking-wide text-foreground-default uppercase"
-		>
+		<label for={id} class={slot.label()}>
 			{label}
 			{#if required}
 				<span class="text-foreground-danger">*</span>
@@ -39,6 +64,6 @@
 	{/if}
 	{@render children({ id })}
 	{#if subtitle}
-		<p class="typography-paragraph-small text-foreground-muted">{subtitle}</p>
+		<p class={slot.subtitle()}>{subtitle}</p>
 	{/if}
 </div>
diff --git a/web/src/lib/components/ui/Textarea.svelte b/web/src/lib/components/ui/Textarea.svelte
index f320f907..ca85aa78 100644
--- a/web/src/lib/components/ui/Textarea.svelte
+++ b/web/src/lib/components/ui/Textarea.svelte
@@ -9,14 +9,20 @@
 	export const textareaField = tv({
 		slots: {
 			root: "relative flex items-start gap-1 rounded-sm border bg-background-default transition-colors",
-			// the floor has to live on the textarea, not the root: the resize handle only ever
-			// shrinks the textarea, so a min-height on the root would let the handle drag past the
-			// box's own minimum and leave dead space under the field. keep this in sync with
-			// textareaMinHeight above — it's 2px shorter because the root's border sits outside it.
 			textarea:
-				"min-h-63.5 flex-1 self-stretch bg-transparent py-2 typography-paragraph-small leading-6 outline-none placeholder:text-foreground-placeholder read-only:resize-none disabled:cursor-not-allowed disabled:resize-none"
+				"flex-1 self-stretch bg-transparent py-2 outline-none placeholder:text-foreground-placeholder read-only:resize-none disabled:cursor-not-allowed disabled:resize-none"
 		},
 		variants: {
+			// the floor has to live on the textarea, not the root: the resize handle only ever
+			// shrinks the textarea, so a min-height on the root would let the handle drag past the
+			// box's own minimum and leave dead space under the field. `default` keeps
+			// textareaMinHeight above in sync — it's 2px shorter because the root's border sits
+			// outside it. `compact` is for short fields (an ssh key, a one-line note) where the
+			// editor-sized floor would swallow the form.
+			size: {
+				default: { textarea: "min-h-63.5" },
+				compact: { textarea: "min-h-20" }
+			},
 			error: {
 				false: {
 					root: "border-border-default focus-within:border-border-strong focus-within:ring-1 focus-within:ring-border-strong"
@@ -46,7 +52,8 @@
 		defaultVariants: {
 			error: false,
 			disabled: false,
-			readonly: false
+			readonly: false,
+			size: "default"
 		}
 	});
 
@@ -65,6 +72,7 @@
 		loading?: boolean;
 		readonly?: boolean;
 		resizeable?: boolean;
+		size?: TextareaFieldVariants["size"];
 		iconLeft?: Component<SvelteHTMLElements["svg"]>;
 		iconRight?: Component<SvelteHTMLElements["svg"]>;
 		class?: string;
@@ -78,6 +86,7 @@
 		loading = false,
 		readonly = false,
 		resizeable = false,
+		size = "default",
 		iconLeft,
 		iconRight,
 		class: className,
@@ -85,7 +94,9 @@
 		...rest
 	}: Props = $props();
 
-	const { root, textarea } = $derived(textareaField({ error, disabled, readonly, resizeable }));
+	const { root, textarea } = $derived(
+		textareaField({ error, disabled, readonly, resizeable, size })
+	);
 
 	// The root no longer carries the text inset (so the scrollbar/resize handle can sit flush
 	// against the border) — the textarea itself owns its horizontal padding, collapsing to 0 on
diff --git a/web/src/lib/components/welcome/FinishStep.svelte b/web/src/lib/components/welcome/FinishStep.svelte
new file mode 100644
index 00000000..904a900c
--- /dev/null
+++ b/web/src/lib/components/welcome/FinishStep.svelte
@@ -0,0 +1,167 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	// the finish bento: a two-column grid where one tile runs the full width and
+	// another spans both rows (appview onboarding/fragments/finish.html)
+	export const tile = tv({
+		slots: {
+			root: "flex flex-col gap-2 rounded-sm border border-border-default p-4",
+			heading: "flex items-center gap-2 typography-paragraph-regular text-foreground-default",
+			body: "flex-1 typography-paragraph-small text-foreground-muted",
+			action:
+				"ml-auto flex w-fit items-center gap-1 typography-paragraph-small text-foreground-default no-underline hover:underline"
+		},
+		variants: {
+			span: {
+				full: { root: "sm:col-span-2" },
+				tall: { root: "sm:row-span-2" },
+				single: { root: "" }
+			},
+			// the community row's tiles are themselves the link, so they need the hover
+			// surface and the tighter gap the four bento tiles don't want
+			link: {
+				true: {
+					root: "flex-1 gap-1 no-underline transition-colors hover:bg-background-subtle hover:no-underline"
+				},
+				false: { root: "" }
+			}
+		},
+		defaultVariants: {
+			span: "single",
+			link: false
+		}
+	});
+
+	export type TileVariants = VariantProps<typeof tile>;
+</script>
+
+<script lang="ts">
+	import type { Component } from "svelte";
+	import type { SvelteHTMLElements } from "svelte/elements";
+	import { resolve } from "$app/paths";
+	import ArrowRight from "$icon/arrow-right";
+	import BookMarked from "$icon/book-marked";
+	import GitPullRequest from "$icon/git-pull-request";
+	import Layers2 from "$icon/layers-2";
+	import MessageCircle from "$icon/message-circle";
+	import Server from "$icon/server";
+	import Twitter from "$icon/twitter";
+	import Bluesky from "$lib/components/icons/Bluesky.svelte";
+	import StepHeader from "./StepHeader.svelte";
+
+	const slot = tile();
+
+	// the appview links /core, a shortcut route it owns; the svelte app addresses
+	// repositories as /[handle]/[repo]
+	const coreHref = resolve("/tangled.org/core" as "/");
+	const newRepoHref = resolve("/repo/new");
+
+	const docs: {
+		icon: Component<SvelteHTMLElements["svg"]>;
+		title: string;
+		body: string;
+		href: string;
+	}[] = [
+		{
+			icon: Server,
+			title: "Host your own knot",
+			body: "Host repositories on your own infrastructure with knots.",
+			href: "https://docs.tangled.org/knot-self-hosting-guide.html"
+		},
+		{
+			icon: Layers2,
+			title: "Host your own spindle",
+			body: "Run CI jobs on your own infrastructure using spindles.",
+			href: "https://docs.tangled.org/spindles.html#self-hosting-guide"
+		}
+	];
+
+	const community: {
+		icon: Component<SvelteHTMLElements["svg"]>;
+		title: string;
+		body: string;
+		href: string;
+	}[] = [
+		{
+			icon: Bluesky,
+			title: "Bluesky",
+			body: "Follow us @tangled.org on Bluesky for updates.",
+			href: "https://bsky.app/profile/tangled.org"
+		},
+		{
+			icon: MessageCircle,
+			title: "Discord",
+			body: "Join the community on Discord.",
+			href: "https://chat.tangled.org"
+		},
+		{
+			icon: Twitter,
+			title: "X (Twitter)",
+			body: "Follow us @tangled_org on X for updates.",
+			href: "https://x.com/tangled_org"
+		}
+	];
+</script>
+
+<div class="flex flex-col gap-6">
+	<StepHeader title="You're all set!" subtitle="Here are a few things to explore next:" />
+
+	<div class="grid grid-cols-1 gap-3 sm:grid-cols-2">
+		<div class={tile({ span: "full" }).root()}>
+			{@render heading(BookMarked, "Create a repository")}
+			<p class={slot.body()}>Kick things off by creating your first repository.</p>
+			<a href={newRepoHref} class={slot.action()}>
+				Create
+				<ArrowRight class="size-4 shrink-0" aria-hidden="true" />
+			</a>
+		</div>
+
+		<div class={tile({ span: "tall" }).root()}>
+			{@render heading(GitPullRequest, "Contribute to the Tangled project")}
+			<p class={slot.body()}>
+				Tangled is fully open-source: Open a feature request, or submit a bug-fix!
+				<br /><br />
+				All contributions are welcome.
+			</p>
+			<a href={coreHref} class={slot.action()}>
+				Contribute
+				<ArrowRight class="size-4 shrink-0" aria-hidden="true" />
+			</a>
+		</div>
+
+		{#each docs as doc (doc.title)}
+			<div class={slot.root()}>
+				{@render heading(doc.icon, doc.title)}
+				<p class={slot.body()}>{doc.body}</p>
+				<a href={doc.href} target="_blank" rel="external noopener noreferrer" class={slot.action()}>
+					Read the docs
+					<ArrowRight class="size-4 shrink-0" aria-hidden="true" />
+				</a>
+			</div>
+		{/each}
+	</div>
+
+	<ul class="grid grid-cols-1 gap-3 sm:grid-cols-3">
+		{#each community as link (link.title)}
+			<li class="flex">
+				<a
+					href={link.href}
+					target="_blank"
+					rel="external noopener noreferrer"
+					class={tile({ link: true }).root()}
+				>
+					{@render heading(link.icon, link.title)}
+					<span class={slot.body()}>{link.body}</span>
+				</a>
+			</li>
+		{/each}
+	</ul>
+</div>
+
+{#snippet heading(icon: Component<SvelteHTMLElements["svg"]>, title: string)}
+	{@const Icon = icon}
+	<span class={slot.heading()}>
+		<Icon class="size-4 shrink-0" aria-hidden="true" />
+		{title}
+	</span>
+{/snippet}
diff --git a/web/src/lib/components/welcome/KeysStep.svelte b/web/src/lib/components/welcome/KeysStep.svelte
new file mode 100644
index 00000000..eff4fa66
--- /dev/null
+++ b/web/src/lib/components/welcome/KeysStep.svelte
@@ -0,0 +1,68 @@
+<script lang="ts">
+	import Plus from "$icon/plus";
+	import Button from "$lib/components/ui/Button.svelte";
+	import Field from "$lib/components/ui/Field.svelte";
+	import Input from "$lib/components/ui/Input.svelte";
+	import Textarea from "$lib/components/ui/Textarea.svelte";
+	import KeyCard from "$lib/components/settings/KeyCard.svelte";
+	import StepHeader from "./StepHeader.svelte";
+	import { addKey, draft, removeKey } from "./draft.svelte";
+
+	let name = $state("");
+	let key = $state("");
+
+	const canAdd = $derived(name.trim() !== "" && key.trim() !== "");
+
+	const add = (event: SubmitEvent) => {
+		event.preventDefault();
+		if (!canAdd) return;
+		addKey(name.trim(), key.trim());
+		name = "";
+		key = "";
+	};
+</script>
+
+<div class="flex flex-col gap-6">
+	<StepHeader
+		title="Add an SSH key"
+		subtitle="Add a public SSH key to push to your repositories over SSH."
+	/>
+
+	{#if draft.keys.length > 0}
+		<ul class="flex flex-col gap-3">
+			{#each draft.keys as pubkey (pubkey.id)}
+				<li>
+					<KeyCard
+						name={pubkey.name}
+						fingerprint={pubkey.fingerprint}
+						createdAt={pubkey.createdAt}
+						onDelete={() => removeKey(pubkey.id)}
+					/>
+				</li>
+			{/each}
+		</ul>
+	{/if}
+
+	<form class="flex flex-col gap-4" onsubmit={add}>
+		<Field label="Key name" labelCase="normal">
+			{#snippet children({ id })}
+				<Input {id} placeholder="my-laptop" required bind:value={name} />
+			{/snippet}
+		</Field>
+
+		<Field label="Public key" labelCase="normal">
+			{#snippet children({ id })}
+				<Textarea
+					{id}
+					size="compact"
+					rows={3}
+					required
+					placeholder="ssh-ed25519 AAAA..."
+					bind:value={key}
+				/>
+			{/snippet}
+		</Field>
+
+		<Button type="submit" icon={Plus} disabled={!canAdd} class="ml-auto">Add key</Button>
+	</form>
+</div>
diff --git a/web/src/lib/components/welcome/ProfileStep.svelte b/web/src/lib/components/welcome/ProfileStep.svelte
new file mode 100644
index 00000000..a8e0a224
--- /dev/null
+++ b/web/src/lib/components/welcome/ProfileStep.svelte
@@ -0,0 +1,73 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	export const avatarPicker = tv({
+		slots: {
+			label:
+				"flex size-40 cursor-pointer flex-col items-center justify-center gap-1 overflow-hidden rounded-full border border-border-default text-foreground-subtle transition-colors hover:bg-background-subtle",
+			image: "size-full rounded-full object-cover",
+			placeholder: "flex flex-col items-center justify-center gap-1"
+		}
+	});
+
+	export type AvatarPickerVariants = VariantProps<typeof avatarPicker>;
+</script>
+
+<script lang="ts">
+	import Camera from "$icon/camera";
+	import Field from "$lib/components/ui/Field.svelte";
+	import Input from "$lib/components/ui/Input.svelte";
+	import StepHeader from "./StepHeader.svelte";
+	import { draft } from "./draft.svelte";
+
+	const slot = avatarPicker();
+
+	// no upload endpoint wired up: the preview is a local object url, which is all
+	// the appview shows before its hx-post to /profile/avatar comes back
+	const pick = (event: Event) => {
+		const file = (event.currentTarget as HTMLInputElement).files?.[0];
+		if (!file) return;
+		if (draft.picture) URL.revokeObjectURL(draft.picture);
+		draft.picture = URL.createObjectURL(file);
+	};
+</script>
+
+<div class="flex flex-col gap-6">
+	<StepHeader title="Welcome!" subtitle="Let's get your profile ready. All fields are optional." />
+
+	<div class="flex flex-col gap-6 md:flex-row">
+		<div class="flex shrink-0 justify-center md:block">
+			<label class={slot.label()}>
+				{#if draft.picture}
+					<img src={draft.picture} alt="Your new avatar" class={slot.image()} />
+				{:else}
+					<span class={slot.placeholder()}>
+						<Camera class="size-6" aria-hidden="true" />
+						<span class="typography-paragraph-small">Upload picture</span>
+					</span>
+				{/if}
+				<input type="file" accept="image/png,image/jpeg" class="hidden" onchange={pick} />
+			</label>
+		</div>
+
+		<div class="flex min-w-0 flex-1 flex-col gap-4">
+			<Field label="Bio" labelCase="normal">
+				{#snippet children({ id })}
+					<Input {id} placeholder="Tell us about yourself" bind:value={draft.description} />
+				{/snippet}
+			</Field>
+
+			<Field label="Pronouns" labelCase="normal">
+				{#snippet children({ id })}
+					<Input {id} placeholder="they/them" bind:value={draft.pronouns} />
+				{/snippet}
+			</Field>
+
+			<Field label="Website" labelCase="normal">
+				{#snippet children({ id })}
+					<Input {id} placeholder="example.com" bind:value={draft.website} />
+				{/snippet}
+			</Field>
+		</div>
+	</div>
+</div>
diff --git a/web/src/lib/components/welcome/SocialStep.svelte b/web/src/lib/components/welcome/SocialStep.svelte
new file mode 100644
index 00000000..0ee0360a
--- /dev/null
+++ b/web/src/lib/components/welcome/SocialStep.svelte
@@ -0,0 +1,32 @@
+<script lang="ts">
+	import EmptyState from "$lib/components/ui/EmptyState.svelte";
+	import FollowCard from "$lib/components/profile/FollowCard.svelte";
+	import RepoCard from "$lib/components/repo/RepoCard.svelte";
+	import { repoKey } from "$lib/components/profile/types";
+	import StepHeader from "./StepHeader.svelte";
+	import { people, trendingRepos } from "./mock";
+</script>
+
+<div class="flex flex-col gap-6">
+	<StepHeader title="Discover" subtitle="Find users to follow and repositories to star." />
+
+	{#if people.length > 0 || trendingRepos.length > 0}
+		{#if people.length > 0}
+			<div class="flex flex-col gap-3">
+				{#each people as person (person.did)}
+					<FollowCard {person} border />
+				{/each}
+			</div>
+		{/if}
+
+		{#if trendingRepos.length > 0}
+			<div class="flex flex-col gap-3">
+				{#each trendingRepos as repo (repoKey(repo))}
+					<RepoCard {repo} border />
+				{/each}
+			</div>
+		{/if}
+	{:else}
+		<EmptyState message="Nothing to suggest right now — you can explore once you're set up." />
+	{/if}
+</div>
diff --git a/web/src/lib/components/welcome/StepHeader.svelte b/web/src/lib/components/welcome/StepHeader.svelte
new file mode 100644
index 00000000..3a5dff2f
--- /dev/null
+++ b/web/src/lib/components/welcome/StepHeader.svelte
@@ -0,0 +1,32 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	// every step opens with the same title/subtitle pair (appview onboarding/* fragments)
+	export const stepHeader = tv({
+		slots: {
+			root: "flex flex-col gap-2",
+			title: "typography-heading-3 font-semibold text-foreground-default",
+			subtitle: "typography-paragraph-regular text-foreground-muted"
+		}
+	});
+
+	export type StepHeaderVariants = VariantProps<typeof stepHeader>;
+</script>
+
+<script lang="ts">
+	interface Props {
+		title: string;
+		subtitle?: string;
+	}
+
+	let { title, subtitle }: Props = $props();
+
+	const slot = stepHeader();
+</script>
+
+<header class={slot.root()}>
+	<h1 class={slot.title()}>{title}</h1>
+	{#if subtitle}
+		<p class={slot.subtitle()}>{subtitle}</p>
+	{/if}
+</header>
diff --git a/web/src/lib/components/welcome/Steps.svelte b/web/src/lib/components/welcome/Steps.svelte
new file mode 100644
index 00000000..c0833305
--- /dev/null
+++ b/web/src/lib/components/welcome/Steps.svelte
@@ -0,0 +1,79 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	// the numbered rail from Figma node 191:6514 — same shape as the appview's
+	// onboarding/fragments/steps, restyled onto the design-system tokens. the three
+	// states differ only in the marker fill and the label colour, so they are one
+	// variant across two slots rather than three hand-written class strings.
+	export const steps = tv({
+		slots: {
+			root: "flex w-full items-center gap-2",
+			item: "flex shrink-0 items-center gap-2",
+			marker:
+				"flex size-5 shrink-0 items-center justify-center rounded-full typography-paragraph-small",
+			// labels are desktop-only, but sr-only rather than hidden so the rail still
+			// reads as a named list of steps on a narrow screen
+			label: "sr-only typography-paragraph-small whitespace-nowrap sm:not-sr-only",
+			connector: "h-px min-w-4 flex-1 bg-border-default"
+		},
+		variants: {
+			state: {
+				done: {
+					marker: "bg-background-inset text-foreground-default",
+					label: "text-foreground-subtle"
+				},
+				current: {
+					marker: "bg-background-muted text-foreground-default",
+					label: "text-foreground-default"
+				},
+				upcoming: {
+					marker: "bg-background-inset text-foreground-subtle",
+					label: "text-foreground-subtle"
+				}
+			}
+		},
+		defaultVariants: {
+			state: "upcoming"
+		}
+	});
+
+	export type StepsVariants = VariantProps<typeof steps>;
+	export type StepState = NonNullable<StepsVariants["state"]>;
+</script>
+
+<script lang="ts">
+	import Check from "$icon/check";
+
+	interface Props {
+		items: readonly { key: string; label: string }[];
+		current: number;
+	}
+
+	let { items, current }: Props = $props();
+
+	// root and connector take no variant, so they resolve once
+	const shell = steps();
+
+	const stateOf = (index: number): StepState =>
+		index < current ? "done" : index === current ? "current" : "upcoming";
+</script>
+
+<ol class={shell.root()}>
+	{#each items as item, index (item.key)}
+		{#if index > 0}
+			<li aria-hidden="true" class={shell.connector()}></li>
+		{/if}
+		{@const state = stateOf(index)}
+		{@const slot = steps({ state })}
+		<li class={slot.item()} aria-current={state === "current" ? "step" : undefined}>
+			<span class={slot.marker()} aria-label={state === "done" ? "done" : undefined}>
+				{#if state === "done"}
+					<Check class="size-3.5" aria-hidden="true" />
+				{:else}
+					{index + 1}
+				{/if}
+			</span>
+			<span class={slot.label()}>{item.label}</span>
+		</li>
+	{/each}
+</ol>
diff --git a/web/src/lib/components/welcome/WelcomeCard.svelte b/web/src/lib/components/welcome/WelcomeCard.svelte
new file mode 100644
index 00000000..97136fff
--- /dev/null
+++ b/web/src/lib/components/welcome/WelcomeCard.svelte
@@ -0,0 +1,96 @@
+<script module lang="ts">
+	import { tv, type VariantProps } from "tailwind-variants";
+
+	export const welcomeCard = tv({
+		slots: {
+			root: "overflow-hidden rounded-sm border border-border-default bg-background-default shadow-xs",
+			header: "overflow-x-auto border-b border-border-default px-6 py-5",
+			// grid so the outgoing and incoming panes share one cell and cross-fade in
+			// place; overflow-hidden is what keeps the swipe inside the card
+			body: "grid overflow-hidden p-6",
+			pane: "col-start-1 row-start-1 min-w-0",
+			footer: "flex items-center justify-between gap-4 border-t border-border-default px-6 py-4"
+		}
+	});
+
+	export type WelcomeCardVariants = VariantProps<typeof welcomeCard>;
+</script>
+
+<script lang="ts">
+	import type { Snippet } from "svelte";
+	import { untrack } from "svelte";
+	import { cubicIn, cubicOut } from "svelte/easing";
+	import { prefersReducedMotion } from "svelte/motion";
+	import { fly } from "svelte/transition";
+	import ArrowLeft from "$icon/arrow-left";
+	import ArrowRight from "$icon/arrow-right";
+	import Check from "$icon/check";
+	import Button from "$lib/components/ui/Button.svelte";
+	import Steps from "./Steps.svelte";
+	import { WELCOME_STEPS, LAST_STEP } from "./steps";
+
+	interface Props {
+		step: number;
+		/** +1 when advancing, -1 when going back — decides which way the pane slides */
+		direction: number;
+		/** the appview greens Next once the step has something worth saving */
+		nextReady?: boolean;
+		onBack: () => void;
+		onNext: () => void;
+		/** rendered per step index, frozen at pane creation so the outgoing pane keeps its own content */
+		children: Snippet<[number]>;
+	}
+
+	let { step, direction, nextReady = false, onBack, onNext, children }: Props = $props();
+
+	const slot = welcomeCard();
+
+	const DISTANCE = 40;
+	const enter = $derived(
+		prefersReducedMotion.current
+			? { duration: 0 }
+			: { x: direction * DISTANCE, duration: 240, delay: 90, easing: cubicOut }
+	);
+	const leave = $derived(
+		prefersReducedMotion.current
+			? { duration: 0 }
+			: { x: direction * -DISTANCE, duration: 150, easing: cubicIn }
+	);
+
+	const isLast = $derived(step === LAST_STEP);
+</script>
+
+<div class={slot.root()}>
+	<div class={slot.header()}>
+		<Steps items={WELCOME_STEPS} current={step} />
+	</div>
+
+	<div class={slot.body()}>
+		{#key step}
+			<!-- untrack freezes the index at creation: `children` is a live snippet, so
+			     without this the leaving pane would re-render with the new step's content
+			     halfway through its own exit transition -->
+			{@const frozen = untrack(() => step)}
+			<div class={slot.pane()} in:fly={enter} out:fly={leave}>
+				{@render children(frozen)}
+			</div>
+		{/key}
+	</div>
+
+	<div class={slot.footer()}>
+		{#if step > 0}
+			<Button variant="ghost" icon={ArrowLeft} onclick={onBack}>Back</Button>
+		{:else}
+			<span></span>
+		{/if}
+
+		<Button
+			variant={nextReady ? "primary" : "default"}
+			icon={isLast ? Check : ArrowRight}
+			iconSide={isLast ? "left" : "right"}
+			onclick={onNext}
+		>
+			{isLast ? "Finish" : "Next"}
+		</Button>
+	</div>
+</div>
diff --git a/web/src/lib/components/welcome/draft.svelte.ts b/web/src/lib/components/welcome/draft.svelte.ts
new file mode 100644
index 00000000..2cbf848e
--- /dev/null
+++ b/web/src/lib/components/welcome/draft.svelte.ts
@@ -0,0 +1,33 @@
+// what the user has entered so far. the step panes are destroyed and recreated on
+// every transition, so this cannot live inside them — the appview has the same
+// split for a different reason, keeping progress in the `onboarding` table and the
+// profile/keys on the record, so wiring this up later means replacing the module
+// rather than moving state around the components.
+
+import { initialKeys, newKey, type MockKey } from "./mock";
+
+export const draft = $state({
+	description: "",
+	pronouns: "",
+	website: "",
+	/** a local object url until there is an upload endpoint to post to */
+	picture: undefined as string | undefined,
+	keys: [...initialKeys] as MockKey[]
+});
+
+/** the appview greens Next once any profile field has something in it */
+export const profileFilled = () =>
+	[draft.description, draft.pronouns, draft.website].some((value) => value.trim() !== "");
+
+// the counter lives here rather than in KeysStep: the pane is recreated on every
+// transition, so a component-local counter would restart and collide with the ids
+// already in the list
+let nextKeyId = 1;
+
+export const addKey = (name: string, key: string) => {
+	draft.keys = [...draft.keys, newKey(nextKeyId++, name, key)];
+};
+
+export const removeKey = (id: number) => {
+	draft.keys = draft.keys.filter((key) => key.id !== id);
+};
diff --git a/web/src/lib/components/welcome/mock.ts b/web/src/lib/components/welcome/mock.ts
new file mode 100644
index 00000000..4aff06c7
--- /dev/null
+++ b/web/src/lib/components/welcome/mock.ts
@@ -0,0 +1,95 @@
+// stand-in data for the welcome flow. the appview fills these from
+// OnboardingSocial / OnboardingKeys; nothing here is wired to an api yet, so the
+// step components read from this module and a real load later replaces it.
+
+import type { PersonData, RepoCardData } from "$lib/components/profile/types";
+
+export interface MockKey {
+	id: number;
+	name: string;
+	fingerprint: string;
+	createdAt: string;
+}
+
+const did = (name: string) => `did:plc:${name.replace(/[^a-z0-9]/g, "")}welcome`;
+
+/** OnboardingSocial's People — suggested accounts to follow */
+export const people: PersonData[] = [
+	{
+		did: did("alphaone"),
+		handle: "alpha.one",
+		description: "Innovative coder at tangled.org, passionate about sustainable tech.",
+		followers: 1100,
+		following: 99
+	},
+	{
+		did: did("betaspace"),
+		handle: "beta.space",
+		description: "Rust and Go enthusiast, creating pixel art and exploring plant-based living.",
+		followers: 987,
+		following: 78
+	},
+	{
+		did: did("gammanetwork"),
+		handle: "gamma.network",
+		description: "Co-founder of EcoTech Labs, blending software with environmental solutions.",
+		followers: 1700,
+		following: 25
+	}
+];
+
+/** OnboardingSocial's TrendingRepos */
+export const trendingRepos: RepoCardData[] = [
+	{
+		rkey: "welcome-1",
+		name: "core",
+		repoDid: did("tangledorg"),
+		ownerHandle: "tangled.org",
+		description: "A decentralized network for secure and scalable data storage.",
+		createdAt: "2026-05-02T10:00:00Z",
+		language: "Go",
+		stars: 2200,
+		issues: 31,
+		pulls: 1
+	},
+	{
+		rkey: "welcome-2",
+		name: "batman.vim",
+		repoDid: did("072004xyz"),
+		ownerHandle: "072004.xyz",
+		description: "A Vim colourscheme that only works at night.",
+		createdAt: "2026-04-18T10:00:00Z",
+		language: "Vim Script",
+		stars: 412,
+		issues: 3,
+		pulls: 2
+	},
+	{
+		rkey: "welcome-3",
+		name: "knotserver",
+		repoDid: did("coopppage"),
+		ownerHandle: "coop.page",
+		description: "Self-hostable git remote that speaks the Tangled protocol.",
+		createdAt: "2026-03-09T10:00:00Z",
+		language: "Rust",
+		stars: 856,
+		issues: 12,
+		pulls: 4
+	}
+];
+
+/** OnboardingKeys' PubKeys — starts empty, the step adds to it */
+export const initialKeys: MockKey[] = [];
+
+/**
+ * Builds the row the appview would get back from `PUT /settings/keys`. It lives
+ * here rather than in draft.svelte.ts because svelte/prefer-svelte-reactivity
+ * rejects a plain `Date` inside a rune module, and this one is a throwaway — the
+ * timestamp is read once, never held.
+ */
+export const newKey = (id: number, name: string, key: string): MockKey => ({
+	id,
+	name,
+	fingerprint: `SHA256:${key.slice(-32)}`,
+	createdAt: new Date().toISOString()
+});
diff --git a/web/src/lib/components/welcome/steps.ts b/web/src/lib/components/welcome/steps.ts
new file mode 100644
index 00000000..82d5ddc5
--- /dev/null
+++ b/web/src/lib/components/welcome/steps.ts
@@ -0,0 +1,16 @@
+// the onboarding steps, mirroring appview/models/onboarding.go. the appview
+// persists the index in the `onboarding` table, so these values are storage
+// keys, not just display order — keep them aligned with the Go constants.
+export const WELCOME_STEPS = [
+	{ key: "profile", label: "Set up your profile" },
+	{ key: "social", label: "Follow & star" },
+	{ key: "keys", label: "Add SSH keys" },
+	{ key: "finish", label: "Finish" }
+] as const;
+
+export type WelcomeStepKey = (typeof WELCOME_STEPS)[number]["key"];
+
+export const WELCOME_TOTAL = WELCOME_STEPS.length;
+
+/** the last step is the summary — there is nothing left to skip past it */
+export const LAST_STEP = WELCOME_TOTAL - 1;
diff --git a/web/src/routes/+layout.svelte b/web/src/routes/+layout.svelte
index 0d9bea87..7bb082e2 100644
--- a/web/src/routes/+layout.svelte
+++ b/web/src/routes/+layout.svelte
@@ -20,6 +20,8 @@
 
 	const signedIn = $derived(Boolean(auth.currentUser));
 	const isAuthShell = $derived(page.url.pathname === "/login");
+	// the welcome flow runs its own steps chrome, so the bar and footer step aside
+	const isWelcomeShell = $derived(page.url.pathname === "/welcome");
 	const isMarketingShell = $derived(
 		!signedIn && (page.url.pathname === "/about" || page.url.pathname === "/")
 	);
@@ -37,7 +39,7 @@
 			? "flex min-h-screen flex-col bg-linear-to-b from-background-default to-background-canvas text-foreground-default"
 			: "flex min-h-screen flex-col bg-background-canvas text-foreground-default"}
 >
-	{#if !isAuthShell}
+	{#if !isAuthShell && !isWelcomeShell}
 		<header
 			class={isMarketingShell
 				? "z-20 w-full bg-transparent pt-[env(safe-area-inset-top)]"
@@ -56,7 +58,7 @@
 		{@render children()}
 	</main>
 
-	{#if !isAuthShell}
+	{#if !isAuthShell && !isWelcomeShell}
 		<Footer variant={isMarketingShell ? "full" : "minimal"} />
 	{/if}
 </div>
diff --git a/web/src/routes/welcome/+page.svelte b/web/src/routes/welcome/+page.svelte
new file mode 100644
index 00000000..12b561f0
--- /dev/null
+++ b/web/src/routes/welcome/+page.svelte
@@ -0,0 +1,69 @@
+<script lang="ts">
+	import { goto } from "$app/navigation";
+	import { resolve } from "$app/paths";
+	import X from "$icon/x";
+	import Button from "$lib/components/ui/Button.svelte";
+	import Logo from "$lib/components/ui/Logo.svelte";
+	import FinishStep from "$lib/components/welcome/FinishStep.svelte";
+	import KeysStep from "$lib/components/welcome/KeysStep.svelte";
+	import ProfileStep from "$lib/components/welcome/ProfileStep.svelte";
+	import SocialStep from "$lib/components/welcome/SocialStep.svelte";
+	import WelcomeCard from "$lib/components/welcome/WelcomeCard.svelte";
+	import { profileFilled } from "$lib/components/welcome/draft.svelte";
+	import { LAST_STEP, WELCOME_TOTAL } from "$lib/components/welcome/steps";
+
+	// the appview keeps the index in the onboarding table and gives each step its
+	// own GET route; with nothing wired up yet this is local state, so wiring it
+	// later means splitting this into /welcome/[step] and reading the record.
+	let step = $state(0);
+	let direction = $state(1);
+
+	const go = (to: number) => {
+		if (to < 0 || to >= WELCOME_TOTAL) return;
+		direction = to > step ? 1 : -1;
+		step = to;
+	};
+
+	// the appview greens Next on every step past the profile, where it is earned
+	const nextReady = $derived(step === 0 ? profileFilled() : true);
+
+	const leave = () => goto(resolve("/"));
+</script>
+
+<svelte:head>
+	<title>Welcome &middot; Tangled</title>
+</svelte:head>
+
+<div class="flex min-h-screen w-full items-start justify-center px-4 pt-16 pb-8">
+	<main class="w-full max-w-3xl">
+		<h1 class="mb-4 flex place-content-center">
+			<Logo wordmark class="h-10" />
+		</h1>
+
+		<WelcomeCard
+			{step}
+			{direction}
+			{nextReady}
+			onBack={() => go(step - 1)}
+			onNext={() => (step === LAST_STEP ? leave() : go(step + 1))}
+		>
+			{#snippet children(current)}
+				{#if current === 0}
+					<ProfileStep />
+				{:else if current === 1}
+					<SocialStep />
+				{:else if current === 2}
+					<KeysStep />
+				{:else}
+					<FinishStep />
+				{/if}
+			{/snippet}
+		</WelcomeCard>
+
+		{#if step < LAST_STEP}
+			<div class="mt-4 flex justify-center">
+				<Button variant="ghost" icon={X} onclick={leave}>Skip onboarding</Button>
+			</div>
+		{/if}
+	</main>
+</div>