diff --git a/docs/design/storybook-investigation.md b/docs/design/storybook-investigation.md
new file mode 100644
index 00000000..2b3b0d00
--- /dev/null
+++ b/docs/design/storybook-investigation.md
@@ -0,0 +1,99 @@
+# Storybook導入 調査記録
+
+## 目的
+
+`packages/extension` へ Storybook を導入し、`OnboardingPage.tsx` の各ステップ
+（`OnboardingStep` × `StepPhase` の組み合わせ）を個別に確認できるようにする
+試みを行った。作業時間の制約により完了に至らなかったため、原因と得られた
+知見を記録する。
+
+## 採用した方針（概要）
+
+- `OnboardingPage` は自身の状態を `useOnboardingState` フックで管理しており、
+  Props を受け取らない。そのため、各ステップ用の Story を個別に自作する
+  のではなく、`useOnboardingState.ts` に既に存在する e2e 用の URL 上書き
+  機構（`?step=SEARCH&phase=value_shown`、`e2e/onboarding-shots.spec.ts` が
+  スクリーンショット撮影に使用しているもの）を Storybook からも流用する
+  方針を取った。
+- `chrome.*` API は Storybook のプレビュー用に独自モック（`chrome.storage`
+  のメモリ実装、`chrome.i18n.getMessage` の実メッセージ引き当て等）を用意
+  し、`Storage.setCommands(getDefaultCommands(locale))` を Story 読み込み時
+  に実行して、本番の初回インストール時と同じ状態を再現する設計とした。
+
+## 遭遇した問題と原因
+
+### 1. Storybook の Vite ビルダーが、拡張機能用の `vite.config.ts` を自動で読み込んでしまう
+
+- `@storybook/react-vite` は既定で `.storybook` の親ディレクトリにある
+  `vite.config.ts` を自動検出し、Storybook 用の設定にマージする仕様になっ
+  ている（`@storybook/builder-vite` 内部の `getBuilderOptions()` /
+  `loadConfigFromFile()`）。
+- 本プロジェクトの `vite.config.ts` は Chrome 拡張機能のビルド専用で、
+  `@crxjs/vite-plugin`（manifest.json の解釈やコンテンツスクリプトの特別
+  なバンドリング）や、Shadow DOM 環境向けにカスタムした
+  `vite-plugin-css-injected-by-js` の `injectCodeFunction`
+  （`document.getElementById("selection-command")?.shadowRoot ?? document.head`
+  への注入）を含んでいる。
+- これが Storybook のプレビュー（通常の DOM ページ）に対しても適用されて
+  しまい、
+  - `@crxjs/vite-plugin` の HMR ハンドラがエラーを送出してオーバーレイ
+    表示になる
+  - CSS が期待通り `<style>` タグとして注入されない（Tailwind の生成物
+    自体は正しいのに、実際のDOMには反映されない）
+    という2つの不具合を引き起こしていた。
+- **対策**: `.storybook/main.ts` の `core.builder.options.viteConfigPath`
+  に、拡張機能とは無関係の空の `vite.config.ts` を指定し、本来の
+  `vite.config.ts` が読み込まれないようにすることで、HMR エラーと
+  Shadow DOM 向け CSS 注入コードの混入は解消した。
+
+### 2. `chrome` グローバルのモック順序・カバレッジ不足によるハング
+
+- `commandStorage.ts` など一部のモジュールは、**import された時点**（トッ
+  プレベル）で `chrome.storage.onChanged.addListener(...)` を呼び出す。
+  そのため、Storybook のプレビュー側で `chrome` のモックを設定するコード
+  は、アプリ本体のどのモジュールよりも先に評価される必要があった
+  （ESM の import 文はファイル内の他の文より先に評価されるため、モック
+  用モジュールは import 文の先頭に置く、かつ本体コードを import しない
+  独立したファイルにする、という工夫が必要だった）。
+- `services/storage/index.ts` の `debouncedSyncSet()` は、
+  `chrome.storage.sync.set(items, callback)` という**コールバック形式**
+  で呼び出している。Storybook 用のモックを Promise ベースのみで実装して
+  いたためコールバックが一切呼ばれず、`Storage.setCommands()` の
+  Promise が永久に解決しない（＝ Story の初期化処理がハングする）という、
+  原因の特定が難しい不具合が発生した。
+  - 症状としては「Storybook のプレビューがローディングスピナーのまま
+    止まる」だけで、コンソールにもエラーが出ないため、`chrome.storage`
+    まわりの実装差異に気づくまでに時間を要した。
+- **対策**: モックの `set`/`remove`/`clear` を、Promise を返しつつ
+  コールバック引数が渡された場合はそれも呼び出す形に修正し、解消した。
+
+### 3. 自動化ブラウザに実機の拡張機能がインストールされていたことによるノイズ
+
+- 動作確認に使用したブラウザ（claude-in-chrome）に、この拡張機能自体の
+  開発ビルドと思われる拡張機能が既にインストールされており、あらゆる
+  ページ（Storybook のプレビュー含む）に content script や Vite の
+  HMR クライアントを注入していた。
+- これにより、コンソールログやネットワークログに無関係な
+  `chrome-extension://...` 由来のログが大量に混入し、問題の切り分け
+  （どこまでが自分たちの Storybook 由来で、どこからが無関係な拡張機能
+  由来か）が難しくなった。
+
+## 未解決だった点
+
+- 上記 1, 2 を解消した直後の時点で、Tailwind のユーティリティクラス自体
+  は正しく生成されるようになっていたが、実際にブラウザへ注入された
+  `<style>` タグには反映されておらず、`@/components/App.css` の Vite
+  モジュールを直接 `import()` しても `<style data-vite-dev-id="...">`
+  が生成されない事象が残っていた。原因（Vite のモジュールキャッシュ、
+  もしくは項番3のノイズの影響）を切り分けている途中で作業を打ち切った。
+
+## 次回への申し送り
+
+- `.storybook/main.ts` で `viteConfigPath` を明示的に空の設定に差し替え
+  る対策は有効だったので、再挑戦する場合はこの対策を先に適用した状態
+  から始めるとよい。
+- `chrome.storage.*` のモックは、コールバック形式・Promise形式の両方を
+  サポートする実装にしておく（`src/test/setup.ts` の Vitest 用モックも
+  同様の考慮がされているため、参考にできる）。
+- 動作確認は、他の拡張機能がインストールされていないクリーンなブラウザ
+  プロファイルで行うことを推奨する。
diff --git a/packages/extension/e2e/onboarding-shots.spec.ts b/packages/extension/e2e/onboarding-shots.spec.ts
new file mode 100644
index 00000000..3311533a
--- /dev/null
+++ b/packages/extension/e2e/onboarding-shots.spec.ts
@@ -0,0 +1,108 @@
+import { test, chromium } from "@playwright/test"
+import fs from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+import { OnboardingStep, StepPhase } from "@/types/onboarding"
+
+// Not part of the regular e2e suite - a design-review tool. Skipped unless
+// explicitly requested (`CAPTURE=1 yarn test:e2e onboarding-shots`) so it
+// never slows down or flakes the normal CI run.
+//
+// Uses `?step=..&phase=..` (see useOnboardingState.ts's readE2eOverride(),
+// e2e-build only) to land directly on each screen instead of driving the
+// real selection/command flow, and launches its own persistent context per
+// locale (rather than the shared `fixtures.ts` one) so this file alone
+// controls `--lang`.
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const pathToExtension = path.join(__dirname, "../dist")
+
+type Shot = {
+  name: string
+  step: keyof typeof OnboardingStep
+  phase?: StepPhase
+}
+
+// One shot per visually distinct screen - not one per StepPhase transition;
+// e.g. Step2's WAIT_EXECUTE looks like Step1's, so only Step1 gets it.
+const SHOTS: Shot[] = [
+  { name: "00-intro", step: "INTRO" },
+  { name: "01-search-explain", step: "SEARCH", phase: StepPhase.EXPLAIN },
+  {
+    name: "02-search-wait-execute",
+    step: "SEARCH",
+    phase: StepPhase.WAIT_EXECUTE,
+  },
+  {
+    name: "03-search-wait-return",
+    step: "SEARCH",
+    phase: StepPhase.WAIT_RETURN,
+  },
+  { name: "04-search-value", step: "SEARCH", phase: StepPhase.VALUE_SHOWN },
+  { name: "05-ai-explain", step: "AI_PROMPT", phase: StepPhase.EXPLAIN },
+  { name: "06-ai-value", step: "AI_PROMPT", phase: StepPhase.VALUE_SHOWN },
+  {
+    name: "07-preview-explain",
+    step: "LINK_PREVIEW",
+    phase: StepPhase.EXPLAIN,
+  },
+  {
+    name: "08-preview-value",
+    step: "LINK_PREVIEW",
+    phase: StepPhase.VALUE_SHOWN,
+  },
+  { name: "09-customize", step: "CUSTOMIZE" },
+  { name: "10-complete", step: "COMPLETE" },
+]
+
+const LOCALES = ["ja", "en-US", "de"]
+
+test.describe("onboarding screenshots (design review)", () => {
+  test.skip(
+    !process.env.CAPTURE,
+    "set CAPTURE=1 to run onboarding screenshot capture",
+  )
+
+  for (const locale of LOCALES) {
+    test(`capture (${locale})`, async () => {
+      test.setTimeout(120_000)
+
+      const context = await chromium.launchPersistentContext("", {
+        headless: false,
+        args: [
+          `--lang=${locale}`,
+          `--disable-extensions-except=${pathToExtension}`,
+          `--load-extension=${pathToExtension}`,
+        ],
+      })
+
+      try {
+        let [sw] = context.serviceWorkers()
+        if (!sw) sw = await context.waitForEvent("serviceworker")
+        const extensionId = sw.url().split("/")[2]
+
+        const page = await context.newPage()
+        const outDir = path.join(
+          __dirname,
+          "../test-results/onboarding",
+          locale,
+        )
+        fs.mkdirSync(outDir, { recursive: true })
+
+        for (const shot of SHOTS) {
+          const params = new URLSearchParams({ step: shot.step })
+          if (shot.phase) params.set("phase", shot.phase)
+          await page.goto(
+            `chrome-extension://${extensionId}/src/onboarding_page.html?${params}`,
+          )
+          // Let entrance animations and the selection-demo cursor settle
+          // into a representative frame before capturing.
+          await page.waitForTimeout(700)
+          await page.screenshot({ path: path.join(outDir, `${shot.name}.png`) })
+        }
+      } finally {
+        await context.close()
+      }
+    })
+  }
+})
diff --git a/packages/extension/package.json b/packages/extension/package.json
index 08c5b87c..57a20659 100644
--- a/packages/extension/package.json
+++ b/packages/extension/package.json
@@ -41,6 +41,7 @@
     "@supabase/supabase-js": "^2.105.4",
     "@testing-library/user-event": "^14.6.0",
     "bowser": "^2.14.1",
+    "canvas-confetti": "^1.9.4",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.1",
     "colorthief": "^2.6.0",
@@ -65,6 +66,7 @@
     "@crxjs/vite-plugin": "^2.0.0-beta.30",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.3.0",
+    "@types/canvas-confetti": "^1.9.0",
     "@types/chrome": "^0.1.36",
     "@types/jest": "^29.5.11",
     "@types/platform": "^1.3.6",
diff --git a/packages/extension/public/SelectionCommandLogo.png b/packages/extension/public/SelectionCommandLogo.png
new file mode 100644
index 00000000..b140bb1b
Binary files /dev/null and b/packages/extension/public/SelectionCommandLogo.png differ
diff --git a/packages/extension/public/_locales/de/messages.json b/packages/extension/public/_locales/de/messages.json
index 91a1d709..10e20548 100644
--- a/packages/extension/public/_locales/de/messages.json
+++ b/packages/extension/public/_locales/de/messages.json
@@ -1301,5 +1301,122 @@
   },
   "hub_login": {
     "message": "Beim Hub anmelden"
+  },
+  "onboarding_step0Title": {
+    "message": "Danke fürs Installieren!"
+  },
+  "onboarding_step0Body": {
+    "message": "Lass uns das Ganze in etwa einer Minute direkt ausprobieren."
+  },
+  "onboarding_startButton": {
+    "message": "Los geht's"
+  },
+  "onboarding_skipButton": {
+    "message": "Überspringen"
+  },
+  "onboarding_step1Explain": {
+    "message": "Markiere den folgenden Text, um sofort eine Suche auszuprobieren."
+  },
+  "onboarding_step1TargetText": {
+    "message": "Eine Erweiterung, mit der du markierten Text mit einem Klick durchsuchen kannst."
+  },
+  "onboarding_selectHint": {
+    "message": "Text unten durch Ziehen markieren"
+  },
+  "onboarding_railSelect": {
+    "message": "Auswählen"
+  },
+  "onboarding_railCommand": {
+    "message": "Befehl"
+  },
+  "onboarding_railResultSearch": {
+    "message": "Suchen"
+  },
+  "onboarding_step1Callout": {
+    "message": "Klicke auf diesen Befehl, um mit Google zu suchen."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "Wechsle zurück zu diesem Tab, dann schließt sich das Fenster automatisch."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "Klicke irgendwo auf den Bildschirm"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "Fertig – jetzt kannst du alles, was du markierst, sofort durchsuchen"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "Füge deine bevorzugte Suchmaschine hinzu, um alltägliche Suchen noch schneller zu machen."
+  },
+  "onboarding_step2Explain": {
+    "message": "Als Nächstes fragen wir die KI zum folgenden Text."
+  },
+  "onboarding_step2TargetText": {
+    "message": "Dies ist eine Chrome-Erweiterung, mit der du Text aus dem Web in einen Prompt einfügen und ausführen kannst - überlege dir ein paar Ideen, wofür du sie nutzen könntest."
+  },
+  "onboarding_step2Callout": {
+    "message": "Führe diesen Befehl aus, um deine Auswahl + einen Prompt an die KI zu senden."
+  },
+  "onboarding_railResultAi": {
+    "message": "KI"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "Sende deine Auswahl + einen Prompt an die KI …"
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "Jetzt kannst du die KI direkt auf der Seite, die du liest, zu allem fragen, was du markierst"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "Frag die KI sofort Dinge wie „Fasse das zusammen\" oder „Analysiere dieses Unternehmen\".\nDen Prompt kannst du frei anpassen."
+  },
+  "onboarding_step3Explain": {
+    "message": "Schauen wir uns einen Link an, ohne einen neuen Tab zu öffnen."
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "Beispiel-Link"
+  },
+  "onboarding_railResultPreview": {
+    "message": "Vorschau"
+  },
+  "onboarding_step3Callout": {
+    "message": "Klicke mit gedrückter Umschalttaste (Shift) auf diesen Link, um ihn in der Vorschau zu öffnen."
+  },
+  "onboarding_clickKeycap": {
+    "message": "Klick"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "Wechsle zurück zu diesem Tab, dann schließt sich das Fenster automatisch."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "Fertig – jetzt kannst du Links in der Vorschau ansehen, ohne die Seite zu verlassen"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "Du hast die Information erhalten und bist sofort zurückgekehrt!\nDas reduziert den Aufwand für Tab-Wechsel, damit du dich auf das Wesentliche konzentrieren kannst."
+  },
+  "onboarding_nextButton": {
+    "message": "Weiter"
+  },
+  "onboarding_step4_title": {
+    "message": "Frei anpassen"
+  },
+  "onboarding_step4Explain": {
+    "message": "Befehle lassen sich jederzeit hinzufügen oder bearbeiten"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "Erstellen & Bearbeiten in den Einstellungen"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Entdecken im Selection Command Hub"
+  },
+  "onboarding_completeTitle": {
+    "message": "Alles bereit!"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command ist einsatzbereit.\nWähle einfach Text auf einer beliebigen Seite aus, um loszulegen."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "Einstellungen öffnen"
+  },
+  "onboarding_closeButton": {
+    "message": "Schließen und ausprobieren"
   }
 }
diff --git a/packages/extension/public/_locales/en/messages.json b/packages/extension/public/_locales/en/messages.json
index 8514e366..77b80e6d 100644
--- a/packages/extension/public/_locales/en/messages.json
+++ b/packages/extension/public/_locales/en/messages.json
@@ -1319,5 +1319,161 @@
   },
   "hub_login": {
     "message": "Login to Hub"
+  },
+  "onboarding_step0Title": {
+    "message": "Thanks for installing!",
+    "description": "Onboarding Step0 (intro screen) heading, shown right after install."
+  },
+  "onboarding_step0Body": {
+    "message": "Let's try it out for about a minute, using it as you go.",
+    "description": "Onboarding Step0 (intro screen) body text."
+  },
+  "onboarding_startButton": {
+    "message": "Get Started",
+    "description": "Onboarding Step0 button that advances to Step1 (Search)."
+  },
+  "onboarding_skipButton": {
+    "message": "Skip",
+    "description": "Button shown on every onboarding step to end the onboarding early."
+  },
+  "onboarding_step1Explain": {
+    "message": "Select the text below to try a search right away.",
+    "description": "Onboarding Step1 (Search command) instruction shown before the user selects the sample text."
+  },
+  "onboarding_step1TargetText": {
+    "message": "An extension that lets you search selected text in a single click.",
+    "description": "Onboarding Step1 sample text the user is asked to select to trigger the real popup menu."
+  },
+  "onboarding_selectHint": {
+    "message": "Drag to select the text below",
+    "description": "Onboarding Step1/2 caption instructing the user to drag-select the sample text, shown above the target text card during the selection demo."
+  },
+  "onboarding_railSelect": {
+    "message": "Select",
+    "description": "Onboarding progress rail label for the 'select' beat of the select -> command -> result pattern (Steps 1-3)."
+  },
+  "onboarding_railCommand": {
+    "message": "Command",
+    "description": "Onboarding progress rail label for the 'command' beat."
+  },
+  "onboarding_railResultSearch": {
+    "message": "Search",
+    "description": "Onboarding progress rail label for Step1's result beat (running a search command)."
+  },
+  "onboarding_step1Callout": {
+    "message": "Click this command to search Google.",
+    "description": "Onboarding Step1 callout/speech-bubble text pointing at the default Google search command in the popup menu."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "Switch back to this tab and the window closes automatically.",
+    "description": "Onboarding Step1 hint shown while waiting for the user to return from the search command's popup/tab."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "Click anywhere on the screen",
+    "description": "Onboarding Step1 callout/speech-bubble text prompting the user to click anywhere on the original page to dismiss the return hint and continue."
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "That's it - you can now search for anything you select in an instant",
+    "description": "Onboarding Step1 value message shown after the user runs the search command and returns to the onboarding tab."
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "Add your favorite search engine to make everyday searches even faster.",
+    "description": "Onboarding Step1 value sub-message, shown under the main value message once the search result has been seen."
+  },
+  "onboarding_step2Explain": {
+    "message": "Next, let's ask AI about the text below.",
+    "description": "Onboarding Step2 (AiPrompt command) instruction shown before the user selects the sample text."
+  },
+  "onboarding_step2TargetText": {
+    "message": "Think of some ideas for what you could do with a Chrome extension that lets you embed text from the web into a prompt and run it.",
+    "description": "Onboarding Step2 sample text the user is asked to select to trigger the AiPrompt command."
+  },
+  "onboarding_step2Callout": {
+    "message": "Run this command to send your selected text + a prompt to the AI.",
+    "description": "Onboarding Step2 callout/speech-bubble text pointing at the onboarding's dedicated AiPrompt command in the popup menu."
+  },
+  "onboarding_railResultAi": {
+    "message": "AI",
+    "description": "Onboarding progress rail label for Step2's result beat (asking AI)."
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "Sending your selected text + prompt to AI...",
+    "description": "Onboarding Step2 hint shown briefly while the AiPrompt command's request to the AI is in flight."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "You can now ask AI about anything you select, right from the page you're reading",
+    "description": "Onboarding Step2 value message shown after the user runs the AiPrompt command."
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "Instantly ask AI things like \"summarize this\" or \"analyze this company.\"\nYou can freely customize the prompt.",
+    "description": "Onboarding Step2 value sub-message. Contains a \\n line break rendered as <br> at display time - keep it as a literal \\n rather than an HTML tag."
+  },
+  "onboarding_step3Explain": {
+    "message": "Let's preview a link without opening a new tab.",
+    "description": "Onboarding Step3 (Link Preview) instruction."
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "Sample Link",
+    "description": "Label of the sample link shown in Onboarding Step3 for the user to Shift+click."
+  },
+  "onboarding_railResultPreview": {
+    "message": "Preview",
+    "description": "Onboarding progress rail label for Step3's result beat (previewing a link)."
+  },
+  "onboarding_step3Callout": {
+    "message": "Shift+click this link to preview it.",
+    "description": "Onboarding Step3 callout/speech-bubble text pointing at the sample link, prompting the user to Shift+click it to trigger Link Preview."
+  },
+  "onboarding_clickKeycap": {
+    "message": "Click",
+    "description": "Keycap-style label paired with a mouse-click icon in Onboarding Step3's Shift+Click callout."
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "Switch back to this tab and the window closes automatically.",
+    "description": "Onboarding Step3 hint shown while waiting for the user to return from the link preview's popup/tab."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "That's it - you can preview links without leaving the page",
+    "description": "Onboarding Step3 value message shown after the user triggers Link Preview."
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "You got the info and came right back!\nThis cuts down on tab-switching, so you can stay focused on what you need to do.",
+    "description": "Onboarding Step3 value sub-message. Contains a \\n line break rendered as <br> at display time - keep it as a literal \\n rather than an HTML tag."
+  },
+  "onboarding_nextButton": {
+    "message": "Next",
+    "description": "Button that advances from a step's value message to the next onboarding step."
+  },
+  "onboarding_step4_title": {
+    "message": "Customize Freely",
+    "description": "Onboarding Step4 heading, shown after the numeral \"4.\" prefix in the UI. Introduces the customize step."
+  },
+  "onboarding_step4Explain": {
+    "message": "You can add or edit commands anytime",
+    "description": "Onboarding Step4 (Customize) explanation shown after Link Preview, before the final Complete screen. A celebratory emoji is appended directly after this text in the UI, so it intentionally omits trailing punctuation."
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "Create & Edit in Settings",
+    "description": "Onboarding Step4 heading above the settings-panel screenshot, pointing to the extension's own command settings screen."
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Discover on the Selection Command Hub",
+    "description": "Onboarding Step4 heading above the Command Hub screenshot, pointing to where users can discover more commands."
+  },
+  "onboarding_completeTitle": {
+    "message": "You're all set!",
+    "description": "Onboarding Step5 (Complete) heading, the final screen."
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command is ready to use.\nJust select text on any page to get started.",
+    "description": "Onboarding Step5 (Complete) body text. Contains a \\n line break rendered as <br> at display time - keep it as a literal \\n rather than an HTML tag."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "Open Settings",
+    "description": "Onboarding Step5 button that opens the extension's options page."
+  },
+  "onboarding_closeButton": {
+    "message": "Close and try it out",
+    "description": "Onboarding Step5 button that closes the onboarding tab and returns the user to the page they were on - doubles as the step's main call to action."
   }
 }
diff --git a/packages/extension/public/_locales/es/messages.json b/packages/extension/public/_locales/es/messages.json
index 64e8143a..4dc78aef 100644
--- a/packages/extension/public/_locales/es/messages.json
+++ b/packages/extension/public/_locales/es/messages.json
@@ -1301,5 +1301,122 @@
   },
   "hub_login": {
     "message": "Iniciar sesión en Hub"
+  },
+  "onboarding_step0Title": {
+    "message": "¡Gracias por instalarlo!"
+  },
+  "onboarding_step0Body": {
+    "message": "Probémoslo durante un minuto, usándolo sobre la marcha."
+  },
+  "onboarding_startButton": {
+    "message": "Empezar"
+  },
+  "onboarding_skipButton": {
+    "message": "Omitir"
+  },
+  "onboarding_step1Explain": {
+    "message": "Selecciona el siguiente texto para probar una búsqueda al instante."
+  },
+  "onboarding_step1TargetText": {
+    "message": "Una extensión que te permite buscar el texto seleccionado con un solo clic."
+  },
+  "onboarding_selectHint": {
+    "message": "Arrastra para seleccionar el texto de abajo"
+  },
+  "onboarding_railSelect": {
+    "message": "Seleccionar"
+  },
+  "onboarding_railCommand": {
+    "message": "Comando"
+  },
+  "onboarding_railResultSearch": {
+    "message": "Buscar"
+  },
+  "onboarding_step1Callout": {
+    "message": "Haz clic en este comando para buscar en Google."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "Vuelve a esta pestaña y la ventana se cerrará automáticamente."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "Haz clic en cualquier parte de la pantalla"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "Listo: ahora puedes buscar al instante cualquier texto que selecciones"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "Añade tu motor de búsqueda favorito para hacer las búsquedas cotidianas aún más rápidas."
+  },
+  "onboarding_step2Explain": {
+    "message": "A continuación, preguntemos a la IA sobre el siguiente texto."
+  },
+  "onboarding_step2TargetText": {
+    "message": "Piensa en algunas ideas de lo que podrías hacer con una extensión de Chrome que te permite insertar texto de la web en un prompt y ejecutarlo."
+  },
+  "onboarding_step2Callout": {
+    "message": "Ejecuta este comando para enviar tu texto seleccionado + un prompt a la IA."
+  },
+  "onboarding_railResultAi": {
+    "message": "IA"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "Enviando tu texto seleccionado + un prompt a la IA…"
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "Ahora puedes preguntarle a la IA sobre cualquier cosa que selecciones, sin salir de la página que estás leyendo"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "Pide a la IA cosas como «resume esto» o «analiza esta empresa» al instante.\nPuedes personalizar el prompt libremente."
+  },
+  "onboarding_step3Explain": {
+    "message": "Previsualicemos un enlace sin abrir una nueva pestaña."
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "Enlace de ejemplo"
+  },
+  "onboarding_railResultPreview": {
+    "message": "Vista previa"
+  },
+  "onboarding_step3Callout": {
+    "message": "Haz Shift+clic en este enlace para previsualizarlo."
+  },
+  "onboarding_clickKeycap": {
+    "message": "Clic"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "Vuelve a esta pestaña y la ventana se cerrará automáticamente."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "Listo: ahora puedes previsualizar enlaces sin salir de la página"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "¡Obtuviste la información y volviste enseguida!\nEsto reduce el trabajo de cambiar de pestañas, para que puedas concentrarte en lo que importa."
+  },
+  "onboarding_nextButton": {
+    "message": "Siguiente"
+  },
+  "onboarding_step4_title": {
+    "message": "Personaliza a tu gusto"
+  },
+  "onboarding_step4Explain": {
+    "message": "Puedes añadir o editar comandos en cualquier momento"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "Crear y editar en Configuración"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Descubre en el Selection Command Hub"
+  },
+  "onboarding_completeTitle": {
+    "message": "¡Todo listo!"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command ya está listo para usarse.\nSolo selecciona texto en cualquier página para empezar."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "Abrir configuración"
+  },
+  "onboarding_closeButton": {
+    "message": "Cerrar y probarlo"
   }
 }
diff --git a/packages/extension/public/_locales/fr/messages.json b/packages/extension/public/_locales/fr/messages.json
index 3f91714e..cd716827 100644
--- a/packages/extension/public/_locales/fr/messages.json
+++ b/packages/extension/public/_locales/fr/messages.json
@@ -1301,5 +1301,122 @@
   },
   "hub_login": {
     "message": "Se connecter au Hub"
+  },
+  "onboarding_step0Title": {
+    "message": "Merci pour l'installation !"
+  },
+  "onboarding_step0Body": {
+    "message": "Prenons une minute pour l'essayer en pratique."
+  },
+  "onboarding_startButton": {
+    "message": "Commencer"
+  },
+  "onboarding_skipButton": {
+    "message": "Passer"
+  },
+  "onboarding_step1Explain": {
+    "message": "Sélectionnez le texte ci-dessous pour essayer une recherche immédiatement."
+  },
+  "onboarding_step1TargetText": {
+    "message": "Une extension qui permet de rechercher le texte sélectionné en un clic."
+  },
+  "onboarding_selectHint": {
+    "message": "Faites glisser pour sélectionner le texte ci-dessous"
+  },
+  "onboarding_railSelect": {
+    "message": "Sélection"
+  },
+  "onboarding_railCommand": {
+    "message": "Commande"
+  },
+  "onboarding_railResultSearch": {
+    "message": "Recherche"
+  },
+  "onboarding_step1Callout": {
+    "message": "Cliquez sur cette commande pour rechercher sur Google."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "Revenez à cet onglet et la fenêtre se fermera automatiquement."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "Cliquez n'importe où sur l'écran"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "Et voilà — vous pouvez désormais rechercher instantanément tout ce que vous sélectionnez"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "Ajoutez votre moteur de recherche préféré pour rendre vos recherches quotidiennes encore plus rapides."
+  },
+  "onboarding_step2Explain": {
+    "message": "Ensuite, interrogeons l'IA à propos du texte ci-dessous."
+  },
+  "onboarding_step2TargetText": {
+    "message": "Réfléchissez à ce que vous pourriez faire avec une extension Chrome qui permet d'intégrer du texte du web dans un prompt et de l'exécuter."
+  },
+  "onboarding_step2Callout": {
+    "message": "Exécutez cette commande pour envoyer votre texte sélectionné + un prompt à l'IA."
+  },
+  "onboarding_railResultAi": {
+    "message": "IA"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "Envoi de votre texte sélectionné + un prompt à l'IA en cours…"
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "Vous pouvez désormais interroger l'IA sur tout ce que vous sélectionnez, directement depuis la page que vous lisez"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "Demandez instantanément à l'IA des choses comme « résume ceci » ou « analyse cette entreprise ».\nVous pouvez personnaliser le prompt librement."
+  },
+  "onboarding_step3Explain": {
+    "message": "Prévisualisons un lien sans ouvrir un nouvel onglet."
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "Lien d'exemple"
+  },
+  "onboarding_railResultPreview": {
+    "message": "Aperçu"
+  },
+  "onboarding_step3Callout": {
+    "message": "Faites Shift+clic sur ce lien pour le prévisualiser."
+  },
+  "onboarding_clickKeycap": {
+    "message": "Clic"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "Revenez à cet onglet et la fenêtre se fermera automatiquement."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "Et voilà — vous pouvez désormais prévisualiser des liens sans quitter la page"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "Vous avez obtenu l'information et êtes revenu aussitôt !\nCela réduit la gestion des onglets, pour que vous puissiez vous concentrer sur l'essentiel."
+  },
+  "onboarding_nextButton": {
+    "message": "Suivant"
+  },
+  "onboarding_step4_title": {
+    "message": "Personnalisez à votre guise"
+  },
+  "onboarding_step4Explain": {
+    "message": "Vous pouvez ajouter ou modifier des commandes à tout moment"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "Créer et modifier dans les paramètres"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Découvrez sur le Selection Command Hub"
+  },
+  "onboarding_completeTitle": {
+    "message": "Tout est prêt !"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command est prêt à l'emploi.\nIl vous suffit de sélectionner du texte sur n'importe quelle page pour commencer."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "Ouvrir les paramètres"
+  },
+  "onboarding_closeButton": {
+    "message": "Fermer et essayer"
   }
 }
diff --git a/packages/extension/public/_locales/hi/messages.json b/packages/extension/public/_locales/hi/messages.json
index 21d441da..2ec54606 100644
--- a/packages/extension/public/_locales/hi/messages.json
+++ b/packages/extension/public/_locales/hi/messages.json
@@ -1301,5 +1301,122 @@
   },
   "hub_login": {
     "message": "Hub में लॉगिन करें"
+  },
+  "onboarding_step0Title": {
+    "message": "इंस्टॉल करने के लिए धन्यवाद!"
+  },
+  "onboarding_step0Body": {
+    "message": "चलिए, इसे इस्तेमाल करते हुए लगभग एक मिनट में आज़माते हैं।"
+  },
+  "onboarding_startButton": {
+    "message": "शुरू करें"
+  },
+  "onboarding_skipButton": {
+    "message": "छोड़ें"
+  },
+  "onboarding_step1Explain": {
+    "message": "तुरंत सर्च आज़माने के लिए नीचे दिए गए टेक्स्ट को चुनें।"
+  },
+  "onboarding_step1TargetText": {
+    "message": "एक एक्सटेंशन जिससे आप चुने हुए टेक्स्ट को एक क्लिक में सर्च कर सकते हैं।"
+  },
+  "onboarding_selectHint": {
+    "message": "नीचे दिए गए टेक्स्ट को खींचकर चुनें"
+  },
+  "onboarding_railSelect": {
+    "message": "चयन"
+  },
+  "onboarding_railCommand": {
+    "message": "कमांड"
+  },
+  "onboarding_railResultSearch": {
+    "message": "खोजें"
+  },
+  "onboarding_step1Callout": {
+    "message": "इस कमांड को चलाने पर Google पर सर्च होगा।"
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "इस टैब पर वापस आएं और विंडो अपने आप बंद हो जाएगी।"
+  },
+  "onboarding_step1Callout_2": {
+    "message": "स्क्रीन पर कहीं भी क्लिक करें"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "बस इतना ही — अब आप जो भी टेक्स्ट चुनें, उसे तुरंत सर्च कर सकते हैं"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "अपना पसंदीदा सर्च इंजन जोड़कर रोज़मर्रा की खोज को और तेज़ बनाएं।"
+  },
+  "onboarding_step2Explain": {
+    "message": "अब, नीचे दिए गए टेक्स्ट के बारे में AI से पूछते हैं।"
+  },
+  "onboarding_step2TargetText": {
+    "message": "सोचिए कि आप एक ऐसे Chrome एक्सटेंशन से क्या-क्या कर सकते हैं, जो वेब पर मौजूद टेक्स्ट को प्रॉम्प्ट में डालकर चला सकता है।"
+  },
+  "onboarding_step2Callout": {
+    "message": "इस कमांड को चलाने पर आपका चुना हुआ टेक्स्ट + एक प्रॉम्प्ट AI को भेजा जाता है।"
+  },
+  "onboarding_railResultAi": {
+    "message": "AI"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "आपका चुना हुआ टेक्स्ट + प्रॉम्प्ट AI को भेजा जा रहा है..."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "अब आप जो पेज पढ़ रहे हैं, वहीं से चुनी हुई किसी भी चीज़ के बारे में AI से पूछ सकते हैं"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "\"इसका सारांश दें\" या \"इस कंपनी का विश्लेषण करें\" जैसी बातें तुरंत AI से पूछें।\nप्रॉम्प्ट को अपनी इच्छानुसार अनुकूलित किया जा सकता है।"
+  },
+  "onboarding_step3Explain": {
+    "message": "बिना नया टैब खोले किसी लिंक का पूर्वावलोकन करते हैं।"
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "नमूना लिंक"
+  },
+  "onboarding_railResultPreview": {
+    "message": "पूर्वावलोकन"
+  },
+  "onboarding_step3Callout": {
+    "message": "इस लिंक पर Shift दबाकर क्लिक करें और उसका पूर्वावलोकन देखें।"
+  },
+  "onboarding_clickKeycap": {
+    "message": "क्लिक"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "इस टैब पर वापस आएं और विंडो अपने आप बंद हो जाएगी।"
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "बस इतना ही — अब आप पेज छोड़े बिना लिंक का पूर्वावलोकन कर सकते हैं"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "आपको जानकारी मिल गई और आप तुरंत वापस आ गए!\nइससे टैब बदलने की झंझट कम होती है, ताकि आप ज़रूरी काम पर ध्यान दे सकें।"
+  },
+  "onboarding_nextButton": {
+    "message": "आगे"
+  },
+  "onboarding_step4_title": {
+    "message": "अपनी पसंद के अनुसार अनुकूलित करें"
+  },
+  "onboarding_step4Explain": {
+    "message": "आप कभी भी कमांड जोड़ या संपादित कर सकते हैं"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "सेटिंग्स में बनाएं और संपादित करें"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Selection Command Hub पर खोजें"
+  },
+  "onboarding_completeTitle": {
+    "message": "सब तैयार है!"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command उपयोग के लिए तैयार है।\nशुरू करने के लिए किसी भी पेज पर टेक्स्ट चुनें।"
+  },
+  "onboarding_openSettingsButton": {
+    "message": "सेटिंग्स खोलें"
+  },
+  "onboarding_closeButton": {
+    "message": "बंद करें और आज़माएं"
   }
 }
diff --git a/packages/extension/public/_locales/id/messages.json b/packages/extension/public/_locales/id/messages.json
index a34ea6d4..6cd36074 100644
--- a/packages/extension/public/_locales/id/messages.json
+++ b/packages/extension/public/_locales/id/messages.json
@@ -1304,5 +1304,122 @@
   },
   "hub_login": {
     "message": "Masuk ke Hub"
+  },
+  "onboarding_step0Title": {
+    "message": "Terima kasih telah menginstal!"
+  },
+  "onboarding_step0Body": {
+    "message": "Mari coba selama sekitar satu menit sambil langsung mempraktikkannya."
+  },
+  "onboarding_startButton": {
+    "message": "Mulai"
+  },
+  "onboarding_skipButton": {
+    "message": "Lewati"
+  },
+  "onboarding_step1Explain": {
+    "message": "Pilih teks di bawah ini untuk langsung mencoba pencarian."
+  },
+  "onboarding_step1TargetText": {
+    "message": "Ekstensi yang memungkinkan Anda mencari teks yang dipilih hanya dengan satu klik."
+  },
+  "onboarding_selectHint": {
+    "message": "Seret untuk memilih teks di bawah"
+  },
+  "onboarding_railSelect": {
+    "message": "Pilih"
+  },
+  "onboarding_railCommand": {
+    "message": "Perintah"
+  },
+  "onboarding_railResultSearch": {
+    "message": "Cari"
+  },
+  "onboarding_step1Callout": {
+    "message": "Klik perintah ini untuk mencari di Google."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "Kembali ke tab ini dan jendela akan tertutup secara otomatis."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "Klik di mana saja pada layar"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "Selesai — sekarang Anda bisa langsung mencari apa pun yang Anda pilih"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "Tambahkan mesin pencari favorit Anda untuk membuat pencarian sehari-hari lebih cepat."
+  },
+  "onboarding_step2Explain": {
+    "message": "Selanjutnya, mari tanyakan ke AI tentang teks di bawah ini."
+  },
+  "onboarding_step2TargetText": {
+    "message": "Pikirkan ide-ide tentang apa yang bisa Anda lakukan dengan ekstensi Chrome yang dapat menyematkan teks dari web ke dalam prompt dan menjalankannya."
+  },
+  "onboarding_step2Callout": {
+    "message": "Jalankan perintah ini untuk mengirim teks yang dipilih + sebuah prompt ke AI."
+  },
+  "onboarding_railResultAi": {
+    "message": "AI"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "Mengirim teks yang dipilih + prompt ke AI..."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "Sekarang Anda bisa bertanya ke AI tentang apa pun yang Anda pilih, langsung dari halaman yang sedang Anda baca"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "Segera minta AI melakukan hal seperti \"ringkas ini\" atau \"analisis perusahaan ini\".\nPrompt dapat disesuaikan secara bebas."
+  },
+  "onboarding_step3Explain": {
+    "message": "Mari pratinjau sebuah tautan tanpa membuka tab baru."
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "Tautan Contoh"
+  },
+  "onboarding_railResultPreview": {
+    "message": "Pratinjau"
+  },
+  "onboarding_step3Callout": {
+    "message": "Shift+klik tautan ini untuk melihat pratinjaunya."
+  },
+  "onboarding_clickKeycap": {
+    "message": "Klik"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "Kembali ke tab ini dan jendela akan tertutup secara otomatis."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "Selesai — sekarang Anda bisa melihat pratinjau tautan tanpa meninggalkan halaman"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "Anda mendapatkan informasinya dan langsung kembali!\nIni mengurangi repotnya berpindah tab, sehingga Anda bisa fokus pada hal yang penting."
+  },
+  "onboarding_nextButton": {
+    "message": "Berikutnya"
+  },
+  "onboarding_step4_title": {
+    "message": "Sesuaikan Sesuka Anda"
+  },
+  "onboarding_step4Explain": {
+    "message": "Anda dapat menambah atau mengedit perintah kapan saja"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "Buat & Edit di Pengaturan"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Temukan di Selection Command Hub"
+  },
+  "onboarding_completeTitle": {
+    "message": "Semua sudah siap!"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command siap digunakan.\nCukup pilih teks di halaman mana pun untuk memulai."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "Buka Pengaturan"
+  },
+  "onboarding_closeButton": {
+    "message": "Tutup dan coba sekarang"
   }
 }
diff --git a/packages/extension/public/_locales/it/messages.json b/packages/extension/public/_locales/it/messages.json
index ce36201e..f5baecca 100644
--- a/packages/extension/public/_locales/it/messages.json
+++ b/packages/extension/public/_locales/it/messages.json
@@ -1301,5 +1301,122 @@
   },
   "hub_login": {
     "message": "Accedi all'Hub"
+  },
+  "onboarding_step0Title": {
+    "message": "Grazie per averlo installato!"
+  },
+  "onboarding_step0Body": {
+    "message": "Proviamolo per circa un minuto, usandolo direttamente."
+  },
+  "onboarding_startButton": {
+    "message": "Inizia"
+  },
+  "onboarding_skipButton": {
+    "message": "Salta"
+  },
+  "onboarding_step1Explain": {
+    "message": "Seleziona il testo qui sotto per provare subito una ricerca."
+  },
+  "onboarding_step1TargetText": {
+    "message": "Un'estensione che ti permette di cercare il testo selezionato con un solo clic."
+  },
+  "onboarding_selectHint": {
+    "message": "Trascina per selezionare il testo qui sotto"
+  },
+  "onboarding_railSelect": {
+    "message": "Seleziona"
+  },
+  "onboarding_railCommand": {
+    "message": "Comando"
+  },
+  "onboarding_railResultSearch": {
+    "message": "Cerca"
+  },
+  "onboarding_step1Callout": {
+    "message": "Fai clic su questo comando per cercare su Google."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "Torna a questa scheda e la finestra si chiuderà automaticamente."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "Fai clic in un punto qualsiasi dello schermo"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "Fatto: ora puoi cercare all'istante qualsiasi cosa selezioni"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "Aggiungi il tuo motore di ricerca preferito per rendere le ricerche quotidiane ancora più veloci."
+  },
+  "onboarding_step2Explain": {
+    "message": "Ora chiediamo all'IA il testo qui sotto."
+  },
+  "onboarding_step2TargetText": {
+    "message": "Pensa a qualche idea su cosa potresti fare con un'estensione Chrome che ti permette di inserire testo dal web in un prompt ed eseguirlo."
+  },
+  "onboarding_step2Callout": {
+    "message": "Esegui questo comando per inviare il testo selezionato + un prompt all'IA."
+  },
+  "onboarding_railResultAi": {
+    "message": "IA"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "Invio del testo selezionato + prompt all'IA in corso..."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "Ora puoi chiedere all'IA qualsiasi cosa selezioni, direttamente dalla pagina che stai leggendo"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "Chiedi subito all'IA cose come \"riassumi questo\" o \"analizza questa azienda\".\nPuoi personalizzare liberamente il prompt."
+  },
+  "onboarding_step3Explain": {
+    "message": "Visualizziamo l'anteprima di un link senza aprire una nuova scheda."
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "Link di esempio"
+  },
+  "onboarding_railResultPreview": {
+    "message": "Anteprima"
+  },
+  "onboarding_step3Callout": {
+    "message": "Fai Shift+clic su questo link per visualizzarne l'anteprima."
+  },
+  "onboarding_clickKeycap": {
+    "message": "Clic"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "Torna a questa scheda e la finestra si chiuderà automaticamente."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "Fatto: ora puoi visualizzare l'anteprima dei link senza lasciare la pagina"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "Hai ottenuto le informazioni e sei tornato subito indietro!\nQuesto riduce la gestione delle schede, così puoi concentrarti su ciò che conta."
+  },
+  "onboarding_nextButton": {
+    "message": "Avanti"
+  },
+  "onboarding_step4_title": {
+    "message": "Personalizza come preferisci"
+  },
+  "onboarding_step4Explain": {
+    "message": "Puoi aggiungere o modificare comandi in qualsiasi momento"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "Crea e modifica nelle impostazioni"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Scopri su Selection Command Hub"
+  },
+  "onboarding_completeTitle": {
+    "message": "Tutto pronto!"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command è pronto all'uso.\nSeleziona del testo in qualsiasi pagina per iniziare."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "Apri impostazioni"
+  },
+  "onboarding_closeButton": {
+    "message": "Chiudi e provalo"
   }
 }
diff --git a/packages/extension/public/_locales/ja/messages.json b/packages/extension/public/_locales/ja/messages.json
index 453c3517..ad47d4c2 100644
--- a/packages/extension/public/_locales/ja/messages.json
+++ b/packages/extension/public/_locales/ja/messages.json
@@ -1298,5 +1298,122 @@
   },
   "hub_login": {
     "message": "Hubへログイン"
+  },
+  "onboarding_step0Title": {
+    "message": "インストールありがとうございます！"
+  },
+  "onboarding_step0Body": {
+    "message": "まずは1分で、実際に使いながら試してみましょう。"
+  },
+  "onboarding_startButton": {
+    "message": "はじめる"
+  },
+  "onboarding_skipButton": {
+    "message": "スキップ"
+  },
+  "onboarding_step1Explain": {
+    "message": "気になるテキストを選択して、すぐに検索してみましょう。"
+  },
+  "onboarding_step1TargetText": {
+    "message": "選択テキストをワンクリックで検索できる拡張機能"
+  },
+  "onboarding_selectHint": {
+    "message": "下のテキストをドラッグして選択"
+  },
+  "onboarding_railSelect": {
+    "message": "選択"
+  },
+  "onboarding_railCommand": {
+    "message": "コマンド"
+  },
+  "onboarding_railResultSearch": {
+    "message": "検索"
+  },
+  "onboarding_step1Callout": {
+    "message": "このコマンドを実行すると、Googleで検索できます。"
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "もとの画面を選択すると、ウィンドウが自動的に消えます"
+  },
+  "onboarding_step1Callout_2": {
+    "message": "画面のどこかをクリック"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "これで、気になった情報をすぐに検索できました"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "好きな検索エンジンを追加すれば、いつもの検索をもっと高速にできます。"
+  },
+  "onboarding_step2Explain": {
+    "message": "次は、選択したテキストをAIに聞いてみましょう。"
+  },
+  "onboarding_step2TargetText": {
+    "message": "Web上のテキストをプロンプトに埋め込んで実行できるChrome拡張機能によって、どんなことが出来るかアイデアを考えてください。"
+  },
+  "onboarding_step2Callout": {
+    "message": "このコマンドを実行すると、選択したテキスト + プロンプトをAIに送れます。"
+  },
+  "onboarding_railResultAi": {
+    "message": "AI"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "選択したテキスト + プロンプトをAIへ送信中..."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "Webページを読みながら、その場でAIに質問できました"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "「要約して」「この企業を分析」などをすぐにAIへ依頼できます。\nプロンプトは自由にカスタマイズができます。"
+  },
+  "onboarding_step3Explain": {
+    "message": "リンク先をタブを開かずに確認してみましょう。"
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "サンプルリンク"
+  },
+  "onboarding_railResultPreview": {
+    "message": "プレビュー"
+  },
+  "onboarding_step3Callout": {
+    "message": "このリンクをShift+クリックすると、プレビューできます。"
+  },
+  "onboarding_clickKeycap": {
+    "message": "クリック"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "もとの画面を選択すると、ウィンドウが自動的に消えます"
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "これで、リンク先をその場で確認できました"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "情報を入手して、すぐに戻って来れました！\nこれでタブ操作の手間を削減し、やるべきことに集中できます。"
+  },
+  "onboarding_nextButton": {
+    "message": "次へ"
+  },
+  "onboarding_step4_title": {
+    "message": "好きにカスタマイズ"
+  },
+  "onboarding_step4Explain": {
+    "message": "コマンドはいつでも追加・編集できます"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "設定画面で作成・編集"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Selection Command Hubで発見"
+  },
+  "onboarding_completeTitle": {
+    "message": "準備は完了です！"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Commandを使う準備が整いました。\nページ上のテキストを選択して、さっそく使ってみましょう。"
+  },
+  "onboarding_openSettingsButton": {
+    "message": "設定を開く"
+  },
+  "onboarding_closeButton": {
+    "message": "閉じて使ってみる"
   }
 }
diff --git a/packages/extension/public/_locales/ko/messages.json b/packages/extension/public/_locales/ko/messages.json
index c6f89e08..bbd9cd83 100644
--- a/packages/extension/public/_locales/ko/messages.json
+++ b/packages/extension/public/_locales/ko/messages.json
@@ -1301,5 +1301,122 @@
   },
   "hub_login": {
     "message": "Hub에 로그인"
+  },
+  "onboarding_step0Title": {
+    "message": "설치해 주셔서 감사합니다!"
+  },
+  "onboarding_step0Body": {
+    "message": "먼저 1분 동안 직접 사용해보며 체험해 봅시다."
+  },
+  "onboarding_startButton": {
+    "message": "시작하기"
+  },
+  "onboarding_skipButton": {
+    "message": "건너뛰기"
+  },
+  "onboarding_step1Explain": {
+    "message": "아래 텍스트를 선택해서 바로 검색해 보세요."
+  },
+  "onboarding_step1TargetText": {
+    "message": "선택한 텍스트를 클릭 한 번으로 검색할 수 있는 확장 프로그램"
+  },
+  "onboarding_selectHint": {
+    "message": "아래 텍스트를 드래그하여 선택하세요"
+  },
+  "onboarding_railSelect": {
+    "message": "선택"
+  },
+  "onboarding_railCommand": {
+    "message": "명령"
+  },
+  "onboarding_railResultSearch": {
+    "message": "검색"
+  },
+  "onboarding_step1Callout": {
+    "message": "이 명령을 실행하면 Google로 검색할 수 있습니다."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "이 탭으로 돌아오면 창이 자동으로 닫힙니다."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "화면 아무 곳이나 클릭"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "이제 궁금했던 정보를 바로 검색할 수 있게 되었습니다"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "좋아하는 검색 엔진을 추가하면 평소 검색을 더 빠르게 할 수 있어요."
+  },
+  "onboarding_step2Explain": {
+    "message": "다음으로 아래 텍스트에 대해 AI에게 물어봅시다."
+  },
+  "onboarding_step2TargetText": {
+    "message": "웹의 텍스트를 프롬프트에 넣어 실행할 수 있는 Chrome 확장 프로그램으로 무엇을 할 수 있을지 아이디어를 생각해 보세요."
+  },
+  "onboarding_step2Callout": {
+    "message": "이 명령을 실행하면 선택한 텍스트 + 프롬프트를 AI에 보낼 수 있습니다."
+  },
+  "onboarding_railResultAi": {
+    "message": "AI"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "선택한 텍스트 + 프롬프트를 AI에 전송 중..."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "이제 페이지를 읽으면서 바로 AI에게 무엇이든 물어볼 수 있습니다"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "\"요약해줘\", \"이 기업을 분석해줘\" 같은 요청을 AI에 바로 할 수 있어요.\n프롬프트는 자유롭게 커스터마이징할 수 있습니다."
+  },
+  "onboarding_step3Explain": {
+    "message": "새 탭을 열지 않고 링크를 미리 볼까요?"
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "샘플 링크"
+  },
+  "onboarding_railResultPreview": {
+    "message": "미리보기"
+  },
+  "onboarding_step3Callout": {
+    "message": "이 링크를 Shift+클릭하면 미리보기를 볼 수 있습니다."
+  },
+  "onboarding_clickKeycap": {
+    "message": "클릭"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "이 탭으로 돌아오면 창이 자동으로 닫힙니다."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "이제 페이지를 벗어나지 않고 링크를 미리 볼 수 있습니다"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "정보를 얻고 바로 돌아올 수 있었어요!\n탭 전환의 번거로움을 줄여, 해야 할 일에 집중할 수 있습니다."
+  },
+  "onboarding_nextButton": {
+    "message": "다음"
+  },
+  "onboarding_step4_title": {
+    "message": "자유롭게 커스터마이징"
+  },
+  "onboarding_step4Explain": {
+    "message": "명령어는 언제든지 추가하거나 편집할 수 있어요"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "설정에서 만들고 편집하기"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Selection Command Hub에서 발견하기"
+  },
+  "onboarding_completeTitle": {
+    "message": "준비가 완료되었습니다!"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command를 사용할 준비가 되었습니다.\n페이지에서 텍스트를 선택해 바로 사용해 보세요."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "설정 열기"
+  },
+  "onboarding_closeButton": {
+    "message": "닫고 사용해보기"
   }
 }
diff --git a/packages/extension/public/_locales/ms/messages.json b/packages/extension/public/_locales/ms/messages.json
index 0bb6f011..fc1bc922 100644
--- a/packages/extension/public/_locales/ms/messages.json
+++ b/packages/extension/public/_locales/ms/messages.json
@@ -1304,5 +1304,122 @@
   },
   "hub_login": {
     "message": "Log masuk ke Hub"
+  },
+  "onboarding_step0Title": {
+    "message": "Terima kasih kerana memasangnya!"
+  },
+  "onboarding_step0Body": {
+    "message": "Jom cuba selama lebih kurang seminit sambil terus menggunakannya."
+  },
+  "onboarding_startButton": {
+    "message": "Mula"
+  },
+  "onboarding_skipButton": {
+    "message": "Langkau"
+  },
+  "onboarding_step1Explain": {
+    "message": "Pilih teks di bawah untuk cuba carian dengan segera."
+  },
+  "onboarding_step1TargetText": {
+    "message": "Sambungan yang membolehkan anda mencari teks yang dipilih hanya dengan satu klik."
+  },
+  "onboarding_selectHint": {
+    "message": "Seret untuk pilih teks di bawah"
+  },
+  "onboarding_railSelect": {
+    "message": "Pilih"
+  },
+  "onboarding_railCommand": {
+    "message": "Arahan"
+  },
+  "onboarding_railResultSearch": {
+    "message": "Cari"
+  },
+  "onboarding_step1Callout": {
+    "message": "Klik arahan ini untuk mencari di Google."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "Kembali ke tab ini dan tetingkap akan tertutup secara automatik."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "Klik di mana-mana pada skrin"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "Selesai — kini anda boleh mencari dengan segera apa sahaja yang anda pilih"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "Tambahkan enjin carian kegemaran anda untuk menjadikan carian harian lebih pantas."
+  },
+  "onboarding_step2Explain": {
+    "message": "Seterusnya, mari tanya AI tentang teks di bawah ini."
+  },
+  "onboarding_step2TargetText": {
+    "message": "Fikirkan beberapa idea tentang apa yang boleh anda lakukan dengan sambungan Chrome yang membolehkan anda menyisipkan teks daripada web ke dalam gesaan dan menjalankannya."
+  },
+  "onboarding_step2Callout": {
+    "message": "Jalankan arahan ini untuk menghantar teks yang dipilih + gesaan kepada AI."
+  },
+  "onboarding_railResultAi": {
+    "message": "AI"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "Menghantar teks yang dipilih + gesaan kepada AI..."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "Kini anda boleh bertanya kepada AI tentang apa sahaja yang anda pilih, terus daripada halaman yang sedang anda baca"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "Minta AI melakukan perkara seperti \"ringkaskan ini\" atau \"analisis syarikat ini\" dengan segera.\nGesaan boleh disesuaikan mengikut citarasa anda."
+  },
+  "onboarding_step3Explain": {
+    "message": "Mari pratonton pautan tanpa membuka tab baharu."
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "Pautan Contoh"
+  },
+  "onboarding_railResultPreview": {
+    "message": "Pratonton"
+  },
+  "onboarding_step3Callout": {
+    "message": "Shift+klik pautan ini untuk pratonton."
+  },
+  "onboarding_clickKeycap": {
+    "message": "Klik"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "Kembali ke tab ini dan tetingkap akan tertutup secara automatik."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "Selesai — kini anda boleh pratonton pautan tanpa meninggalkan halaman"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "Anda mendapat maklumat dan terus kembali!\nIni mengurangkan kerumitan menukar tab, supaya anda boleh fokus pada perkara yang penting."
+  },
+  "onboarding_nextButton": {
+    "message": "Seterusnya"
+  },
+  "onboarding_step4_title": {
+    "message": "Sesuaikan Mengikut Citarasa Anda"
+  },
+  "onboarding_step4Explain": {
+    "message": "Anda boleh menambah atau mengedit arahan pada bila-bila masa"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "Cipta & Edit dalam Tetapan"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Temui di Selection Command Hub"
+  },
+  "onboarding_completeTitle": {
+    "message": "Semuanya sedia!"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command sedia digunakan.\nPilih sahaja teks pada mana-mana halaman untuk bermula."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "Buka Tetapan"
+  },
+  "onboarding_closeButton": {
+    "message": "Tutup dan cuba sekarang"
   }
 }
diff --git a/packages/extension/public/_locales/pt_BR/messages.json b/packages/extension/public/_locales/pt_BR/messages.json
index 5e865323..8768173a 100644
--- a/packages/extension/public/_locales/pt_BR/messages.json
+++ b/packages/extension/public/_locales/pt_BR/messages.json
@@ -1304,5 +1304,122 @@
   },
   "hub_login": {
     "message": "Entrar no Hub"
+  },
+  "onboarding_step0Title": {
+    "message": "Obrigado por instalar!"
+  },
+  "onboarding_step0Body": {
+    "message": "Vamos experimentar por cerca de um minuto, usando na prática."
+  },
+  "onboarding_startButton": {
+    "message": "Começar"
+  },
+  "onboarding_skipButton": {
+    "message": "Pular"
+  },
+  "onboarding_step1Explain": {
+    "message": "Selecione o texto abaixo para testar uma pesquisa agora mesmo."
+  },
+  "onboarding_step1TargetText": {
+    "message": "Uma extensão que permite pesquisar o texto selecionado com um clique."
+  },
+  "onboarding_selectHint": {
+    "message": "Arraste para selecionar o texto abaixo"
+  },
+  "onboarding_railSelect": {
+    "message": "Selecionar"
+  },
+  "onboarding_railCommand": {
+    "message": "Comando"
+  },
+  "onboarding_railResultSearch": {
+    "message": "Pesquisar"
+  },
+  "onboarding_step1Callout": {
+    "message": "Clique neste comando para pesquisar no Google."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "Volte para esta aba e a janela se fecha automaticamente."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "Clique em qualquer lugar da tela"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "Pronto — agora você pode pesquisar instantaneamente qualquer coisa que selecionar"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "Adicione seu mecanismo de busca favorito para tornar as buscas do dia a dia ainda mais rápidas."
+  },
+  "onboarding_step2Explain": {
+    "message": "A seguir, vamos perguntar à IA sobre o texto abaixo."
+  },
+  "onboarding_step2TargetText": {
+    "message": "Pense em algumas ideias do que você poderia fazer com uma extensão do Chrome que permite inserir texto da web em um prompt e executá-lo."
+  },
+  "onboarding_step2Callout": {
+    "message": "Execute este comando para enviar seu texto selecionado + um prompt para a IA."
+  },
+  "onboarding_railResultAi": {
+    "message": "IA"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "Enviando seu texto selecionado + um prompt para a IA..."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "Agora você pode perguntar à IA sobre qualquer coisa que selecionar, direto da página que está lendo"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "Peça à IA coisas como \"resuma isso\" ou \"analise esta empresa\" instantaneamente.\nVocê pode personalizar o prompt livremente."
+  },
+  "onboarding_step3Explain": {
+    "message": "Vamos pré-visualizar um link sem abrir uma nova aba."
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "Link de exemplo"
+  },
+  "onboarding_railResultPreview": {
+    "message": "Pré-visualização"
+  },
+  "onboarding_step3Callout": {
+    "message": "Shift+clique neste link para pré-visualizá-lo."
+  },
+  "onboarding_clickKeycap": {
+    "message": "Clique"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "Volte para esta aba e a janela se fecha automaticamente."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "Pronto — agora você pode pré-visualizar links sem sair da página"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "Você obteve a informação e voltou na hora!\nIsso reduz o trabalho de trocar de abas, para você focar no que importa."
+  },
+  "onboarding_nextButton": {
+    "message": "Próximo"
+  },
+  "onboarding_step4_title": {
+    "message": "Personalize do Seu Jeito"
+  },
+  "onboarding_step4Explain": {
+    "message": "Você pode adicionar ou editar comandos a qualquer momento"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "Criar e editar nas Configurações"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Descubra no Selection Command Hub"
+  },
+  "onboarding_completeTitle": {
+    "message": "Tudo pronto!"
+  },
+  "onboarding_completeBody": {
+    "message": "O Selection Command está pronto para uso.\nBasta selecionar um texto em qualquer página para começar."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "Abrir configurações"
+  },
+  "onboarding_closeButton": {
+    "message": "Fechar e experimentar"
   }
 }
diff --git a/packages/extension/public/_locales/pt_PT/messages.json b/packages/extension/public/_locales/pt_PT/messages.json
index c57367cc..0f45b75f 100644
--- a/packages/extension/public/_locales/pt_PT/messages.json
+++ b/packages/extension/public/_locales/pt_PT/messages.json
@@ -1304,5 +1304,122 @@
   },
   "hub_login": {
     "message": "Iniciar sessão no Hub"
+  },
+  "onboarding_step0Title": {
+    "message": "Obrigado por instalar!"
+  },
+  "onboarding_step0Body": {
+    "message": "Vamos experimentá-lo durante cerca de um minuto, na prática."
+  },
+  "onboarding_startButton": {
+    "message": "Começar"
+  },
+  "onboarding_skipButton": {
+    "message": "Ignorar"
+  },
+  "onboarding_step1Explain": {
+    "message": "Selecione o texto abaixo para experimentar uma pesquisa de imediato."
+  },
+  "onboarding_step1TargetText": {
+    "message": "Uma extensão que permite pesquisar o texto selecionado com um único clique."
+  },
+  "onboarding_selectHint": {
+    "message": "Arraste para selecionar o texto abaixo"
+  },
+  "onboarding_railSelect": {
+    "message": "Selecionar"
+  },
+  "onboarding_railCommand": {
+    "message": "Comando"
+  },
+  "onboarding_railResultSearch": {
+    "message": "Pesquisar"
+  },
+  "onboarding_step1Callout": {
+    "message": "Clique neste comando para pesquisar no Google."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "Volte a este separador e a janela fecha-se automaticamente."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "Clique em qualquer parte do ecrã"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "Pronto — agora já pode pesquisar instantaneamente tudo o que selecionar"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "Adicione o seu motor de pesquisa preferido para tornar as pesquisas do dia a dia ainda mais rápidas."
+  },
+  "onboarding_step2Explain": {
+    "message": "De seguida, vamos perguntar à IA sobre o texto abaixo."
+  },
+  "onboarding_step2TargetText": {
+    "message": "Pense em algumas ideias sobre o que poderia fazer com uma extensão do Chrome que permite inserir texto da web num prompt e executá-lo."
+  },
+  "onboarding_step2Callout": {
+    "message": "Execute este comando para enviar o texto selecionado + um prompt para a IA."
+  },
+  "onboarding_railResultAi": {
+    "message": "IA"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "A enviar o texto selecionado + um prompt para a IA..."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "Agora já pode perguntar à IA sobre o que selecionar, diretamente a partir da página que está a ler"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "Peça à IA coisas como \"resume isto\" ou \"analisa esta empresa\" instantaneamente.\nPode personalizar o prompt livremente."
+  },
+  "onboarding_step3Explain": {
+    "message": "Vamos pré-visualizar uma ligação sem abrir um novo separador."
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "Ligação de exemplo"
+  },
+  "onboarding_railResultPreview": {
+    "message": "Pré-visualização"
+  },
+  "onboarding_step3Callout": {
+    "message": "Shift+clique neste link para pré-visualizá-lo."
+  },
+  "onboarding_clickKeycap": {
+    "message": "Clique"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "Volte a este separador e a janela fecha-se automaticamente."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "Pronto — agora já pode pré-visualizar ligações sem sair da página"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "Obteve a informação e voltou de imediato!\nIsto reduz o incómodo de mudar de separadores, para que se possa concentrar no que importa."
+  },
+  "onboarding_nextButton": {
+    "message": "Seguinte"
+  },
+  "onboarding_step4_title": {
+    "message": "Personalize ao Seu Gosto"
+  },
+  "onboarding_step4Explain": {
+    "message": "Pode adicionar ou editar comandos a qualquer momento"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "Criar e editar nas Definições"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Descubra no Selection Command Hub"
+  },
+  "onboarding_completeTitle": {
+    "message": "Tudo pronto!"
+  },
+  "onboarding_completeBody": {
+    "message": "O Selection Command está pronto a usar.\nBasta selecionar texto em qualquer página para começar."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "Abrir definições"
+  },
+  "onboarding_closeButton": {
+    "message": "Fechar e experimentar"
   }
 }
diff --git a/packages/extension/public/_locales/ru/messages.json b/packages/extension/public/_locales/ru/messages.json
index 6c25f653..742199b4 100644
--- a/packages/extension/public/_locales/ru/messages.json
+++ b/packages/extension/public/_locales/ru/messages.json
@@ -1301,5 +1301,122 @@
   },
   "hub_login": {
     "message": "Войти в Hub"
+  },
+  "onboarding_step0Title": {
+    "message": "Спасибо за установку!"
+  },
+  "onboarding_step0Body": {
+    "message": "Давайте потратим примерно минуту, чтобы попробовать его в деле."
+  },
+  "onboarding_startButton": {
+    "message": "Начать"
+  },
+  "onboarding_skipButton": {
+    "message": "Пропустить"
+  },
+  "onboarding_step1Explain": {
+    "message": "Выделите текст ниже, чтобы сразу попробовать поиск."
+  },
+  "onboarding_step1TargetText": {
+    "message": "Расширение, позволяющее искать выделенный текст одним щелчком."
+  },
+  "onboarding_selectHint": {
+    "message": "Перетащите, чтобы выделить текст ниже"
+  },
+  "onboarding_railSelect": {
+    "message": "Выделение"
+  },
+  "onboarding_railCommand": {
+    "message": "Команда"
+  },
+  "onboarding_railResultSearch": {
+    "message": "Поиск"
+  },
+  "onboarding_step1Callout": {
+    "message": "Нажмите эту команду, чтобы выполнить поиск в Google."
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "Вернитесь на эту вкладку, и окно автоматически закроется."
+  },
+  "onboarding_step1Callout_2": {
+    "message": "Нажмите в любом месте экрана"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "Готово — теперь вы можете мгновенно искать всё, что выделите"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "Добавьте любимую поисковую систему, чтобы делать повседневный поиск ещё быстрее."
+  },
+  "onboarding_step2Explain": {
+    "message": "Далее давайте спросим ИИ о тексте ниже."
+  },
+  "onboarding_step2TargetText": {
+    "message": "Подумайте, что можно сделать с помощью расширения Chrome, которое позволяет вставлять текст из интернета в запрос и выполнять его."
+  },
+  "onboarding_step2Callout": {
+    "message": "Выполните эту команду, чтобы отправить выделенный текст + запрос в ИИ."
+  },
+  "onboarding_railResultAi": {
+    "message": "ИИ"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "Отправка выделенного текста + запроса в ИИ..."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "Теперь вы можете спрашивать ИИ о чём угодно прямо на странице, которую читаете"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "Мгновенно просите ИИ о таких вещах, как «сделай краткое содержание» или «проанализируй эту компанию».\nПромпт можно свободно настраивать."
+  },
+  "onboarding_step3Explain": {
+    "message": "Давайте просмотрим ссылку без открытия новой вкладки."
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "Пример ссылки"
+  },
+  "onboarding_railResultPreview": {
+    "message": "Просмотр"
+  },
+  "onboarding_step3Callout": {
+    "message": "Нажмите Shift и щёлкните по этой ссылке, чтобы увидеть предпросмотр."
+  },
+  "onboarding_clickKeycap": {
+    "message": "Клик"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "Вернитесь на эту вкладку, и окно автоматически закроется."
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "Готово — теперь вы можете просматривать ссылки, не покидая страницу"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "Вы получили нужную информацию и сразу вернулись обратно!\nЭто снижает необходимость переключаться между вкладками, позволяя сосредоточиться на главном."
+  },
+  "onboarding_nextButton": {
+    "message": "Далее"
+  },
+  "onboarding_step4_title": {
+    "message": "Настройте по своему вкусу"
+  },
+  "onboarding_step4Explain": {
+    "message": "Команды можно добавлять и редактировать в любое время"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "Создать и изменить в настройках"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "Найдите на Selection Command Hub"
+  },
+  "onboarding_completeTitle": {
+    "message": "Всё готово!"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command готов к использованию.\nПросто выделите текст на любой странице, чтобы начать."
+  },
+  "onboarding_openSettingsButton": {
+    "message": "Открыть настройки"
+  },
+  "onboarding_closeButton": {
+    "message": "Закрыть и попробовать"
   }
 }
diff --git a/packages/extension/public/_locales/zh_CN/messages.json b/packages/extension/public/_locales/zh_CN/messages.json
index f9006916..b0a41661 100644
--- a/packages/extension/public/_locales/zh_CN/messages.json
+++ b/packages/extension/public/_locales/zh_CN/messages.json
@@ -1301,5 +1301,122 @@
   },
   "hub_login": {
     "message": "登录 Hub"
+  },
+  "onboarding_step0Title": {
+    "message": "感谢您的安装！"
+  },
+  "onboarding_step0Body": {
+    "message": "让我们花一分钟时间，边操作边体验一下吧。"
+  },
+  "onboarding_startButton": {
+    "message": "开始体验"
+  },
+  "onboarding_skipButton": {
+    "message": "跳过"
+  },
+  "onboarding_step1Explain": {
+    "message": "选择下面的文本，立即试试搜索功能。"
+  },
+  "onboarding_step1TargetText": {
+    "message": "一款可以一键搜索所选文本的扩展程序"
+  },
+  "onboarding_selectHint": {
+    "message": "拖动以选择下方文本"
+  },
+  "onboarding_railSelect": {
+    "message": "选择"
+  },
+  "onboarding_railCommand": {
+    "message": "命令"
+  },
+  "onboarding_railResultSearch": {
+    "message": "搜索"
+  },
+  "onboarding_step1Callout": {
+    "message": "点击此命令即可使用 Google 搜索。"
+  },
+  "onboarding_step1ReturnHint": {
+    "message": "切回此标签页，窗口会自动关闭。"
+  },
+  "onboarding_step1Callout_2": {
+    "message": "点击屏幕上的任意位置"
+  },
+  "onboarding_step1ValueMessage": {
+    "message": "就是这样——现在您可以立即搜索所选的任何内容"
+  },
+  "onboarding_step1ValueSubmessage": {
+    "message": "添加您喜欢的搜索引擎，让日常搜索更快捷。"
+  },
+  "onboarding_step2Explain": {
+    "message": "接下来，让我们向 AI 询问下面这段文字。"
+  },
+  "onboarding_step2TargetText": {
+    "message": "想想你能用这个可以把网页文字嵌入提示词并执行的 Chrome 扩展程序做些什么。"
+  },
+  "onboarding_step2Callout": {
+    "message": "运行此命令，即可将选中文本 + 提示词发送给 AI。"
+  },
+  "onboarding_railResultAi": {
+    "message": "AI"
+  },
+  "onboarding_step2WaitReturn": {
+    "message": "正在将选中文本 + 提示词发送给 AI..."
+  },
+  "onboarding_step2ValueMessage": {
+    "message": "现在，您可以在阅读网页的同时，就您选择的任何内容向 AI 提问"
+  },
+  "onboarding_step2ValueSubmessage": {
+    "message": "立即向 AI 请求「总结一下」「分析这家公司」等操作。\n提示词可以自由自定义。"
+  },
+  "onboarding_step3Explain": {
+    "message": "让我们在不打开新标签页的情况下预览链接。"
+  },
+  "onboarding_step3LinkLabel": {
+    "message": "示例链接"
+  },
+  "onboarding_railResultPreview": {
+    "message": "预览"
+  },
+  "onboarding_step3Callout": {
+    "message": "按住 Shift 并点击此链接即可预览。"
+  },
+  "onboarding_clickKeycap": {
+    "message": "点击"
+  },
+  "onboarding_step3ReturnHint": {
+    "message": "切回此标签页，窗口会自动关闭。"
+  },
+  "onboarding_step3ValueMessage": {
+    "message": "就是这样——现在您可以在不离开当前页面的情况下预览链接"
+  },
+  "onboarding_step3ValueSubmessage": {
+    "message": "获取信息后立即返回！\n这减少了切换标签页的麻烦，让你可以专注于真正重要的事情。"
+  },
+  "onboarding_nextButton": {
+    "message": "下一步"
+  },
+  "onboarding_step4_title": {
+    "message": "随心定制"
+  },
+  "onboarding_step4Explain": {
+    "message": "您可以随时添加或编辑命令"
+  },
+  "onboarding_step4SettingsHeading": {
+    "message": "在设置中创建与编辑"
+  },
+  "onboarding_step4HubHeading": {
+    "message": "在 Selection Command Hub 中发现"
+  },
+  "onboarding_completeTitle": {
+    "message": "一切就绪！"
+  },
+  "onboarding_completeBody": {
+    "message": "Selection Command 已准备就绪。\n选中页面上的任意文本即可开始使用。"
+  },
+  "onboarding_openSettingsButton": {
+    "message": "打开设置"
+  },
+  "onboarding_closeButton": {
+    "message": "关闭并试用"
   }
 }
diff --git a/packages/extension/public/onboarding/HubScreen.png b/packages/extension/public/onboarding/HubScreen.png
new file mode 100644
index 00000000..25621c4b
Binary files /dev/null and b/packages/extension/public/onboarding/HubScreen.png differ
diff --git a/packages/extension/public/onboarding/OptionScreen.png b/packages/extension/public/onboarding/OptionScreen.png
new file mode 100644
index 00000000..89299fbb
Binary files /dev/null and b/packages/extension/public/onboarding/OptionScreen.png differ
diff --git a/packages/extension/src/action/executor.test.ts b/packages/extension/src/action/executor.test.ts
index faf04849..f4fc7e0c 100644
--- a/packages/extension/src/action/executor.test.ts
+++ b/packages/extension/src/action/executor.test.ts
@@ -69,4 +69,63 @@ describe("executeAction", () => {
       }),
     )
   })
+
+  it("skips analytics event when executed from the onboarding page", async () => {
+    const execute = vi.fn().mockResolvedValue("ok")
+    const actions = {
+      [OPEN_MODE.TAB]: { execute },
+    } as Record<string, { execute: () => Promise<string> }>
+
+    await executeAction({
+      actions,
+      command: { id: "cmd-4", openMode: OPEN_MODE.TAB } as any,
+      position: null,
+      selectionText: "text",
+      pageUrl: "chrome-extension://abc123/src/onboarding_page.html",
+    })
+
+    expect(sendEvent).not.toHaveBeenCalled()
+  })
+
+  it("still sends analytics event when executed from another extension page", async () => {
+    const execute = vi.fn().mockResolvedValue("ok")
+    const actions = {
+      [OPEN_MODE.TAB]: { execute },
+    } as Record<string, { execute: () => Promise<string> }>
+
+    await executeAction({
+      actions,
+      command: { id: "cmd-5", openMode: OPEN_MODE.TAB } as any,
+      position: null,
+      selectionText: "text",
+      pageUrl: "chrome-extension://abc123/src/options_page.html",
+    })
+
+    expect(sendEvent).toHaveBeenCalledWith(
+      ANALYTICS_EVENTS.SELECTION_COMMAND,
+      expect.objectContaining({ command_id: "cmd-5" }),
+    )
+  })
+
+  it("dispatches an onboarding:command-executed window event", async () => {
+    const execute = vi.fn().mockResolvedValue("ok")
+    const actions = {
+      [OPEN_MODE.TAB]: { execute },
+    } as Record<string, { execute: () => Promise<string> }>
+    const dispatchSpy = vi.spyOn(window, "dispatchEvent")
+
+    await executeAction({
+      actions,
+      command: { id: "cmd-3", openMode: OPEN_MODE.TAB } as any,
+      position: null,
+      selectionText: "text",
+    })
+
+    expect(dispatchSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: "onboarding:command-executed",
+        detail: { commandId: "cmd-3", commandType: OPEN_MODE.TAB },
+      }),
+    )
+  })
 })
diff --git a/packages/extension/src/action/executor.ts b/packages/extension/src/action/executor.ts
index 52fcddac..cddabb33 100644
--- a/packages/extension/src/action/executor.ts
+++ b/packages/extension/src/action/executor.ts
@@ -2,6 +2,10 @@ import type { ExecuteCommandParams } from "@/types"
 import { OPEN_MODE } from "@/const"
 import { sendEvent, ANALYTICS_EVENTS } from "@/services/analytics"
 import { resolveCommandSource } from "@/services/commandSource"
+import {
+  dispatchCommandExecuted,
+  isOnboardingPage,
+} from "@/components/onboarding/onboardingEvents"
 
 export async function executeAction({
   actions,
@@ -36,12 +40,17 @@ export async function executeAction({
 
   const { sourceType, sourceId } = resolveCommandSource(command)
 
-  sendEvent(ANALYTICS_EVENTS.SELECTION_COMMAND, {
-    event_label: mode,
-    command_id: command.id,
-    source_type: sourceType,
-    source_id: sourceId,
-  })
+  // Don't send analytics events for commands executed from within the onboarding flow itself.
+  if (!isOnboardingPage(pageUrl)) {
+    sendEvent(ANALYTICS_EVENTS.SELECTION_COMMAND, {
+      event_label: mode,
+      command_id: command.id,
+      source_type: sourceType,
+      source_id: sourceId,
+    })
+  }
+
+  dispatchCommandExecuted({ commandId: command.id, commandType: mode })
 
   return res
 }
diff --git a/packages/extension/src/background_script.test.ts b/packages/extension/src/background_script.test.ts
index 8d0d4a86..8384d7ba 100644
--- a/packages/extension/src/background_script.test.ts
+++ b/packages/extension/src/background_script.test.ts
@@ -622,6 +622,52 @@ describe("onInstalled: installed analytics event", () => {
       expect.anything(),
     )
   })
+
+  it("IN-03: opens the onboarding page tab when reason is install", async () => {
+    vi.doMock("@/services/analytics", () => ({
+      ANALYTICS_EVENTS: { INSTALLED: "installed" },
+      sendEvent: vi.fn(),
+      getOrCreateClientId: vi.fn().mockResolvedValue("test-client-id"),
+    }))
+
+    vi.resetModules()
+    await import("./background_script")
+
+    const listenerCalls = (chrome.runtime.onInstalled.addListener as any).mock
+      .calls
+    const onInstalledListener = listenerCalls[0][0]
+
+    await onInstalledListener({
+      reason: chrome.runtime.OnInstalledReason.INSTALL,
+    })
+
+    expect(chrome.tabs.create).toHaveBeenCalledWith({
+      url: "src/onboarding_page.html",
+    })
+  })
+
+  it("IN-04: does not open the onboarding page tab when reason is update", async () => {
+    vi.doMock("@/services/analytics", () => ({
+      ANALYTICS_EVENTS: { INSTALLED: "installed" },
+      sendEvent: vi.fn(),
+      getOrCreateClientId: vi.fn().mockResolvedValue("test-client-id"),
+    }))
+
+    vi.resetModules()
+    await import("./background_script")
+
+    const listenerCalls = (chrome.runtime.onInstalled.addListener as any).mock
+      .calls
+    const onInstalledListener = listenerCalls[0][0]
+
+    await onInstalledListener({
+      reason: chrome.runtime.OnInstalledReason.UPDATE,
+    })
+
+    expect(chrome.tabs.create).not.toHaveBeenCalledWith(
+      expect.objectContaining({ url: "src/onboarding_page.html" }),
+    )
+  })
 })
 
 describe("Uninstall URL (onInstalled)", () => {
diff --git a/packages/extension/src/background_script.ts b/packages/extension/src/background_script.ts
index 6994bbfa..2f0c52b1 100644
--- a/packages/extension/src/background_script.ts
+++ b/packages/extension/src/background_script.ts
@@ -1,6 +1,7 @@
 import {
   isDebug,
   OPTION_PAGE_PATH,
+  ONBOARDING_PAGE_PATH,
   SHORTCUT_NO_SELECTION_BEHAVIOR,
   NEW_HUB_URL,
   SCREEN,
@@ -58,6 +59,30 @@ const getActiveTabId = (
   return true
 }
 
+// Closes the sender's own tab. Routed through the background script (rather
+// than the page calling chrome.tabs.remove() on itself) since a page closing
+// its own tab is the more robust pattern - it keeps tab lifecycle decisions
+// in one place alongside the rest of the extension's tab management.
+//
+// Responds *before* removing the tab, not after: the sender is awaiting this
+// response in the very tab we're about to close, so if the response only
+// arrived once chrome.tabs.remove() had resolved, that await would be racing
+// its own tab's teardown. Acknowledging first lets the sender's promise
+// settle cleanly while its tab is still fully alive; the removal itself
+// follows as a fire-and-forget side effect.
+const closeTab = (
+  _: unknown,
+  sender: Sender,
+  response: (res: unknown) => void,
+) => {
+  const tabId = sender.tab?.id
+  response(tabId != null)
+  if (tabId != null) {
+    chrome.tabs.remove(tabId)
+  }
+  return false
+}
+
 const onConnect = async function (port: chrome.runtime.Port) {
   if (port.name !== CONNECTION_APP) return
   port.onDisconnect.addListener(() => onDisconnect(port))
@@ -287,6 +312,7 @@ const commandFuncs = {
 
   [BgCommand.getTabId]: getTabId,
   [BgCommand.getActiveTabId]: getActiveTabId,
+  [BgCommand.closeTab]: closeTab,
 
   //
   // Hub
@@ -445,6 +471,7 @@ chrome.runtime.onInstalled.addListener(async (details) => {
     if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
       await Settings.reset()
       sendEvent(ANALYTICS_EVENTS.INSTALLED, {}, SCREEN.SERVICE_WORKER)
+      chrome.tabs.create({ url: ONBOARDING_PAGE_PATH })
     }
 
     await ContextMenu.init()
diff --git a/packages/extension/src/components/App.tsx b/packages/extension/src/components/App.tsx
index c71f54e3..5afe96c6 100644
--- a/packages/extension/src/components/App.tsx
+++ b/packages/extension/src/components/App.tsx
@@ -26,7 +26,6 @@ type Props = {
 
 export function App({ rootElm }: Props) {
   const [positionElm, setPositionElm] = useState<Element | null>(null)
-  const [isHover, setIsHover] = useState<boolean>(false)
 
   useEffect(() => {
     const handleShowToast = (
@@ -72,12 +71,9 @@ export function App({ rootElm }: Props) {
   return (
     <TabContextProvider>
       <PageActionContextProvider>
-        <SelectContextProvider isPopupHover={isHover}>
+        <SelectContextProvider>
           <SelectAnchor ref={setPositionElm} />
-          <Popup
-            positionElm={positionElm}
-            onHover={(v: boolean) => setIsHover(v)}
-          />
+          <Popup positionElm={positionElm} />
           <InvisibleItem positionElm={positionElm} />
           <LinkSelector />
           <OpenInTab />
diff --git a/packages/extension/src/components/Popup.tsx b/packages/extension/src/components/Popup.tsx
index 247aa1a3..18ac857f 100644
--- a/packages/extension/src/components/Popup.tsx
+++ b/packages/extension/src/components/Popup.tsx
@@ -1,4 +1,4 @@
-import { useState, useEffect, createContext, forwardRef } from "react"
+import { useState, useEffect, forwardRef } from "react"
 import { Popover, PopoverContent, PopoverAnchor } from "@/components/ui/popover"
 import { Menu } from "@/components/menu/Menu"
 import { useUserSettings } from "@/hooks/useSettings"
@@ -6,6 +6,8 @@ import { useDetectStartup } from "@/hooks/useDetectStartup"
 import { useTabCommandReceiver } from "@/hooks/useTabCommandReceiver"
 import { useSidePanelNavigation } from "@/hooks/useSidePanelNavigation"
 import { useSidePanelAutoClose } from "@/hooks/useSidePanelAutoClose"
+import { useSelectContext } from "@/hooks/useSelectContext"
+import { popupContext } from "@/hooks/usePopupContext"
 import { hexToHsl, isMac, onHover, cn } from "@/lib/utils"
 import { t } from "@/services/i18n"
 import { STYLE_VARIABLE, EXIT_DURATION, SIDE, ALIGN } from "@/const"
@@ -15,17 +17,9 @@ import css from "./Popup.module.css"
 export type PopupProps = {
   positionElm: Element | null
   isPreview?: boolean
-  onHover?: (hover: boolean) => void
+  inOnboarding?: boolean
 }
 
-type ContextType = {
-  isPreview?: boolean
-  inTransition?: boolean
-  side: SIDE
-  align: ALIGN
-}
-export const popupContext = createContext<ContextType>({} as ContextType)
-
 export const Popup = forwardRef<HTMLDivElement, PopupProps>(
   (props: PopupProps, ref) => {
     useTabCommandReceiver()
@@ -33,6 +27,8 @@ export const Popup = forwardRef<HTMLDivElement, PopupProps>(
     useSidePanelAutoClose()
 
     const { userSettings } = useUserSettings()
+    const { setDetectSelectionEnabled } = useSelectContext()
+
     const [inTransition, setInTransition] = useState(false)
     const [shouldRender, setShouldRender] = useState(false)
     const [isHover, setIsHover] = useState(false)
@@ -40,6 +36,7 @@ export const Popup = forwardRef<HTMLDivElement, PopupProps>(
       ...props,
       isHover,
     })
+
     const isPreview = props.isPreview === true
     const placement = userSettings?.popupPlacement
     const side = isPreview ? SIDE.bottom : (placement?.side ?? SIDE.top)
@@ -100,15 +97,29 @@ export const Popup = forwardRef<HTMLDivElement, PopupProps>(
         clearTimeout(transitionTimer)
         clearTimeout(delayTimer)
       }
-    }, [visible])
+    }, [visible, userSettings?.userStyles])
+
+    useEffect(() => {
+      if (!visible || props.positionElm == null) {
+        setDetectSelectionEnabled(true)
+      }
+    }, [visible, props.positionElm, setDetectSelectionEnabled])
 
     const handleOnHover = (hover: boolean) => {
       setIsHover(hover)
-      props.onHover?.(hover)
+      setDetectSelectionEnabled(!hover)
     }
 
     return (
-      <popupContext.Provider value={{ isPreview, inTransition, side, align }}>
+      <popupContext.Provider
+        value={{
+          isPreview,
+          inTransition,
+          inOnboarding: props.inOnboarding,
+          side,
+          align,
+        }}
+      >
         {isPreview && <PreviewDesc {...props} />}
         <Popover open={visible}>
           <PopoverAnchor virtualRef={{ current: props.positionElm }} />
diff --git a/packages/extension/src/components/Tooltip.tsx b/packages/extension/src/components/Tooltip.tsx
index a4473a43..0dee55da 100644
--- a/packages/extension/src/components/Tooltip.tsx
+++ b/packages/extension/src/components/Tooltip.tsx
@@ -1,4 +1,4 @@
-import { useContext, useEffect, useState } from "react"
+import { useEffect, useState } from "react"
 import clsx from "clsx"
 import {
   Popover,
@@ -6,7 +6,7 @@ import {
   PopoverAnchor,
   PopoverArrow,
 } from "@/components/ui/popover"
-import { popupContext } from "@/components/Popup"
+import { usePopupContext } from "@/hooks/usePopupContext"
 import { SIDE } from "@/const"
 
 type PopupProps = {
@@ -18,7 +18,7 @@ type PopupProps = {
 }
 
 export function Tooltip(props: PopupProps) {
-  const { side } = useContext(popupContext)
+  const { side, inTransition, inOnboarding } = usePopupContext()
   const delay = props.delay ?? 300
   const [isOpen, setIsOpen] = useState(false)
   const [shouldRender, setShouldRender] = useState(false)
@@ -51,7 +51,7 @@ export function Tooltip(props: PopupProps) {
     return () => clearTimeout(timer)
   }, [isOpen, delay])
 
-  if (props.disabled || !elm) {
+  if (inTransition || inOnboarding || props.disabled || !elm) {
     return null
   }
 
@@ -61,7 +61,7 @@ export function Tooltip(props: PopupProps) {
       {shouldRender && (
         <PopoverContent
           className={clsx(
-            "bg-gray-800 min-w-4 bg-gray-800 px-2 py-1.5 shadow-md",
+            "bg-gray-800 min-w-4 px-2 py-1.5 shadow-md",
             props.className,
           )}
           side={side === SIDE.bottom ? SIDE.bottom : "top"}
diff --git a/packages/extension/src/components/menu/MenuFolder.tsx b/packages/extension/src/components/menu/MenuFolder.tsx
index 35b97482..e4665852 100644
--- a/packages/extension/src/components/menu/MenuFolder.tsx
+++ b/packages/extension/src/components/menu/MenuFolder.tsx
@@ -1,4 +1,4 @@
-import React, { useState, useRef, useContext, useLayoutEffect } from "react"
+import React, { useState, useRef, useLayoutEffect } from "react"
 import { Popover, PopoverContent, PopoverAnchor } from "@/components/ui/popover"
 import { ScrollAreaConditional } from "@/components/ui/scroll-area"
 
@@ -7,7 +7,7 @@ import { MenuItem } from "./MenuItem"
 import { ChevronRight } from "lucide-react"
 import { HoverArea } from "@/components/menu/HoverArea"
 import { MenuImage } from "@/components/menu/MenuImage"
-import { popupContext } from "@/components/Popup"
+import { usePopupContext } from "@/hooks/usePopupContext"
 import css from "./Menu.module.css"
 import type { Command, CommandFolder } from "@/types"
 import { cn, onHover } from "@/lib/utils"
@@ -77,7 +77,7 @@ export const MenuFolder = (props: {
   const [triggeredFolder, setTriggeredFolder] = useState("")
   const [hoveredFolder, setHoveredFolder] = useState("")
   const childActiveFolder = triggeredFolder || hoveredFolder
-  const { inTransition } = useContext(popupContext)
+  const { inTransition } = usePopupContext()
 
   // Resolve the effective style for this folder's content.
   // INHERIT: use parent style (isHorizontal), otherwise use folder's explicit style setting.
diff --git a/packages/extension/src/components/menu/MenuItem.tsx b/packages/extension/src/components/menu/MenuItem.tsx
index 070acba1..b48e3288 100644
--- a/packages/extension/src/components/menu/MenuItem.tsx
+++ b/packages/extension/src/components/menu/MenuItem.tsx
@@ -1,12 +1,13 @@
-import React, { useRef, useContext } from "react"
+import React, { useRef } from "react"
 import clsx from "clsx"
-import { popupContext } from "@/components/Popup"
+import { usePopupContext } from "@/hooks/usePopupContext"
 import { Tooltip } from "../Tooltip"
 import { RefreshCw, Check, AlertCircle } from "lucide-react"
 import { ResultPopup } from "@/components/result/ResultPopup"
 import { useSelectContext } from "@/hooks/useSelectContext"
 import { useCommandExecutor } from "@/hooks/useCommandExecutor"
 import { getCommandEnabled } from "@/lib/commandEnabled"
+import { PopupOption } from "@/services/option/defaultSettings"
 import { ExecState } from "@/const"
 import type { Command } from "@/types"
 
@@ -24,8 +25,8 @@ export function MenuItem(props: MenuItemProps): React.ReactNode {
     useCommandExecutor()
   const onlyIcon = props.onlyIcon
   const { iconUrl, title } = props.command
+  const { isPreview, inTransition, inOnboarding } = usePopupContext()
   const { selectionText, target } = useSelectContext()
-  const { isPreview, inTransition } = useContext(popupContext)
   const { enabled, message: defaultMessage } = getCommandEnabled(props.command)
   const message = itemState.message || defaultMessage
 
@@ -38,11 +39,22 @@ export function MenuItem(props: MenuItemProps): React.ReactNode {
     }
 
     const rect = props.menuRef.current.getBoundingClientRect()
+    let position = { x: rect.right + 10, y: rect.top }
+
+    // During onboarding, align to the right edge so the on-screen explanation stays visible.
+    if (inOnboarding) {
+      const innerWidth = window.innerWidth
+      const x1 = innerWidth / 2 + 620 / 2 //  width of the explanation box
+      const screenWidth = window.screen.width
+      const x2 = screenWidth - PopupOption.width - 20
+      position = { x: Math.min(x1, x2), y: rect.top }
+    }
+
     const useSecondary = e.metaKey || e.ctrlKey
 
     executeCommand({
       command: props.command,
-      position: { x: rect.right + 10, y: rect.top },
+      position,
       selectionText,
       target,
       useSecondary,
@@ -66,6 +78,7 @@ export function MenuItem(props: MenuItemProps): React.ReactNode {
         )}
         role="menuitem"
         aria-label={title}
+        data-command-id={props.command.id}
         ref={buttonRef}
         onClick={handleClick}
         disabled={!enabled}
@@ -76,7 +89,7 @@ export function MenuItem(props: MenuItemProps): React.ReactNode {
       <Tooltip
         text={message}
         positionElm={buttonRef.current}
-        disabled={inTransition || (!onlyIcon && enabled)}
+        disabled={!onlyIcon && enabled}
       />
       <ResultPopup
         visible={result != null}
diff --git a/packages/extension/src/components/onboarding/OnboardingCallout.tsx b/packages/extension/src/components/onboarding/OnboardingCallout.tsx
new file mode 100644
index 00000000..018f4f33
--- /dev/null
+++ b/packages/extension/src/components/onboarding/OnboardingCallout.tsx
@@ -0,0 +1,81 @@
+import { ReactNode, useEffect, useState } from "react"
+import {
+  Popover,
+  PopoverContent,
+  PopoverAnchor,
+  PopoverArrow,
+} from "@/components/ui/popover"
+import { cn } from "@/lib/utils"
+import { SIDE, ALIGN } from "@/const"
+
+type Props = {
+  // The element the callout should point at (e.g. a specific command button
+  // found via `[data-command-id]`, see MenuItem.tsx).
+  targetElm: Element | null
+  open: boolean
+  // Delay (ms) before the callout actually appears once `open` becomes
+  // true, so it doesn't flash in immediately alongside the thing it's
+  // pointing at. Hiding (`open` -> false) is always immediate.
+  openDelay?: number
+  // Extra classes merged onto the popover content, e.g. to override the
+  // default enter-animation duration for a specific caller.
+  contentClassName?: string
+  side?: SIDE
+  align?: ALIGN
+  children: ReactNode
+}
+
+// A speech-bubble style callout anchored to an arbitrary DOM element,
+// externally controlled via `open` (unlike Tooltip.tsx, which is
+// hover-triggered and used throughout the regular popup menu - reusing it
+// here would risk regressing that shared, frequently-exercised component).
+export function OnboardingCallout({
+  targetElm,
+  open,
+  openDelay = 0,
+  contentClassName,
+  side = SIDE.top,
+  align = ALIGN.center,
+  children,
+}: Props) {
+  const [shown, setShown] = useState(false)
+
+  useEffect(() => {
+    if (!open) {
+      setShown(false)
+      return
+    }
+    if (openDelay <= 0) {
+      setShown(true)
+      return
+    }
+    const timer = window.setTimeout(() => setShown(true), openDelay)
+    return () => window.clearTimeout(timer)
+  }, [open, openDelay])
+
+  if (!targetElm) return null
+
+  return (
+    <Popover open={shown}>
+      <PopoverAnchor virtualRef={{ current: targetElm }} />
+      {shown && (
+        <PopoverContent
+          side={side}
+          align={align}
+          sideOffset={10}
+          className={cn(contentClassName, "shadow-none")}
+        >
+          <div className="animate-onboarding-float motion-reduce:animate-none max-w-64 rounded-md bg-gray-800 px-3 py-2 shadow-xl">
+            <div className="text-sm text-white whitespace-pre-wrap">
+              {children}
+            </div>
+          </div>
+          <PopoverArrow
+            className="fill-gray-800 animate-onboarding-float motion-reduce:animate-none shadow-xl"
+            height={6}
+          />
+        </PopoverContent>
+      )}
+    </Popover>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/OnboardingConfetti.tsx b/packages/extension/src/components/onboarding/OnboardingConfetti.tsx
new file mode 100644
index 00000000..286c1efc
--- /dev/null
+++ b/packages/extension/src/components/onboarding/OnboardingConfetti.tsx
@@ -0,0 +1,87 @@
+import { useEffect, useRef } from "react"
+import confetti from "canvas-confetti"
+import { usePrefersReducedMotion } from "@/hooks/usePrefersReducedMotion"
+
+const COLORS = [
+  "#082f49",
+  "#0284c7",
+  "#7dd3fc",
+  "#f59e0b",
+  "#cbd5e1",
+  "#dc2626",
+  "#ef4444",
+]
+
+// Step5's one-shot celebration burst. Fires once on mount and never loops -
+// see the onboarding motion spec's "one thing moves at a time" rule; a
+// looping confetti field would compete with the checkmark/heading fade-in.
+//
+// `useWorker: false` is required under the extension pages' MV3 CSP
+// (script-src 'self'): canvas-confetti defaults to rendering in a blob-URL
+// web worker, which that CSP blocks.
+//
+// Gating is done with our own usePrefersReducedMotion() rather than
+// canvas-confetti's built-in `disableForReducedMotion` option: that option
+// checks `matchMedia('(prefers-reduced-motion)')` with no value, which
+// matches whenever the browser merely *supports* the media feature - true
+// in effectively every modern browser - so it silently disables confetti
+// unconditionally rather than honoring the user's actual OS setting.
+export function OnboardingConfetti() {
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const prefersReducedMotion = usePrefersReducedMotion()
+
+  useEffect(() => {
+    const canvas = canvasRef.current
+    if (!canvas || prefersReducedMotion) return
+
+    const instance = confetti.create(canvas, {
+      resize: true,
+      useWorker: false,
+    })
+
+    // Delay the burst slightly so it doesn't fire before the page has
+    // finished painting (avoids the first frames being dropped/invisible).
+    const timer = setTimeout(() => {
+      // angle: 270 shoots particles downward (canvas-confetti's angle 90,
+      // the default, shoots UP - a fountain/firework burst - which combined
+      // with origin.y near/above 0 sends everything off the top of the
+      // canvas and it never becomes visible). origin.y: 0 starts them right
+      // at the top edge so the fall reads immediately.
+      //
+      // ticks: 200 keeps particles alive long enough to reach the bottom
+      // of the viewport instead of being culled mid-fall.
+      instance({
+        particleCount: 120,
+        spread: 160,
+        angle: 270,
+        startVelocity: 35,
+        gravity: 0.8,
+        ticks: 200,
+        origin: { x: 0.5, y: 0 },
+        colors: COLORS,
+      })
+    }, 600)
+
+    return () => {
+      clearTimeout(timer)
+      instance.reset()
+    }
+  }, [prefersReducedMotion])
+
+  if (prefersReducedMotion) return null
+
+  return (
+    <canvas
+      ref={canvasRef}
+      aria-hidden
+      // `w-full h-full` are load-bearing, not decorative: <canvas> is a
+      // replaced element, so `inset-0` alone leaves its CSS box at the
+      // element's intrinsic 300x150 default (absolutely-positioned replaced
+      // elements size from their intrinsic dimensions, not from inset
+      // constraints, per CSS2.1 10.6.5) - canvas-confetti's `resize: true`
+      // then reads that tiny box via getBoundingClientRect() and everything
+      // renders squeezed into the top-left corner.
+      className="pointer-events-none fixed inset-0 z-20 size-full !h-full"
+    />
+  )
+}
diff --git a/packages/extension/src/components/onboarding/OnboardingFadeIn.tsx b/packages/extension/src/components/onboarding/OnboardingFadeIn.tsx
new file mode 100644
index 00000000..b48a30a7
--- /dev/null
+++ b/packages/extension/src/components/onboarding/OnboardingFadeIn.tsx
@@ -0,0 +1,26 @@
+import { ReactNode } from "react"
+import clsx from "clsx"
+
+type Props = {
+  children: ReactNode
+  className?: string
+  delay?: number // in milliseconds; optional delay before the fade-in starts
+}
+
+// Wraps a block of onboarding explanation text so it fades in from slightly
+// below, per the PRD's "説明テキストは少し下からフェードイン" rule. Uses a
+// `key`-less CSS animation (re-triggered by React remounting the element,
+// e.g. when the step/phase changes) rather than a JS animation library.
+export function OnboardingFadeIn({ children, className, delay }: Props) {
+  return (
+    <div
+      className={clsx(
+        "motion-reduce:animate-none animate-onboarding-rise",
+        className,
+      )}
+      style={{ animationDelay: delay ? `${delay}ms` : undefined }}
+    >
+      {children}
+    </div>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/OnboardingLayout.tsx b/packages/extension/src/components/onboarding/OnboardingLayout.tsx
new file mode 100644
index 00000000..26b29743
--- /dev/null
+++ b/packages/extension/src/components/onboarding/OnboardingLayout.tsx
@@ -0,0 +1,75 @@
+import { ReactNode } from "react"
+import { t } from "@/services/i18n"
+import { getProgress, showsSkip } from "./onboardingProgress"
+import type { OnboardingStep } from "@/types/onboarding"
+
+const ICON_URL = chrome.runtime.getURL("SelectionCommandLogo.png")
+
+type Props = {
+  step: OnboardingStep
+  onSkip: () => void
+  children: ReactNode
+}
+
+// Shared chrome around every onboarding step: a constant-strength vignette
+// (unlike the old per-step OnboardingOverlay spotlight, this never changes
+// between screens, so nothing about the background shifts on transition),
+// a header with the brand mark and a 4-segment progress indicator, and a
+// Skip button fixed to the bottom-right corner. Individual step components
+// now render only their own content.
+export function OnboardingLayout({ step, onSkip, children }: Props) {
+  const progress = getProgress(step)
+
+  return (
+    <div className="relative flex min-h-screen flex-col overflow-hidden bg-white">
+      <div
+        aria-hidden
+        className="pointer-events-none absolute inset-0 z-0 bg-[radial-gradient(56%_50%_at_50%_50%,rgba(15,23,42,0)_0%,rgba(15,23,42,0)_52%,rgba(15,23,42,0.12)_100%)]"
+      />
+
+      <div className="relative z-10 flex items-center justify-between px-10 py-5">
+        {progress && (
+          <img
+            src={ICON_URL}
+            className="block h-7"
+            alt="Logo of selection command"
+            aria-hidden
+          />
+        )}
+        {progress && (
+          <div className="flex items-center gap-3.5 select-none">
+            <div className="flex gap-1.5">
+              {progress.pills.map((pill, i) => (
+                <span
+                  key={i}
+                  className={
+                    pill === "todo"
+                      ? "h-1 w-[26px] rounded-full bg-slate-100"
+                      : "h-1 w-[26px] rounded-full bg-sky-950"
+                  }
+                />
+              ))}
+            </div>
+            <span className="text-xs font-bold tracking-wide text-slate-500 [font-variant-numeric:tabular-nums]">
+              {progress.current} / {progress.total}
+            </span>
+          </div>
+        )}
+      </div>
+
+      <div className="relative z-10 flex flex-1 flex-col items-center justify-center px-10 text-center [&>*]:h-[400px]">
+        {children}
+      </div>
+
+      {showsSkip(step) && (
+        <button
+          type="button"
+          onClick={onSkip}
+          className="absolute right-[30px] bottom-6 z-20 inline-flex min-h-11 items-center rounded-md px-3.5 text-sm font-medium text-slate-600 hover:bg-slate-100/80 hover:text-slate-700"
+        >
+          {t("onboarding_skipButton")}
+        </button>
+      )}
+    </div>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/OnboardingPage.tsx b/packages/extension/src/components/onboarding/OnboardingPage.tsx
new file mode 100644
index 00000000..fa68c51d
--- /dev/null
+++ b/packages/extension/src/components/onboarding/OnboardingPage.tsx
@@ -0,0 +1,50 @@
+import { useState } from "react"
+import { SelectContextProvider } from "@/providers/SelectContextProvider"
+import { SelectAnchor } from "@/components/SelectAnchor"
+import { Popup } from "@/components/Popup"
+import { LinkSelector } from "@/components/LinkSelector"
+import { useOnboardingState } from "./useOnboardingState"
+import { OnboardingLayout } from "./OnboardingLayout"
+import { StepIntro } from "./steps/StepIntro"
+import { StepSearchCommand } from "./steps/StepSearchCommand"
+import { StepAiPromptCommand } from "./steps/StepAiPromptCommand"
+import { StepLinkPreview } from "./steps/StepLinkPreview"
+import { StepCustomize } from "./steps/StepCustomize"
+import { StepComplete } from "./steps/StepComplete"
+import { OnboardingStep } from "@/types/onboarding"
+
+import "@/components/App.css"
+
+export function OnboardingPage() {
+  const onboarding = useOnboardingState()
+  const [positionElm, setPositionElm] = useState<Element | null>(null)
+
+  return (
+    <SelectContextProvider>
+      <OnboardingLayout step={onboarding.step} onSkip={onboarding.skip}>
+        {onboarding.step === OnboardingStep.INTRO && (
+          <StepIntro onboarding={onboarding} />
+        )}
+        {onboarding.step === OnboardingStep.SEARCH && (
+          <StepSearchCommand onboarding={onboarding} />
+        )}
+        {onboarding.step === OnboardingStep.AI_PROMPT && (
+          <StepAiPromptCommand onboarding={onboarding} />
+        )}
+        {onboarding.step === OnboardingStep.LINK_PREVIEW && (
+          <StepLinkPreview onboarding={onboarding} />
+        )}
+        {onboarding.step === OnboardingStep.CUSTOMIZE && (
+          <StepCustomize onboarding={onboarding} />
+        )}
+        {onboarding.step === OnboardingStep.COMPLETE && (
+          <StepComplete onboarding={onboarding} />
+        )}
+      </OnboardingLayout>
+
+      <SelectAnchor ref={setPositionElm} />
+      <Popup positionElm={positionElm} inOnboarding={true} />
+      <LinkSelector />
+    </SelectContextProvider>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/OnboardingRail.tsx b/packages/extension/src/components/onboarding/OnboardingRail.tsx
new file mode 100644
index 00000000..f87bda83
--- /dev/null
+++ b/packages/extension/src/components/onboarding/OnboardingRail.tsx
@@ -0,0 +1,110 @@
+import { Check, ChevronsRight } from "lucide-react"
+import { cn } from "@/lib/utils"
+
+// Reinforces the PRD's "select -> command -> result" mental model
+// (https://github.com/ujiro99/selection-command/issues/452, section 6-2) as
+// a persistent visual on Steps 1-3, replacing the plain uppercase caption
+// text from the first cut. `activeBeat` is the 0-based index of the beat
+// the current step is on (0 = selecting, 1 = running a command, 2 = seeing
+// the result); beats before it render as done, after it as upcoming.
+// Passing -1 renders all three beats as done, for the value-shown payoff
+// screens where all three actions already happened.
+type Props = {
+  selectLabel: string
+  commandLabel: string
+  resultLabel: string
+  activeBeat: 0 | 1 | 2 | -1
+  // "sm" (default) is the compact form shown inline while a step is in
+  // progress; "lg" is the larger, staggered-reveal form used on the
+  // value-shown payoff screens.
+  size?: "sm" | "lg"
+}
+
+type BeatState = "done" | "current" | "todo"
+
+function beatState(index: number, activeBeat: Props["activeBeat"]): BeatState {
+  if (activeBeat === -1 || index < activeBeat) return "done"
+  return index === activeBeat ? "current" : "todo"
+}
+
+export function OnboardingRail({
+  selectLabel,
+  commandLabel,
+  resultLabel,
+  activeBeat,
+  size = "sm",
+}: Props) {
+  const beats = [selectLabel, commandLabel, resultLabel]
+  const lg = size === "lg"
+
+  return (
+    <div
+      className={cn(
+        "flex items-center",
+        lg ? "gap-3 rounded-lg px-[26px] py-4" : "gap-2.5",
+      )}
+    >
+      {beats.map((label, i) => {
+        const state = beatState(i, activeBeat)
+        // The chevron before beat i is "walked" once the beat to its left
+        // (i - 1) is done.
+        const chevronWalked = i > 0 && beatState(i - 1, activeBeat) === "done"
+        // Each beat/chevron fades in a beat later than the last, so the
+        // sequence reads left-to-right - only used for the "lg" celebratory
+        // rail; the compact "sm" rail appears with the step's own fade-in.
+        const delayMs = lg ? 60 + i * 140 : 0
+
+        return (
+          <div key={label} className="contents">
+            {i > 0 && (
+              <ChevronsRight
+                className={cn(
+                  lg ? "size-[18px]" : "size-3.5",
+                  chevronWalked ? "text-sky-950" : "text-slate-300",
+                  lg && "animate-onboarding-rise motion-reduce:animate-none",
+                )}
+                style={lg ? { animationDelay: `${delayMs}ms` } : undefined}
+                strokeWidth={3}
+              />
+            )}
+            <div
+              className={cn(
+                "flex items-center font-semibold tracking-wide text-slate-500",
+                lg ? "gap-2.5 text-[13px]" : "gap-1.5 text-xs",
+                lg && "animate-onboarding-rise motion-reduce:animate-none",
+              )}
+              style={lg ? { animationDelay: `${delayMs}ms` } : undefined}
+            >
+              <span
+                className={cn(
+                  "flex items-center justify-center rounded-full",
+                  lg ? "size-6" : "size-[18px]",
+                  state === "todo"
+                    ? "bg-slate-200"
+                    : state === "done"
+                      ? "bg-blue-200 text-blue-800"
+                      : "bg-sky-950/[0.14] text-sky-950",
+                )}
+              >
+                {state === "done" && (
+                  <Check
+                    className={lg ? "size-3" : "size-2.5"}
+                    strokeWidth={3.2}
+                  />
+                )}
+                {state === "current" && (
+                  <span className="size-2.5 rounded-full bg-sky-950 inline-block">
+                    <span className="w-full h-full rounded-full bg-sky-950 block animate-ping opacity-70" />
+                  </span>
+                )}
+              </span>
+              <span className={state === "todo" ? "" : "text-sky-950"}>
+                {label}
+              </span>
+            </div>
+          </div>
+        )
+      })}
+    </div>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/OnboardingTargetText.tsx b/packages/extension/src/components/onboarding/OnboardingTargetText.tsx
new file mode 100644
index 00000000..1498be75
--- /dev/null
+++ b/packages/extension/src/components/onboarding/OnboardingTargetText.tsx
@@ -0,0 +1,90 @@
+import { useRef, useState } from "react"
+import { TextCursor } from "lucide-react"
+import { t } from "@/services/i18n"
+import { cn, isEmpty } from "@/lib/utils"
+import { usePrefersReducedMotion } from "@/hooks/usePrefersReducedMotion"
+import { useSelectContext } from "@/hooks/useSelectContext"
+import { useSelectionDemo } from "./useSelectionDemo"
+import { OnboardingCallout } from "./OnboardingCallout"
+
+type Props = {
+  text: string
+  // True once the user has actually selected the text (any later phase),
+  // rendering it as a static, already-selected highlight instead.
+  selected: boolean
+  // Delay (ms) before the "select this" callout appears. Passed in rather
+  // than hardcoded so callers manage it alongside their other phase-based
+  // delays (see each step's `delays` object).
+  calloutDelay?: number
+}
+
+// The sample text card shown on Steps 1-2. Demonstrates the "drag to
+// select" gesture on a loop via useSelectionDemo(), and points an
+// OnboardingCallout at the card while nothing is selected - matching every
+// other "do this next" hint in the onboarding flow (see OnboardingCallout)
+// so first-time users recognize this as something to select rather than
+// something to read.
+export function OnboardingTargetText({ text, selected, calloutDelay }: Props) {
+  const prefersReducedMotion = usePrefersReducedMotion()
+  const { selectionText } = useSelectContext()
+  const textRef = useRef<HTMLSpanElement>(null)
+  const cursorRef = useRef<HTMLSpanElement>(null)
+  const [cardElm, setCardElm] = useState<HTMLDivElement | null>(null)
+  // Nothing currently selected -> still prompting the user to select the
+  // sample text. Tracks live selection (not the latched `selected` prop) so
+  // the hint and demo both reappear if the user deselects without running
+  // a command yet.
+  const showSelectHint = isEmpty(selectionText)
+  const runDemo = !prefersReducedMotion && showSelectHint
+
+  useSelectionDemo(textRef, cursorRef, runDemo)
+
+  return (
+    <div className="flex flex-col items-center gap-2.5">
+      <div
+        ref={setCardElm}
+        className={cn(
+          "relative max-w-[560px] rounded-lg border px-[26px] py-5 text-left text-base leading-[1.9] text-slate-800 select-text",
+          "border-slate-200 bg-muted/80",
+          !selected &&
+            !runDemo &&
+            "[--onboarding-ring-color:rgba(8,47,73,0.16)] animate-onboarding-ring motion-reduce:animate-none",
+        )}
+      >
+        <span
+          ref={textRef}
+          className={cn(
+            "[box-decoration-break:clone] p-1",
+            // `runDemo` is already false when prefers-reduced-motion is on
+            // (see usePrefersReducedMotion() above), so no motion-reduce:
+            // variant is needed here.
+            runDemo && "animate-onboarding-highlight rounded-sm",
+          )}
+        >
+          {text}
+        </span>
+
+        {runDemo && (
+          <span
+            ref={cursorRef}
+            aria-hidden
+            className="pointer-events-none absolute top-0 left-0 select-none text-slate-900 opacity-0 [filter:drop-shadow(0_0_2px_#fff)_drop-shadow(0_1px_3px_rgba(15,23,42,.35))]"
+          >
+            <TextCursor className="size-[18px]" strokeWidth={2} />
+          </span>
+        )}
+      </div>
+
+      <OnboardingCallout
+        targetElm={cardElm}
+        open={showSelectHint}
+        openDelay={calloutDelay}
+      >
+        <span className="inline-flex items-center gap-1.5">
+          <TextCursor className="size-3.5" strokeWidth={2} />
+          {t("onboarding_selectHint")}
+        </span>
+      </OnboardingCallout>
+    </div>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/onboardingAnalytics.test.ts b/packages/extension/src/components/onboarding/onboardingAnalytics.test.ts
new file mode 100644
index 00000000..c6257baf
--- /dev/null
+++ b/packages/extension/src/components/onboarding/onboardingAnalytics.test.ts
@@ -0,0 +1,41 @@
+import { describe, it, expect, vi } from "vitest"
+import { OnboardingStep } from "@/types/onboarding"
+import { SCREEN } from "@/const"
+
+const sendEvent = vi.fn()
+vi.mock("@/services/analytics", async () => {
+  const actual = await vi.importActual("@/services/analytics")
+  return {
+    ...actual,
+    sendEvent: (...args: unknown[]) => sendEvent(...args),
+  }
+})
+
+const { sendOnboardingEvent } = await import("./onboardingAnalytics")
+const { ANALYTICS_EVENTS } = await import("@/services/analytics")
+
+describe("sendOnboardingEvent", () => {
+  it("normalizes a numeric OnboardingStep param to its stable string label", () => {
+    sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_VALUE_REACHED, {
+      step: OnboardingStep.AI_PROMPT,
+    })
+
+    expect(sendEvent).toHaveBeenCalledWith(
+      ANALYTICS_EVENTS.ONBOARDING_VALUE_REACHED,
+      { step: "ai_prompt" },
+      SCREEN.ONBOARDING,
+    )
+  })
+
+  it("leaves params without a step field untouched", () => {
+    sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_START, {
+      locale: "en",
+    })
+
+    expect(sendEvent).toHaveBeenCalledWith(
+      ANALYTICS_EVENTS.ONBOARDING_START,
+      { locale: "en" },
+      SCREEN.ONBOARDING,
+    )
+  })
+})
diff --git a/packages/extension/src/components/onboarding/onboardingAnalytics.ts b/packages/extension/src/components/onboarding/onboardingAnalytics.ts
new file mode 100644
index 00000000..1c60af23
--- /dev/null
+++ b/packages/extension/src/components/onboarding/onboardingAnalytics.ts
@@ -0,0 +1,30 @@
+import { sendEvent, ANALYTICS_EVENTS } from "@/services/analytics"
+import { SCREEN } from "@/const"
+import { OnboardingStep } from "@/types/onboarding"
+
+// Stable string labels for GA4's `step` param, so recorded events keep their
+// meaning even if OnboardingStep's numeric enum values ever change.
+const STEP_LABELS: Record<OnboardingStep, string> = {
+  [OnboardingStep.INTRO]: "intro",
+  [OnboardingStep.SEARCH]: "search",
+  [OnboardingStep.AI_PROMPT]: "ai_prompt",
+  [OnboardingStep.LINK_PREVIEW]: "link_preview",
+  [OnboardingStep.CUSTOMIZE]: "customize",
+  [OnboardingStep.COMPLETE]: "complete",
+}
+
+// Thin wrapper so step components never call sendEvent directly - keeps the
+// SCREEN.ONBOARDING tag and event names centralized in one place. Also
+// normalizes a `step` param (passed as the OnboardingStep enum) to its
+// stable string label before sending.
+export function sendOnboardingEvent(
+  name: (typeof ANALYTICS_EVENTS)[keyof typeof ANALYTICS_EVENTS],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  params: any = {},
+) {
+  const normalizedParams =
+    params.step !== undefined
+      ? { ...params, step: STEP_LABELS[params.step as OnboardingStep] }
+      : params
+  sendEvent(name, normalizedParams, SCREEN.ONBOARDING)
+}
diff --git a/packages/extension/src/components/onboarding/onboardingCommand.ts b/packages/extension/src/components/onboarding/onboardingCommand.ts
new file mode 100644
index 00000000..7daf9b32
--- /dev/null
+++ b/packages/extension/src/components/onboarding/onboardingCommand.ts
@@ -0,0 +1,137 @@
+import { OPEN_MODE, POPUP_OPTION } from "@/const"
+import { INSERT, toInsertTemplate } from "@/services/pageAction/insertSymbols"
+import { getAiServicesFallback } from "@/services/aiPromptFallback"
+import type { AiPromptCommand } from "@/types"
+
+const SELECTED_TEXT = toInsertTemplate(INSERT.SELECTED_TEXT)
+
+// The AI service used by the onboarding's AiPrompt command.
+const ONBOARDING_AI_PROMPT_SERVICE_ID = "chatgpt"
+
+// Derive the icon URL from ai-services.json (single source of truth),
+// keyed to the service actually used by aiPromptOption.serviceId below.
+const ONBOARDING_AI_PROMPT_ICON_URL =
+  getAiServicesFallback().find((s) => s.id === ONBOARDING_AI_PROMPT_SERVICE_ID)
+    ?.faviconUrl ?? ""
+
+// Fixed id for the onboarding's AiPrompt command, so the onboarding UI can
+// reliably point a callout at this specific menu button
+// (see MenuItem.tsx's `data-command-id` attribute) regardless of locale.
+export const ONBOARDING_AI_PROMPT_COMMAND_ID =
+  "8b6f2e10-9a44-5c7d-8b3f-2e6a7c1d4f90"
+
+// Creates the AiPrompt command used in Step2 of the onboarding. It is added
+// as a normal, permanent default command (not removed after onboarding
+// finishes) so returning users can keep using it. The prompt simply forwards
+// the selected text, so users can see their selection reflected back
+// immediately without needing to understand prompt engineering.
+export function createOnboardingAiPromptCommand(
+  title: string,
+  prompt: string,
+): AiPromptCommand {
+  return {
+    id: ONBOARDING_AI_PROMPT_COMMAND_ID,
+    revision: 0,
+    title,
+    iconUrl: ONBOARDING_AI_PROMPT_ICON_URL,
+    openMode: OPEN_MODE.AI_PROMPT,
+    aiPromptOption: {
+      serviceId: ONBOARDING_AI_PROMPT_SERVICE_ID,
+      prompt,
+      openMode: OPEN_MODE.SIDE_PANEL,
+    },
+    popupOption: {
+      width: POPUP_OPTION.width,
+      height: POPUP_OPTION.height,
+    },
+  }
+}
+
+// Per-locale title/prompt text for the onboarding AiPrompt command, keyed the
+// same way as defaultSettings.ts's LOCALE_COMMANDS (exact BCP 47 keys such as
+// "pt-br" take priority there over prefix keys such "pt" - both are listed
+// here since their text happens to be identical today but may diverge).
+type OnboardingAiPromptLocaleText = {
+  title: string
+  prompt: string
+}
+
+const ONBOARDING_AI_PROMPT_LOCALES: Record<
+  string,
+  OnboardingAiPromptLocaleText
+> = {
+  en: {
+    title: "Run with AI",
+    prompt: `Please execute the following prompt.\n\n${SELECTED_TEXT}`,
+  },
+  ja: {
+    title: "AIで実行",
+    prompt: `以下のプロンプトを実行してください。\n\n${SELECTED_TEXT}`,
+  },
+  zh: {
+    title: "用AI执行",
+    prompt: `请执行以下提示词。\n\n${SELECTED_TEXT}`,
+  },
+  ko: {
+    title: "AI로 실행",
+    prompt: `다음 프롬프트를 실행해 주세요.\n\n${SELECTED_TEXT}`,
+  },
+  ru: {
+    title: "Выполнить с ИИ",
+    prompt: `Пожалуйста, выполните следующий запрос.\n\n${SELECTED_TEXT}`,
+  },
+  de: {
+    title: "Mit KI ausführen",
+    prompt: `Bitte führen Sie den folgenden Prompt aus.\n\n${SELECTED_TEXT}`,
+  },
+  fr: {
+    title: "Exécuter avec l'IA",
+    prompt: `Veuillez exécuter le prompt suivant.\n\n${SELECTED_TEXT}`,
+  },
+  es: {
+    title: "Ejecutar con IA",
+    prompt: `Por favor, ejecuta el siguiente prompt.\n\n${SELECTED_TEXT}`,
+  },
+  "pt-br": {
+    title: "Executar com IA",
+    prompt: `Por favor, execute o seguinte prompt.\n\n${SELECTED_TEXT}`,
+  },
+  pt: {
+    title: "Executar com IA",
+    prompt: `Por favor, execute o seguinte prompt.\n\n${SELECTED_TEXT}`,
+  },
+  hi: {
+    title: "AI से चलाएं",
+    prompt: `कृपया निम्नलिखित प्रॉम्प्ट को निष्पादित करें।\n\n${SELECTED_TEXT}`,
+  },
+  id: {
+    title: "Jalankan dengan AI",
+    prompt: `Silakan jalankan prompt berikut.\n\n${SELECTED_TEXT}`,
+  },
+  ms: {
+    title: "Jalankan dengan AI",
+    prompt: `Sila jalankan gesaan berikut.\n\n${SELECTED_TEXT}`,
+  },
+  it: {
+    title: "Esegui con l'IA",
+    prompt: `Esegui il seguente prompt.\n\n${SELECTED_TEXT}`,
+  },
+}
+
+// Builds the onboarding AiPrompt command for every supported locale, keyed
+// the same way as ONBOARDING_AI_PROMPT_LOCALES / defaultSettings.ts's
+// LOCALE_COMMANDS. The icon is resolved from ai-services.json based on
+// ONBOARDING_AI_PROMPT_SERVICE_ID, so callers no longer need to supply it.
+export function createOnboardingAiPromptCommands(): Record<
+  string,
+  AiPromptCommand
+> {
+  return Object.fromEntries(
+    Object.entries(ONBOARDING_AI_PROMPT_LOCALES).map(
+      ([locale, { title, prompt }]) => [
+        locale,
+        createOnboardingAiPromptCommand(title, prompt),
+      ],
+    ),
+  )
+}
diff --git a/packages/extension/src/components/onboarding/onboardingEvents.ts b/packages/extension/src/components/onboarding/onboardingEvents.ts
new file mode 100644
index 00000000..70d04b4b
--- /dev/null
+++ b/packages/extension/src/components/onboarding/onboardingEvents.ts
@@ -0,0 +1,50 @@
+import { OPEN_MODE, DRAG_OPEN_MODE, ONBOARDING_PAGE_PATH } from "@/const"
+
+// Fired on `window` whenever a command (menu command or link preview) is
+// executed, regardless of whether the onboarding page is open. This keeps
+// the onboarding step-progression logic decoupled from the core execution
+// code paths (executor.ts / useDetectLinkCommand.ts) - those callers only
+// need to dispatch the event, they don't know or care who's listening.
+export const ONBOARDING_EVENT = {
+  COMMAND_EXECUTED: "onboarding:command-executed",
+} as const
+
+export type OnboardingCommandExecutedDetail = {
+  commandId: string
+  commandType: OPEN_MODE | DRAG_OPEN_MODE
+}
+
+export function dispatchCommandExecuted(
+  detail: OnboardingCommandExecutedDetail,
+): void {
+  // executeAction() (the sole caller) also runs in the service worker
+  // (background.ts), where `window` does not exist. No-op there; the
+  // onboarding page always runs in a normal window context.
+  if (typeof window === "undefined") return
+
+  window.dispatchEvent(
+    new CustomEvent<OnboardingCommandExecutedDetail>(
+      ONBOARDING_EVENT.COMMAND_EXECUTED,
+      { detail },
+    ),
+  )
+}
+
+// Whether the given page URL is the onboarding page, e.g. to skip analytics
+// events for commands executed from within the onboarding flow itself. Only
+// matches the onboarding page specifically (not extension pages in general,
+// such as the options page).
+export function isOnboardingPage(url?: string | null): boolean {
+  return url?.includes(ONBOARDING_PAGE_PATH) ?? false
+}
+
+export function subscribeCommandExecuted(
+  listener: (detail: OnboardingCommandExecutedDetail) => void,
+): () => void {
+  const handler = (e: Event) => {
+    listener((e as CustomEvent<OnboardingCommandExecutedDetail>).detail)
+  }
+  window.addEventListener(ONBOARDING_EVENT.COMMAND_EXECUTED, handler)
+  return () =>
+    window.removeEventListener(ONBOARDING_EVENT.COMMAND_EXECUTED, handler)
+}
diff --git a/packages/extension/src/components/onboarding/onboardingProgress.test.ts b/packages/extension/src/components/onboarding/onboardingProgress.test.ts
new file mode 100644
index 00000000..b97c9116
--- /dev/null
+++ b/packages/extension/src/components/onboarding/onboardingProgress.test.ts
@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest"
+import { getProgress, showsSkip } from "./onboardingProgress"
+import { OnboardingStep } from "@/types/onboarding"
+
+describe("getProgress", () => {
+  it("returns null for the intro bookend", () => {
+    expect(getProgress(OnboardingStep.INTRO)).toBeNull()
+  })
+
+  it("returns null for the complete bookend", () => {
+    expect(getProgress(OnboardingStep.COMPLETE)).toBeNull()
+  })
+
+  it("marks the first tracked step as current with the rest todo", () => {
+    expect(getProgress(OnboardingStep.SEARCH)).toEqual({
+      pills: ["current", "todo", "todo", "todo"],
+      current: 1,
+      total: 4,
+    })
+  })
+
+  it("marks earlier steps done and later steps todo", () => {
+    expect(getProgress(OnboardingStep.LINK_PREVIEW)).toEqual({
+      pills: ["done", "done", "current", "todo"],
+      current: 3,
+      total: 4,
+    })
+  })
+
+  it("marks the last tracked step as current with none todo", () => {
+    expect(getProgress(OnboardingStep.CUSTOMIZE)).toEqual({
+      pills: ["done", "done", "done", "current"],
+      current: 4,
+      total: 4,
+    })
+  })
+})
+
+describe("showsSkip", () => {
+  it("is true for every step except COMPLETE", () => {
+    expect(showsSkip(OnboardingStep.INTRO)).toBe(true)
+    expect(showsSkip(OnboardingStep.SEARCH)).toBe(true)
+    expect(showsSkip(OnboardingStep.CUSTOMIZE)).toBe(true)
+    expect(showsSkip(OnboardingStep.COMPLETE)).toBe(false)
+  })
+})
diff --git a/packages/extension/src/components/onboarding/onboardingProgress.ts b/packages/extension/src/components/onboarding/onboardingProgress.ts
new file mode 100644
index 00000000..4c42617a
--- /dev/null
+++ b/packages/extension/src/components/onboarding/onboardingProgress.ts
@@ -0,0 +1,39 @@
+import { OnboardingStep } from "@/types/onboarding"
+
+// The 4 steps the progress indicator tracks. INTRO and COMPLETE are
+// bookends (no indicator shown for them) - see getProgress() below.
+export const PROGRESS_STEPS = [
+  OnboardingStep.SEARCH,
+  OnboardingStep.AI_PROMPT,
+  OnboardingStep.LINK_PREVIEW,
+  OnboardingStep.CUSTOMIZE,
+] as const
+
+export type PillState = "done" | "current" | "todo"
+
+export type OnboardingProgress = {
+  pills: PillState[]
+  current: number
+  total: number
+}
+
+// Derives the header progress indicator's state from the current step, so
+// no other component needs to know the step count or index arithmetic.
+// Returns null for INTRO/COMPLETE, which don't show an indicator.
+export function getProgress(step: OnboardingStep): OnboardingProgress | null {
+  const index = PROGRESS_STEPS.indexOf(step as (typeof PROGRESS_STEPS)[number])
+  if (index === -1) return null
+
+  return {
+    pills: PROGRESS_STEPS.map((_, i) =>
+      i < index ? "done" : i === index ? "current" : "todo",
+    ),
+    current: index + 1,
+    total: PROGRESS_STEPS.length,
+  }
+}
+
+// The Skip button is available on every step except the final one - there's
+// nothing left to skip once the user has reached it.
+export const showsSkip = (step: OnboardingStep): boolean =>
+  step !== OnboardingStep.COMPLETE
diff --git a/packages/extension/src/components/onboarding/onboardingWindow.ts b/packages/extension/src/components/onboarding/onboardingWindow.ts
new file mode 100644
index 00000000..3c17e3ac
--- /dev/null
+++ b/packages/extension/src/components/onboarding/onboardingWindow.ts
@@ -0,0 +1,18 @@
+import { Ipc, BgCommand } from "@/services/ipc"
+
+// Closes the onboarding tab. The tab is opened via chrome.tabs.create() from
+// the background script (not window.open() from the page itself), so a bare
+// window.close() call is not guaranteed to work per the Window.close() spec
+// ("scripts may close only the windows that were opened by them"). Routing
+// the close through the background script (BgCommand.closeTab) rather than
+// calling chrome.tabs.remove() on the page's own tab id keeps tab lifecycle
+// decisions in the background script alongside the rest of tab management.
+export async function closeOnboardingTab(): Promise<void> {
+  try {
+    const closed = await Ipc.send<undefined, boolean>(BgCommand.closeTab)
+    if (closed) return
+  } catch {
+    // Fall through to window.close() below.
+  }
+  window.close()
+}
diff --git a/packages/extension/src/components/onboarding/phaseDelays.ts b/packages/extension/src/components/onboarding/phaseDelays.ts
new file mode 100644
index 00000000..6b085ee3
--- /dev/null
+++ b/packages/extension/src/components/onboarding/phaseDelays.ts
@@ -0,0 +1,17 @@
+// ms, nested by phase since the same element (e.g. rail) can have a
+// different delay depending on which phase is currently showing it. Shared
+// across the onboarding step components (StepSearchCommand, StepAiPromptCommand,
+// StepLinkPreview) - each step's own `delays` object only fills in the keys
+// it actually renders for a given phase.
+export type PhaseDelays = {
+  commandType: number
+  message: number
+  rail: number
+  targetText?: number
+  targetTextCallout?: number
+  callout?: number
+  returnCallout?: number
+  emoji?: number
+  valueSubmessage?: number
+  nextButton?: number
+}
diff --git a/packages/extension/src/components/onboarding/steps/StepAiPromptCommand.tsx b/packages/extension/src/components/onboarding/steps/StepAiPromptCommand.tsx
new file mode 100644
index 00000000..c81a7e20
--- /dev/null
+++ b/packages/extension/src/components/onboarding/steps/StepAiPromptCommand.tsx
@@ -0,0 +1,233 @@
+import { useEffect, useState } from "react"
+import { cn } from "@/lib/utils"
+import { ChevronRight } from "lucide-react"
+import { t } from "@/services/i18n"
+import { useSelectContext } from "@/hooks/useSelectContext"
+import { isEmpty } from "@/lib/utils"
+import { renderMultiline } from "../textUtils"
+import { ONBOARDING_AI_PROMPT_COMMAND_ID } from "../onboardingCommand"
+import { subscribeCommandExecuted } from "../onboardingEvents"
+import { OnboardingCallout } from "../OnboardingCallout"
+import { OnboardingFadeIn } from "../OnboardingFadeIn"
+import { OnboardingTargetText } from "../OnboardingTargetText"
+import { OnboardingRail } from "../OnboardingRail"
+import { OnboardingStep, StepPhase } from "@/types/onboarding"
+import type { UseOnboardingState } from "../useOnboardingState"
+import type { PhaseDelays } from "../phaseDelays"
+
+type Props = {
+  onboarding: UseOnboardingState
+}
+
+function railBeat(phase: StepPhase): 0 | 1 | 2 | -1 {
+  if (phase === StepPhase.WAIT_EXECUTE) return 1
+  if (phase === StepPhase.WAIT_RETURN) return 2
+  if (phase === StepPhase.VALUE_SHOWN) return -1
+  return 0
+}
+
+// Step2: run the onboarding's dedicated AiPrompt command (see
+// onboardingCommand.ts), which opens the side panel - unlike Step1's search,
+// the onboarding page never loses visibility here, so there's no separate
+// "wait for the user to come back" phase, and the rail only ever needs
+// beats 0 (selecting) and 1 (running the command).
+export function StepAiPromptCommand({ onboarding }: Props) {
+  const { phase, setPhase } = onboarding
+  const { selectionText, setSelectionText } = useSelectContext()
+  const [calloutElm, setCalloutElm] = useState<Element | null>(null)
+
+  const isExplain = phase === StepPhase.EXPLAIN
+  const isWaitSelection = phase === StepPhase.WAIT_SELECTION
+  const isWaitExecute = phase === StepPhase.WAIT_EXECUTE
+  const isWaitReturn = phase === StepPhase.WAIT_RETURN
+  const isValueShown = phase === StepPhase.VALUE_SHOWN
+
+  const delays: Partial<Record<StepPhase, PhaseDelays>> = {
+    [StepPhase.EXPLAIN]: {
+      commandType: 100,
+      message: 300,
+      rail: 400,
+      targetText: 500,
+      targetTextCallout: 800,
+      callout: 200,
+    },
+    [StepPhase.WAIT_EXECUTE]: {
+      commandType: 100,
+      message: 300,
+      rail: 400,
+      targetText: 500,
+      targetTextCallout: 800,
+      callout: 200,
+    },
+    [StepPhase.WAIT_RETURN]: {
+      commandType: 100,
+      message: 300,
+      rail: 400,
+      targetText: 500,
+      targetTextCallout: 800,
+      callout: 200,
+    },
+    [StepPhase.VALUE_SHOWN]: {
+      commandType: 100,
+      message: 300,
+      emoji: 500,
+      valueSubmessage: 800,
+      rail: 1200,
+      nextButton: 1400,
+    },
+  }
+  const phaseDelays = delays[phase] ?? delays[StepPhase.EXPLAIN]!
+
+  useEffect(() => {
+    if (!isExplain) return
+    setSelectionText("")
+    setPhase(StepPhase.WAIT_SELECTION)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  useEffect(() => {
+    if (!isWaitSelection) return
+    if (isEmpty(selectionText)) return
+    onboarding.recordFirstSelection(OnboardingStep.AI_PROMPT)
+    setPhase(StepPhase.WAIT_EXECUTE)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [phase, selectionText])
+
+  useEffect(() => {
+    if (!isWaitExecute) {
+      setCalloutElm(null)
+      return
+    }
+    // Observe the DOM instead of polling, so the callout both appears once
+    // the popup menu renders AND disappears if the button is later removed.
+    const selector = `[data-command-id="${ONBOARDING_AI_PROMPT_COMMAND_ID}"]`
+    const sync = () => {
+      const elm = document.querySelector(selector)
+      setCalloutElm(elm)
+    }
+    sync()
+    const observer = new MutationObserver(sync)
+    observer.observe(document.body, { childList: true, subtree: true })
+    return () => {
+      observer.disconnect()
+    }
+  }, [isWaitExecute])
+
+  useEffect(() => {
+    if (!isWaitExecute) return
+    return subscribeCommandExecuted(({ commandId, commandType }) => {
+      if (commandId !== ONBOARDING_AI_PROMPT_COMMAND_ID) return
+      onboarding.recordCommandExecuted(OnboardingStep.AI_PROMPT, commandType)
+      setPhase(StepPhase.WAIT_RETURN)
+      setPhase(StepPhase.VALUE_SHOWN, 5000)
+    })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [phase])
+
+  // Renders through this single return for every phase, including
+  // VALUE_SHOWN, instead of branching into a separate <OnboardingValueShown>
+  // subtree there - see StepSearchCommand.tsx for why: that would mount a
+  // second, independent OnboardingRail, losing the "select -> command ->
+  // result" beat animation's continuity right as the payoff screen appears.
+  return (
+    <div className={cn("flex flex-col items-center gap-10 select-none")}>
+      <OnboardingFadeIn key={"command-type"} delay={phaseDelays.commandType}>
+        <h2 className="text-4xl font-bold text-slate-700 flex items-center">
+          <span className="font-mono">2.</span>{" "}
+          {t("Option_commandType_aiPrompt_title")}
+        </h2>
+      </OnboardingFadeIn>
+
+      <div className="flex flex-col items-center gap-4">
+        <OnboardingFadeIn
+          key={
+            isValueShown
+              ? "value-message"
+              : isWaitReturn
+                ? "wait-return"
+                : "explain"
+          }
+          className="flex flex-col items-center gap-4"
+          delay={phaseDelays.message}
+        >
+          <p className="max-w-xl text-xl leading-[1.75] font-semibold text-slate-900">
+            {isValueShown ? (
+              <>
+                <span>{t("onboarding_step2ValueMessage")}</span>
+                <span
+                  className="ml-1 inline-block animate-onboarding-pop-2 motion-reduce:animate-none"
+                  style={{ animationDelay: `${phaseDelays.emoji}ms` }}
+                >
+                  🎉
+                </span>
+              </>
+            ) : isWaitReturn ? (
+              t("onboarding_step2WaitReturn")
+            ) : (
+              t("onboarding_step2Explain")
+            )}
+          </p>
+        </OnboardingFadeIn>
+
+        {isValueShown && (
+          <OnboardingFadeIn
+            key="value-submessage"
+            delay={phaseDelays.valueSubmessage}
+          >
+            <p className="max-w-xl text-base text-slate-700 text-pretty">
+              {renderMultiline(t("onboarding_step2ValueSubmessage"))}
+            </p>
+          </OnboardingFadeIn>
+        )}
+
+        <OnboardingFadeIn
+          key={isValueShown ? "rail-complete" : "rail"}
+          delay={phaseDelays.rail}
+          className={isValueShown ? undefined : "pb-14"}
+        >
+          <OnboardingRail
+            selectLabel={t("onboarding_railSelect")}
+            commandLabel={t("onboarding_railCommand")}
+            resultLabel={t("onboarding_railResultAi")}
+            activeBeat={railBeat(phase)}
+            size="lg"
+          />
+        </OnboardingFadeIn>
+      </div>
+
+      {!isValueShown && (
+        <>
+          <OnboardingFadeIn key={"target-text"} delay={phaseDelays.targetText}>
+            <OnboardingTargetText
+              text={t("onboarding_step2TargetText")}
+              selected={!isExplain}
+              calloutDelay={phaseDelays.targetTextCallout}
+            />
+          </OnboardingFadeIn>
+
+          <OnboardingCallout
+            targetElm={calloutElm}
+            open={calloutElm != null}
+            openDelay={phaseDelays.callout}
+            contentClassName="duration-300"
+          >
+            {t("onboarding_step2Callout")}
+          </OnboardingCallout>
+        </>
+      )}
+
+      {isValueShown && (
+        <OnboardingFadeIn key="next-button" delay={phaseDelays.nextButton}>
+          <button
+            type="button"
+            onClick={() => onboarding.goToStep(OnboardingStep.LINK_PREVIEW)}
+            className="flex items-center gap-2 min-h-14 rounded-xl bg-sky-950 px-8 text-lg font-semibold text-white shadow-[0_10px_20px_-14px_rgba(15,23,42,.7)] hover:brightness-[1.35]"
+          >
+            {t("onboarding_nextButton")}
+            <ChevronRight className="inline-block size-5" />
+          </button>
+        </OnboardingFadeIn>
+      )}
+    </div>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/steps/StepComplete.tsx b/packages/extension/src/components/onboarding/steps/StepComplete.tsx
new file mode 100644
index 00000000..516a65d6
--- /dev/null
+++ b/packages/extension/src/components/onboarding/steps/StepComplete.tsx
@@ -0,0 +1,91 @@
+import { useEffect } from "react"
+import { MousePointerClick, PartyPopper, Settings } from "lucide-react"
+import { t } from "@/services/i18n"
+import { OnboardingFadeIn } from "../OnboardingFadeIn"
+import { OnboardingConfetti } from "../OnboardingConfetti"
+import { closeOnboardingTab } from "../onboardingWindow"
+import { renderMultiline } from "../textUtils"
+import type { UseOnboardingState } from "../useOnboardingState"
+
+type Props = {
+  onboarding: UseOnboardingState
+}
+
+// Step5: the final, EXPLAIN-only screen. Marks the onboarding as complete
+// (hasShownOnboarding=true, ONBOARDING_COMPLETE analytics event) as soon as
+// it's reached, since there's no further step to skip out of.
+//
+// The primary button closes the tab and returns the user to the page they
+// were on - the explanation text already tells them to "select text and
+// try it", so the button that actually lets them do that is the one that
+// gets top billing; "open settings" (something they can always do later,
+// and which Step4 already introduced) is the secondary action.
+export function StepComplete({ onboarding }: Props) {
+  const { complete } = onboarding
+  const delays = [600, 200, 800, 1000, 1200] // ms
+
+  useEffect(() => {
+    complete()
+  }, [complete])
+
+  return (
+    <>
+      <OnboardingConfetti />
+      <div className="flex flex-col items-center gap-8">
+        <span
+          className="flex size-[76px] animate-onboarding-pop items-center justify-center rounded-full bg-green-200 text-green-600 motion-reduce:animate-none motion-reduce:opacity-100"
+          style={{ animationDelay: `${delays[0]}ms` }}
+        >
+          <PartyPopper className="size-9" strokeWidth={1.8} />
+        </span>
+
+        <OnboardingFadeIn
+          className="flex flex-col items-center gap-5"
+          delay={delays[1]}
+        >
+          <h1 className="mt-1 text-3xl font-bold tracking-tight text-slate-700">
+            {t("onboarding_completeTitle")}
+          </h1>
+        </OnboardingFadeIn>
+
+        <OnboardingFadeIn
+          className="flex flex-col items-center gap-5"
+          delay={delays[2]}
+        >
+          <p className="max-w-lg text-base leading-[1.85] text-slate-700 text-pretty">
+            {renderMultiline(t("onboarding_completeBody"))}
+          </p>
+        </OnboardingFadeIn>
+
+        <div className="mt-2.5 flex items-center gap-5">
+          <OnboardingFadeIn
+            className="flex flex-col items-center gap-5"
+            delay={delays[3]}
+          >
+            <button
+              type="button"
+              className="flex items-center gap-3 min-h-14 rounded-xl bg-sky-950 pl-6 pr-8 text-[15px] font-semibold text-white shadow-[0_10px_20px_-14px_rgba(15,23,42,.7)] hover:brightness-[1.35]"
+              onClick={() => closeOnboardingTab()}
+            >
+              <MousePointerClick className="inline-block size-5" />
+              {t("onboarding_closeButton")}
+            </button>
+          </OnboardingFadeIn>
+          <OnboardingFadeIn
+            className="flex flex-col items-center gap-5"
+            delay={delays[4]}
+          >
+            <button
+              type="button"
+              className="flex items-center gap-3 min-h-14 rounded-xl px-5 text-[15px] font-medium text-slate-500 border border-slate-200 hover:bg-slate-50 hover:text-slate-700"
+              onClick={() => chrome.runtime.openOptionsPage()}
+            >
+              <Settings className="inline-block size-4" />
+              {t("onboarding_openSettingsButton")}
+            </button>
+          </OnboardingFadeIn>
+        </div>
+      </div>
+    </>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/steps/StepCustomize.tsx b/packages/extension/src/components/onboarding/steps/StepCustomize.tsx
new file mode 100644
index 00000000..7cb685d3
--- /dev/null
+++ b/packages/extension/src/components/onboarding/steps/StepCustomize.tsx
@@ -0,0 +1,90 @@
+import { Settings, Share2, ChevronRight } from "lucide-react"
+import { t } from "@/services/i18n"
+import { OnboardingFadeIn } from "../OnboardingFadeIn"
+import { OnboardingStep } from "@/types/onboarding"
+import type { UseOnboardingState } from "../useOnboardingState"
+
+type Props = {
+  onboarding: UseOnboardingState
+}
+
+const OPTION_SCREEN_URL = chrome.runtime.getURL("onboarding/OptionScreen.png")
+const HUB_SCREEN_URL = chrome.runtime.getURL("onboarding/HubScreen.png")
+
+// Step4: EXPLAIN-only wrap-up telling the user the sample commands seen in
+// Steps 1-3 can be added to or edited from either the settings screen or
+// the Command Hub. Both panels below are screenshots of those real screens,
+// not live links - per the PRD, Step4 is a lightweight pointer, not a place
+// to start a real editing/browsing flow mid-onboarding.
+export function StepCustomize({ onboarding }: Props) {
+  return (
+    <div className="flex flex-col items-center gap-10 !h-[540px]">
+      <OnboardingFadeIn key="title" delay={100}>
+        <h2 className="text-4xl font-bold text-slate-700 flex items-center">
+          <span className="font-mono">4.</span> {t("onboarding_step4_title")}
+        </h2>
+      </OnboardingFadeIn>
+
+      <OnboardingFadeIn key="explain" delay={300}>
+        <p className="max-w-xl text-xl leading-[1.75] font-semibold text-slate-900">
+          {t("onboarding_step4Explain")}
+          <span
+            className="ml-1 inline-block animate-onboarding-pop-2 motion-reduce:animate-none"
+            style={{ animationDelay: "600ms" }}
+          >
+            🎉
+          </span>
+        </p>
+      </OnboardingFadeIn>
+
+      <div className="grid w-[884px] grid-cols-2 gap-12">
+        <OnboardingFadeIn key="option-screen" delay={1000}>
+          <div className="flex flex-col gap-2.5">
+            <div className="flex items-center gap-2 text-left text-sm font-bold text-slate-700">
+              <span className="flex size-6 items-center justify-center rounded-md bg-sky-950/[0.1] text-sky-950">
+                <Settings className="size-4" strokeWidth={2} />
+              </span>
+              {t("onboarding_step4SettingsHeading")}
+            </div>
+            <div className="h-[226px] overflow-hidden rounded-lg border border-slate-200 bg-white shadow-[0_1px_2px_rgba(15,23,42,.04),0_16px_32px_-26px_rgba(15,23,42,.35)]">
+              <img
+                src={OPTION_SCREEN_URL}
+                alt=""
+                className="h-full w-full object-cover object-top"
+              />
+            </div>
+          </div>
+        </OnboardingFadeIn>
+
+        <OnboardingFadeIn key="hub-screen" delay={1200}>
+          <div className="flex flex-col gap-2.5">
+            <div className="flex items-center gap-2 text-left text-sm font-bold text-slate-700">
+              <span className="flex size-6 items-center justify-center rounded-md bg-sky-950/[0.1] text-sky-950">
+                <Share2 className="size-4" strokeWidth={2} />
+              </span>
+              {t("onboarding_step4HubHeading")}
+            </div>
+            <div className="h-[226px] overflow-hidden rounded-lg border border-slate-200 bg-white shadow-[0_1px_2px_rgba(15,23,42,.04),0_16px_32px_-26px_rgba(15,23,42,.35)]">
+              <img
+                src={HUB_SCREEN_URL}
+                alt=""
+                className="h-full w-full object-cover object-top"
+              />
+            </div>
+          </div>
+        </OnboardingFadeIn>
+      </div>
+
+      <OnboardingFadeIn key="next-button" delay={1400}>
+        <button
+          type="button"
+          className="mt-4 flex items-center gap-2 min-h-14 rounded-xl bg-sky-950 pl-8 pr-5 text-lg font-semibold text-white shadow-[0_10px_20px_-14px_rgba(15,23,42,.7)] hover:brightness-[1.35]"
+          onClick={() => onboarding.goToStep(OnboardingStep.COMPLETE)}
+        >
+          {t("onboarding_nextButton")}
+          <ChevronRight className="inline-block size-5" />
+        </button>
+      </OnboardingFadeIn>
+    </div>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/steps/StepIntro.tsx b/packages/extension/src/components/onboarding/steps/StepIntro.tsx
new file mode 100644
index 00000000..16428525
--- /dev/null
+++ b/packages/extension/src/components/onboarding/steps/StepIntro.tsx
@@ -0,0 +1,50 @@
+import { t } from "@/services/i18n"
+import { ChevronRight } from "lucide-react"
+import { OnboardingFadeIn } from "../OnboardingFadeIn"
+import { OnboardingStep } from "@/types/onboarding"
+import type { UseOnboardingState } from "../useOnboardingState"
+
+const ICON_URL = chrome.runtime.getURL("SelectionCommandLogo.png")
+
+type Props = {
+  onboarding: UseOnboardingState
+}
+
+// Step0: the landing screen shown right after install.
+export function StepIntro({ onboarding }: Props) {
+  return (
+    <div className="flex flex-col items-center justify-center gap-16">
+      <OnboardingFadeIn delay={200} className="flex items-center">
+        <img
+          src={ICON_URL}
+          className={"block h-[50px]"}
+          alt="Logo of selection command"
+          aria-hidden
+        />
+      </OnboardingFadeIn>
+
+      <div>
+        <OnboardingFadeIn delay={500}>
+          <h1 className="max-w-xl text-3xl font-bold tracking-tight text-slate-900">
+            {t("onboarding_step0Title")}
+          </h1>
+        </OnboardingFadeIn>
+        <OnboardingFadeIn delay={600}>
+          <p className="max-w-xl mt-5 text-xl leading-[1.85] text-slate-600">
+            {t("onboarding_step0Body")}
+          </p>
+        </OnboardingFadeIn>
+      </div>
+      <OnboardingFadeIn delay={800} className="flex justify-center">
+        <button
+          type="button"
+          className="flex items-center gap-2 min-h-14 rounded-xl bg-sky-950 pl-8 pr-5 text-lg font-semibold text-white shadow-[0_10px_20px_-14px_rgba(15,23,42,.7)] hover:brightness-[1.35]"
+          onClick={() => onboarding.goToStep(OnboardingStep.SEARCH)}
+        >
+          {t("onboarding_startButton")}
+          <ChevronRight className="inline-block size-5" />
+        </button>
+      </OnboardingFadeIn>
+    </div>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/steps/StepLinkPreview.tsx b/packages/extension/src/components/onboarding/steps/StepLinkPreview.tsx
new file mode 100644
index 00000000..e0193cc9
--- /dev/null
+++ b/packages/extension/src/components/onboarding/steps/StepLinkPreview.tsx
@@ -0,0 +1,253 @@
+import { useEffect, useState } from "react"
+import { ChevronRight, ArrowBigUp, MousePointerClick } from "lucide-react"
+import { t } from "@/services/i18n"
+import { DRAG_OPEN_MODE } from "@/const"
+import { subscribeCommandExecuted } from "../onboardingEvents"
+import { OnboardingCallout } from "../OnboardingCallout"
+import { OnboardingFadeIn } from "../OnboardingFadeIn"
+import { OnboardingRail } from "../OnboardingRail"
+import { renderMultiline } from "../textUtils"
+import { OnboardingStep, StepPhase } from "@/types/onboarding"
+import type { UseOnboardingState } from "../useOnboardingState"
+import type { PhaseDelays } from "../phaseDelays"
+
+type Props = {
+  onboarding: UseOnboardingState
+}
+
+const DRAG_OPEN_MODES: readonly string[] = Object.values(DRAG_OPEN_MODE)
+
+// WAIT_RETURN counts as the rail's "result" beat, same as StepSearchCommand -
+// the preview already opened, we're just waiting for the user to switch back.
+function railBeat(phase: StepPhase): 0 | 2 {
+  if (phase === StepPhase.WAIT_RETURN) return 2
+  return 0
+}
+
+// Step3: Shift+click the sample link to trigger Link Preview. Unlike
+// Steps 1-2 this isn't triggered via text selection, so it only ever uses
+// the EXPLAIN, WAIT_RETURN and VALUE_SHOWN phases - per the design note
+// that "select" here stands in for "pick the target" even though the
+// gesture is a click, not a drag.
+export function StepLinkPreview({ onboarding }: Props) {
+  const { phase, setPhase } = onboarding
+  const [linkElm, setLinkElm] = useState<HTMLElement | null>(null)
+  const [returnCalloutElm, setReturnCalloutElm] = useState<Element | null>(null)
+
+  const isExplain = phase === StepPhase.EXPLAIN
+  const isWaitReturn = phase === StepPhase.WAIT_RETURN
+  const isValueShown = phase === StepPhase.VALUE_SHOWN
+
+  // Step3 only ever uses EXPLAIN, WAIT_RETURN and VALUE_SHOWN (see the
+  // component doc comment above), so there's no waitExecute group here.
+  const delays: Partial<Record<StepPhase, PhaseDelays>> = {
+    [StepPhase.EXPLAIN]: {
+      commandType: 100,
+      message: 300,
+      rail: 400,
+      targetText: 500,
+      callout: 800,
+    },
+    [StepPhase.WAIT_RETURN]: {
+      commandType: 100,
+      message: 300,
+      rail: 400,
+      returnCallout: 1000,
+    },
+    [StepPhase.VALUE_SHOWN]: {
+      commandType: 100,
+      message: 300,
+      emoji: 500,
+      valueSubmessage: 800,
+      rail: 1200,
+      nextButton: 1400,
+    },
+  }
+  const phaseDelays = delays[phase] ?? delays[StepPhase.EXPLAIN]!
+
+  useEffect(() => {
+    if (isWaitReturn) {
+      const elm = document.querySelector(
+        "[data-testid='onboarding-step3-callout-anchor']",
+      )
+      setReturnCalloutElm(elm)
+    } else {
+      setReturnCalloutElm(null)
+    }
+
+    if (!isExplain) return
+
+    return subscribeCommandExecuted(({ commandType }) => {
+      if (!DRAG_OPEN_MODES.includes(commandType)) return
+      onboarding.recordCommandExecuted(OnboardingStep.LINK_PREVIEW, commandType)
+      setPhase(StepPhase.WAIT_RETURN)
+    })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [phase])
+
+  // The preview opens in a separate browser window/tab, so switching focus
+  // back doesn't reliably fire `visibilitychange` alone (that API tracks tab
+  // occlusion/minimization, not window focus) - a `focus` listener on this
+  // window is needed too, to reliably detect the user clicking back onto the
+  // onboarding window. See StepSearchCommand.tsx for the same pattern.
+  useEffect(() => {
+    if (!isWaitReturn) return
+
+    const onVisible = () => {
+      if (document.visibilityState === "visible") {
+        setPhase(StepPhase.VALUE_SHOWN, 100)
+      }
+    }
+    document.addEventListener("visibilitychange", onVisible)
+    window.addEventListener("focus", onVisible)
+    return () => {
+      document.removeEventListener("visibilitychange", onVisible)
+      window.removeEventListener("focus", onVisible)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [phase])
+
+  // Renders through this single return for every phase, including
+  // VALUE_SHOWN, instead of branching into a separate <OnboardingValueShown>
+  // subtree there - see StepSearchCommand.tsx for why: that would mount a
+  // second, independent OnboardingRail, losing the "select -> command ->
+  // result" beat animation's continuity right as the payoff screen appears.
+  return (
+    <div className="flex flex-col items-center gap-10">
+      <OnboardingFadeIn key={"command-type"} delay={phaseDelays.commandType}>
+        <h2 className="text-4xl font-bold text-slate-700 flex items-center">
+          <span className="font-mono">3.</span> {t("Option_linkCommand")}
+        </h2>
+      </OnboardingFadeIn>
+
+      <div className="flex flex-col items-center gap-4">
+        <OnboardingFadeIn
+          key={
+            isValueShown
+              ? "value-message"
+              : isWaitReturn
+                ? "return-hint"
+                : "explain"
+          }
+          className="flex flex-col items-center gap-4"
+          delay={phaseDelays.message}
+        >
+          <p className="max-w-xl text-xl leading-[1.75] font-semibold text-slate-900">
+            {isValueShown ? (
+              <>
+                <span>{t("onboarding_step3ValueMessage")}</span>
+                <span
+                  className="ml-1 inline-block animate-onboarding-pop-2 motion-reduce:animate-none"
+                  style={{ animationDelay: `${phaseDelays.emoji}ms` }}
+                >
+                  🎉
+                </span>
+              </>
+            ) : isWaitReturn ? (
+              t("onboarding_step3ReturnHint")
+            ) : (
+              t("onboarding_step3Explain")
+            )}
+          </p>
+        </OnboardingFadeIn>
+
+        {isValueShown && (
+          <OnboardingFadeIn
+            key="value-submessage"
+            delay={phaseDelays.valueSubmessage}
+          >
+            <p className="max-w-xl text-base text-slate-700 text-pretty">
+              {renderMultiline(t("onboarding_step3ValueSubmessage"))}
+            </p>
+          </OnboardingFadeIn>
+        )}
+
+        <OnboardingFadeIn
+          key={isValueShown ? "rail-complete" : "rail"}
+          delay={phaseDelays.rail}
+        >
+          <OnboardingRail
+            selectLabel={t("onboarding_railSelect")}
+            commandLabel={t("onboarding_railCommand")}
+            resultLabel={t("onboarding_railResultPreview")}
+            activeBeat={isValueShown ? -1 : railBeat(phase)}
+            size="lg"
+          />
+        </OnboardingFadeIn>
+      </div>
+
+      {isExplain && (
+        <OnboardingFadeIn
+          key={"target-text"}
+          className="mt-24 flex flex-col items-center gap-8"
+          delay={phaseDelays.targetText}
+        >
+          <div
+            className="flex animate-onboarding-ring items-center justify-center rounded-lg border border-slate-200 bg-white [--onboarding-ring-color:rgba(8,47,73,0.16)] motion-reduce:animate-none"
+            ref={setLinkElm}
+          >
+            <a
+              href="https://www.aalto.fi/en/news/one-in-four-internet-users-are-overwhelmed-by-the-clutter-in-their-browser"
+              className="text-base px-6 py-3 text-sky-700 underline decoration-1 underline-offset-[3px] hover:text-sky-800"
+              onClick={(e) => e.preventDefault()}
+            >
+              {t("onboarding_step3LinkLabel")}
+            </a>
+          </div>
+
+          <OnboardingCallout
+            targetElm={linkElm}
+            open={linkElm != null}
+            openDelay={phaseDelays.callout}
+            contentClassName="duration-300 select-none"
+          >
+            <div className="flex flex-col items-center gap-2 pb-1">
+              {t("onboarding_step3Callout")}
+              <div className="flex items-center gap-2">
+                <span className="inline-flex min-h-8 items-center gap-1.5 rounded-lg border border-b-2 border-slate-300 bg-white px-2.5 text-xs font-bold tracking-wide text-slate-700">
+                  <ArrowBigUp className="size-4" strokeWidth={2} />
+                  Shift
+                </span>
+                <span className="text-xs font-semibold text-slate-500">+</span>
+                <span className="inline-flex min-h-8 items-center gap-1.5 rounded-lg border border-b-2 border-slate-300 bg-white px-2.5 text-xs font-bold tracking-wide text-slate-700">
+                  <MousePointerClick className="size-4" strokeWidth={2} />
+                  {t("onboarding_clickKeycap")}
+                </span>
+              </div>
+            </div>
+          </OnboardingCallout>
+        </OnboardingFadeIn>
+      )}
+
+      {isWaitReturn && (
+        <>
+          <span
+            className="mt-10 size-8 shrink-0 rounded-full bg-sky-950/[0.14] text-sky-950 animate-onboarding-blink motion-reduce:animate-none"
+            data-testid="onboarding-step3-callout-anchor"
+          />
+          <OnboardingCallout
+            targetElm={returnCalloutElm}
+            open={returnCalloutElm != null}
+            openDelay={phaseDelays.returnCallout}
+            contentClassName="duration-300"
+          >
+            {t("onboarding_step1Callout_2")}
+          </OnboardingCallout>
+        </>
+      )}
+
+      {isValueShown && (
+        <OnboardingFadeIn key="next-button" delay={phaseDelays.nextButton}>
+          <button
+            type="button"
+            onClick={() => onboarding.goToStep(OnboardingStep.CUSTOMIZE)}
+            className="flex items-center gap-2 min-h-14 rounded-xl bg-sky-950 px-8 text-lg font-semibold text-white shadow-[0_10px_20px_-14px_rgba(15,23,42,.7)] hover:brightness-[1.35]"
+          >
+            {t("onboarding_nextButton")}
+            <ChevronRight className="inline-block size-5" />
+          </button>
+        </OnboardingFadeIn>
+      )}
+    </div>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/steps/StepSearchCommand.tsx b/packages/extension/src/components/onboarding/steps/StepSearchCommand.tsx
new file mode 100644
index 00000000..1cf2482c
--- /dev/null
+++ b/packages/extension/src/components/onboarding/steps/StepSearchCommand.tsx
@@ -0,0 +1,295 @@
+import { useEffect, useState } from "react"
+import { ChevronRight } from "lucide-react"
+import { t } from "@/services/i18n"
+import { cn } from "@/lib/utils"
+import { useSelectContext } from "@/hooks/useSelectContext"
+import { useSection } from "@/hooks/useSettings"
+import { CACHE_SECTIONS } from "@/services/settings/settingsCache"
+import { isEmpty } from "@/lib/utils"
+import { OPEN_MODE_TYPE_MAP, COMMAND_TYPE } from "@/const"
+import { subscribeCommandExecuted } from "../onboardingEvents"
+import { OnboardingCallout } from "../OnboardingCallout"
+import { OnboardingFadeIn } from "../OnboardingFadeIn"
+import { OnboardingTargetText } from "../OnboardingTargetText"
+import { OnboardingRail } from "../OnboardingRail"
+import { OnboardingStep, StepPhase } from "@/types/onboarding"
+import type { UseOnboardingState } from "../useOnboardingState"
+import type { PhaseDelays } from "../phaseDelays"
+
+type Props = {
+  onboarding: UseOnboardingState
+}
+
+// WAIT_RETURN still counts as the rail's "result" beat (see
+// OnboardingRail) - the search already ran, we're just waiting for the
+// user to switch back.
+function railBeat(phase: StepPhase): 0 | 1 | 2 {
+  if (phase === StepPhase.WAIT_EXECUTE) return 1
+  if (phase === StepPhase.WAIT_RETURN) return 2
+  return 0
+}
+
+// Step1 - the PRD's "First Value" moment.
+export function StepSearchCommand({ onboarding }: Props) {
+  const { phase, setPhase } = onboarding
+  const { selectionText } = useSelectContext()
+  const { data: commands } = useSection(CACHE_SECTIONS.COMMANDS)
+  const [calloutElm, setCalloutElm] = useState<Element | null>(null)
+  const [returnCalloutElm, setReturnCalloutElm] = useState<Element | null>(null)
+
+  const googleCommand = commands?.find((c) => c.title === "Google")
+
+  const isExplain = phase === StepPhase.EXPLAIN
+  const isWaitExecute = phase === StepPhase.WAIT_EXECUTE
+  const isWaitReturn = phase === StepPhase.WAIT_RETURN
+  const isValueShown = phase === StepPhase.VALUE_SHOWN
+
+  const delays: Partial<Record<StepPhase, PhaseDelays>> = {
+    [StepPhase.EXPLAIN]: {
+      commandType: 100,
+      message: 300,
+      rail: 400,
+      targetText: 700,
+      targetTextCallout: 900,
+      callout: 1000,
+    },
+    [StepPhase.WAIT_EXECUTE]: {
+      commandType: 100,
+      message: 300,
+      rail: 400,
+      targetText: 500,
+      targetTextCallout: 800,
+      callout: 200,
+    },
+    [StepPhase.WAIT_RETURN]: {
+      commandType: 100,
+      message: 300,
+      rail: 400,
+      returnCallout: 1000,
+    },
+    [StepPhase.VALUE_SHOWN]: {
+      commandType: 100,
+      message: 300,
+      emoji: 500,
+      valueSubmessage: 800,
+      rail: 1200,
+      nextButton: 1400,
+    },
+  }
+  const phaseDelays = delays[phase] ?? delays[StepPhase.EXPLAIN]!
+
+  // The popup menu opens on its own once the sample text is selected
+  // (default startup method is text selection).
+  useEffect(() => {
+    if (!isExplain) return
+    if (isEmpty(selectionText)) return
+    onboarding.recordFirstSelection(OnboardingStep.SEARCH)
+    setPhase(StepPhase.WAIT_EXECUTE, 600)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [phase, selectionText])
+
+  // Find the rendered Google command button (see MenuItem.tsx's
+  // `data-command-id`) to point the callout at, once the menu has had a
+  // chance to render. Re-runs on every selection change so that redoing the
+  // text selection (which closes and reopens the real popup menu) hides the
+  // stale callout and re-anchors it to the freshly rendered button instead
+  // of staying frozen at the old position.
+  useEffect(() => {
+    if (!isWaitExecute || !googleCommand) {
+      setCalloutElm(null)
+      return
+    }
+    if (isEmpty(selectionText)) {
+      setCalloutElm(null)
+      return
+    }
+
+    // Observe the DOM instead of polling, so the callout both appears once
+    // the popup menu renders AND disappears if the button is later removed
+    // (e.g. the popup menu closes without a selection change in between).
+    const selector = `[data-command-id="${googleCommand.id}"]`
+    const sync = () => {
+      const elm = document.querySelector(selector)
+      setCalloutElm(elm)
+    }
+    sync()
+    const observer = new MutationObserver(sync)
+    observer.observe(document.body, { childList: true, subtree: true })
+    return () => {
+      observer.disconnect()
+    }
+  }, [isWaitExecute, googleCommand, selectionText])
+
+  // Any search-type command counts here (the callout points at Google
+  // specifically, but the default set has several search commands - being
+  // lenient matches the PRD's "選択→コマンド→検索" mental model rather than
+  // requiring one exact command).
+  useEffect(() => {
+    if (!isWaitExecute) return
+    return subscribeCommandExecuted(({ commandType }) => {
+      if (
+        OPEN_MODE_TYPE_MAP[commandType as keyof typeof OPEN_MODE_TYPE_MAP] !==
+        COMMAND_TYPE.SEARCH
+      ) {
+        return
+      }
+      onboarding.recordCommandExecuted(OnboardingStep.SEARCH, commandType)
+      setPhase(StepPhase.WAIT_RETURN)
+    })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [phase])
+
+  // The search command opens in a separate browser window (see
+  // Popup.execute -> BgCommand.openPopup -> chrome.windows.create), not a
+  // tab in this same window. Switching focus between two on-screen windows
+  // doesn't reliably fire `visibilitychange` (that API tracks tab
+  // occlusion/minimization, not window focus), so a `focus` listener on
+  // this window is needed to reliably detect the user clicking back onto
+  // the onboarding window.
+  useEffect(() => {
+    if (!isWaitReturn) return
+
+    const elm = document.querySelector(
+      "[data-testid='onboarding-step1-callout-anchor']",
+    )
+    setReturnCalloutElm(elm)
+
+    const onVisible = () => {
+      if (document.visibilityState === "visible") {
+        setPhase(StepPhase.VALUE_SHOWN, 100)
+        setReturnCalloutElm(null)
+      }
+    }
+    document.addEventListener("visibilitychange", onVisible)
+    window.addEventListener("focus", onVisible)
+    return () => {
+      document.removeEventListener("visibilitychange", onVisible)
+      window.removeEventListener("focus", onVisible)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [phase])
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col items-center gap-10",
+        !isValueShown && !isWaitReturn && "select-none",
+        isWaitReturn && "pb-40",
+      )}
+    >
+      <OnboardingFadeIn key={"command-type"} delay={phaseDelays.commandType}>
+        <h2 className="text-4xl font-bold text-slate-700 flex items-center">
+          <span className="font-mono">1.</span>{" "}
+          {t("Option_commandType_search_title")}
+        </h2>
+      </OnboardingFadeIn>
+
+      <div className="flex flex-col items-center gap-4">
+        <OnboardingFadeIn
+          key={
+            isValueShown
+              ? "value-message"
+              : isWaitReturn
+                ? "return-hint"
+                : "explain"
+          }
+          className="flex flex-col items-center gap-4"
+          delay={phaseDelays.message}
+        >
+          <p className="max-w-xl text-xl leading-[1.75] font-semibold text-slate-900">
+            {isValueShown ? (
+              <>
+                <span>{t("onboarding_step1ValueMessage")}</span>
+                <span
+                  className="ml-1 inline-block animate-onboarding-pop-2 motion-reduce:animate-none"
+                  style={{ animationDelay: `${phaseDelays.emoji}ms` }}
+                >
+                  🎉
+                </span>
+              </>
+            ) : isWaitReturn ? (
+              t("onboarding_step1ReturnHint")
+            ) : (
+              t("onboarding_step1Explain")
+            )}
+          </p>
+        </OnboardingFadeIn>
+
+        {isValueShown && (
+          <OnboardingFadeIn
+            key="value-submessage"
+            delay={phaseDelays.valueSubmessage}
+          >
+            <p className="max-w-xl text-base text-slate-700 text-pretty">
+              {t("onboarding_step1ValueSubmessage")}
+            </p>
+          </OnboardingFadeIn>
+        )}
+
+        <OnboardingFadeIn
+          key={isValueShown ? "rail-complete" : "rail"}
+          delay={phaseDelays.rail}
+          className={isValueShown ? undefined : "pb-14"}
+        >
+          <OnboardingRail
+            selectLabel={t("onboarding_railSelect")}
+            commandLabel={t("onboarding_railCommand")}
+            resultLabel={t("onboarding_railResultSearch")}
+            activeBeat={isValueShown ? -1 : railBeat(phase)}
+            size="lg"
+          />
+        </OnboardingFadeIn>
+      </div>
+
+      {(isExplain || isWaitExecute) && (
+        <>
+          <OnboardingFadeIn key={"target-text"} delay={phaseDelays.targetText}>
+            <OnboardingTargetText
+              text={t("onboarding_step1TargetText")}
+              selected={!isExplain}
+              calloutDelay={phaseDelays.targetTextCallout}
+            />
+          </OnboardingFadeIn>
+          <OnboardingCallout
+            targetElm={calloutElm}
+            open={calloutElm != null}
+            openDelay={phaseDelays.callout}
+            contentClassName="duration-300"
+          >
+            {t("onboarding_step1Callout")}
+          </OnboardingCallout>
+        </>
+      )}
+
+      {isWaitReturn && (
+        <>
+          <span
+            className="size-8 shrink-0 rounded-full bg-sky-950/[0.14] text-sky-950 animate-onboarding-blink motion-reduce:animate-none"
+            data-testid="onboarding-step1-callout-anchor"
+          />
+          <OnboardingCallout
+            targetElm={returnCalloutElm}
+            open={returnCalloutElm != null}
+            openDelay={phaseDelays.returnCallout}
+            contentClassName="duration-300"
+          >
+            {t("onboarding_step1Callout_2")}
+          </OnboardingCallout>
+        </>
+      )}
+
+      {isValueShown && (
+        <OnboardingFadeIn key="next-button" delay={phaseDelays.nextButton}>
+          <button
+            type="button"
+            onClick={() => onboarding.goToStep(OnboardingStep.AI_PROMPT)}
+            className="flex items-center gap-2 min-h-14 rounded-xl bg-sky-950 px-8 text-lg font-semibold text-white shadow-[0_10px_20px_-14px_rgba(15,23,42,.7)] hover:brightness-[1.35]"
+          >
+            {t("onboarding_nextButton")}
+            <ChevronRight className="inline-block size-5" />
+          </button>
+        </OnboardingFadeIn>
+      )}
+    </div>
+  )
+}
diff --git a/packages/extension/src/components/onboarding/textUtils.tsx b/packages/extension/src/components/onboarding/textUtils.tsx
new file mode 100644
index 00000000..1b0ade40
--- /dev/null
+++ b/packages/extension/src/components/onboarding/textUtils.tsx
@@ -0,0 +1,14 @@
+import { Fragment, type ReactNode } from "react"
+
+// Locale strings use "\n" for line breaks instead of embedding <br> tags
+// directly, so translators editing messages.json only ever see plain text.
+// This converts that "\n" into actual <br> elements at render time.
+export function renderMultiline(text: string): ReactNode {
+  const lines = text.split("\n")
+  return lines.map((line, i) => (
+    <Fragment key={i}>
+      {line}
+      {i < lines.length - 1 && <br />}
+    </Fragment>
+  ))
+}
diff --git a/packages/extension/src/components/onboarding/useOnboardingState.ts b/packages/extension/src/components/onboarding/useOnboardingState.ts
new file mode 100644
index 00000000..90365d08
--- /dev/null
+++ b/packages/extension/src/components/onboarding/useOnboardingState.ts
@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+import { OnboardingStep, StepPhase } from "@/types/onboarding"
+import { ANALYTICS_EVENTS } from "@/services/analytics"
+import { sendOnboardingEvent } from "./onboardingAnalytics"
+import { Settings } from "@/services/settings/settings"
+import { getCurrentLocale } from "@/services/i18n"
+import { VERSION } from "@/const"
+import { closeOnboardingTab } from "./onboardingWindow"
+
+export type UseOnboardingState = ReturnType<typeof useOnboardingState>
+
+// development or e2e build-only escape hatch (`?step=SEARCH&phase=value_shown`) so
+// screenshot/manual-QA tooling can land directly on any step/phase without
+// driving the whole real flow.
+function readStepAndPhaseOverride(): {
+  step: OnboardingStep
+  phase: StepPhase
+} | null {
+  if (!["e2e", "development"].includes(import.meta.env.MODE)) return null
+  const params = new URLSearchParams(window.location.search)
+  const stepParam = params.get("step")
+  if (!stepParam) return null
+
+  const step = OnboardingStep[stepParam as keyof typeof OnboardingStep]
+  if (step === undefined) return null
+
+  const phaseParam = params.get("phase")
+  const phaseValues: string[] = Object.values(StepPhase)
+  const phase =
+    phaseParam && phaseValues.includes(phaseParam)
+      ? (phaseParam as StepPhase)
+      : StepPhase.EXPLAIN
+
+  return { step, phase }
+}
+
+export function useOnboardingState() {
+  const [step, setStep] = useState<OnboardingStep>(
+    () => readStepAndPhaseOverride()?.step ?? OnboardingStep.INTRO,
+  )
+  const [phase, _setPhase] = useState<StepPhase>(
+    () => readStepAndPhaseOverride()?.phase ?? StepPhase.EXPLAIN,
+  )
+  const startedAtRef = useRef<number>(Date.now())
+  const seenValueStepsRef = useRef<Set<OnboardingStep>>(new Set())
+  const seenSelectionStepsRef = useRef<Set<OnboardingStep>>(new Set())
+  const finishedRef = useRef(false)
+  const hasEventSendRef = useRef(false)
+  const phaseTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    return () => {
+      if (phaseTimeoutRef.current != null) {
+        clearTimeout(phaseTimeoutRef.current)
+      }
+    }
+  }, [])
+
+  useEffect(() => {
+    if (hasEventSendRef.current) return
+    hasEventSendRef.current = true
+    sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_START, {
+      locale: getCurrentLocale(),
+      extension_version: VERSION,
+    })
+  }, [])
+
+  const setPhase = useCallback((next: StepPhase, delay?: number) => {
+    if (phaseTimeoutRef.current != null) {
+      clearTimeout(phaseTimeoutRef.current)
+      phaseTimeoutRef.current = null
+    }
+    if (delay) {
+      phaseTimeoutRef.current = setTimeout(() => {
+        phaseTimeoutRef.current = null
+        _setPhase(next)
+      }, delay)
+      return
+    }
+    _setPhase(next)
+  }, [])
+
+  const goToStep = useCallback((next: OnboardingStep) => {
+    if (phaseTimeoutRef.current != null) {
+      clearTimeout(phaseTimeoutRef.current)
+      phaseTimeoutRef.current = null
+    }
+    setStep(next)
+    _setPhase(StepPhase.EXPLAIN)
+  }, [])
+
+  // Fires once per step, the first time that step reaches VALUE_SHOWN -
+  // that phase is each step's "the user got the payoff" moment per the PRD.
+  useEffect(() => {
+    if (phase !== StepPhase.VALUE_SHOWN) return
+    if (seenValueStepsRef.current.has(step)) return
+    seenValueStepsRef.current.add(step)
+    sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_VALUE_REACHED, { step })
+  }, [phase, step])
+
+  // Records the first text/link selection observed within a given step.
+  // No-ops on subsequent selections within the same step.
+  const recordFirstSelection = useCallback((forStep: OnboardingStep) => {
+    if (seenSelectionStepsRef.current.has(forStep)) return
+    seenSelectionStepsRef.current.add(forStep)
+    sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_TEXT_SELECTION, {
+      step: forStep,
+    })
+  }, [])
+
+  const recordCommandExecuted = useCallback(
+    (forStep: OnboardingStep, commandType: string) => {
+      sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_COMMAND_EXECUTE, {
+        command_type: commandType,
+        step: forStep,
+      })
+    },
+    [],
+  )
+
+  const markFinished = useCallback(async () => {
+    if (finishedRef.current) return
+    finishedRef.current = true
+    // Never show the onboarding tab again after this run, whether the user
+    // completed it or skipped partway through. Awaited by callers so the
+    // setting is persisted before the tab closes.
+    await Settings.update("hasShownOnboarding", () => true)
+  }, [])
+
+  // Unlike Complete's "Close" button (a deliberate final step the user
+  // reaches after reading the summary), Skip fires immediately on click, so
+  // there's no natural delay for the settings write to land - explicitly
+  // await it before closing the tab.
+  const skip = useCallback(async () => {
+    sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_SKIP, { step })
+    await markFinished()
+    await closeOnboardingTab()
+  }, [step, markFinished])
+
+  const complete = useCallback(() => {
+    // Guard here too, not just inside markFinished() - StepComplete calls
+    // this from a mount-time useEffect, which StrictMode's dev-only double
+    // effect invocation would otherwise run twice, sending this event twice.
+    if (finishedRef.current) return
+    sendOnboardingEvent(ANALYTICS_EVENTS.ONBOARDING_COMPLETE, {
+      completion_time_sec:
+        Math.round((Date.now() - startedAtRef.current) / 100) / 10,
+    })
+    markFinished()
+  }, [markFinished])
+
+  return {
+    step,
+    phase,
+    setPhase,
+    goToStep,
+    skip,
+    complete,
+    recordFirstSelection,
+    recordCommandExecuted,
+  }
+}
diff --git a/packages/extension/src/components/onboarding/useSelectionDemo.test.ts b/packages/extension/src/components/onboarding/useSelectionDemo.test.ts
new file mode 100644
index 00000000..049feb0d
--- /dev/null
+++ b/packages/extension/src/components/onboarding/useSelectionDemo.test.ts
@@ -0,0 +1,188 @@
+import { describe, it, expect, vi } from "vitest"
+import { renderHook } from "@testing-library/react"
+import { createRef } from "react"
+import {
+  buildKeyframes,
+  useSelectionDemo,
+  type LineRect,
+} from "./useSelectionDemo"
+
+describe("buildKeyframes", () => {
+  const host: LineRect = { x: 0, y: 0, width: 500, height: 200 }
+
+  it("returns an empty array for no lines", () => {
+    expect(buildKeyframes([], host)).toEqual([])
+  })
+
+  it("starts at the line's start and holds at its end for a single line", () => {
+    const line: LineRect = { x: 20, y: 40, width: 300, height: 24 }
+    const frames = buildKeyframes([line], host)
+
+    expect(frames[0]).toEqual({
+      offset: 0,
+      transform: "translate(20px, 40px)",
+      opacity: 1,
+    })
+    const last = frames[frames.length - 1]
+    expect(last).toEqual({
+      offset: 1,
+      transform: "translate(320px, 40px)",
+      opacity: 1,
+    })
+    // Every keyframe stays fully opaque - nothing to hide with one line.
+    expect(frames.every((f) => f.opacity === 1)).toBe(true)
+  })
+
+  it("subtracts the host origin from line coordinates", () => {
+    const shiftedHost: LineRect = { x: 100, y: 50, width: 500, height: 200 }
+    const line: LineRect = { x: 120, y: 90, width: 200, height: 24 }
+    const frames = buildKeyframes([line], shiftedHost)
+
+    expect(frames[0].transform).toBe("translate(20px, 40px)")
+  })
+
+  it("dips opacity to 0 and jumps position between two lines", () => {
+    const lines: LineRect[] = [
+      { x: 0, y: 0, width: 300, height: 24 },
+      { x: 0, y: 30, width: 150, height: 24 },
+    ]
+    const frames = buildKeyframes(lines, host)
+
+    const zeroOpacityFrames = frames.filter((f) => f.opacity === 0)
+    // Two frames dip to opacity 0: end-of-line-1 position, then
+    // start-of-line-2 position, both invisible.
+    expect(zeroOpacityFrames).toHaveLength(2)
+    expect(zeroOpacityFrames[0].transform).toBe("translate(300px, 0px)")
+    expect(zeroOpacityFrames[1].transform).toBe("translate(0px, 30px)")
+
+    // Offsets are non-decreasing, as WAAPI requires.
+    for (let i = 1; i < frames.length; i++) {
+      expect(frames[i].offset as number).toBeGreaterThanOrEqual(
+        frames[i - 1].offset as number,
+      )
+    }
+
+    // Ends on the second line's end position, fully visible.
+    const last = frames[frames.length - 1]
+    expect(last).toEqual({
+      offset: 1,
+      transform: "translate(150px, 30px)",
+      opacity: 1,
+    })
+  })
+
+  it("gives a wider line proportionally more of the movement budget", () => {
+    const lines: LineRect[] = [
+      { x: 0, y: 0, width: 400, height: 24 },
+      { x: 0, y: 30, width: 100, height: 24 },
+    ]
+    const frames = buildKeyframes(lines, host)
+    // First line (400/500 of the width) should reach its end-of-line
+    // keyframe at a larger offset than the short second line's span.
+    const line1End = frames.find(
+      (f) => f.transform === "translate(400px, 0px)",
+    )!
+    // moveFraction = 1 - holdFraction(1200/3000) - gapFraction(0.015) =
+    // 0.585; line1 gets 400/500 of it.
+    expect(line1End.offset as number).toBeCloseTo(0.468, 3)
+  })
+})
+
+describe("useSelectionDemo", () => {
+  it("does nothing when disabled", () => {
+    const textRef = createRef<HTMLElement>()
+    const cursorRef = createRef<HTMLElement>()
+    expect(() =>
+      renderHook(() => useSelectionDemo(textRef, cursorRef, false)),
+    ).not.toThrow()
+  })
+
+  it("no-ops when the refs aren't attached yet", () => {
+    const textRef = createRef<HTMLElement>()
+    const cursorRef = createRef<HTMLElement>()
+    expect(() =>
+      renderHook(() => useSelectionDemo(textRef, cursorRef, true)),
+    ).not.toThrow()
+  })
+
+  it("no-ops in jsdom, which has no Element.animate, and cleans up without throwing", () => {
+    const text = document.createElement("span")
+    const cursor = document.createElement("span")
+    document.body.append(text, cursor)
+    const textRef = { current: text }
+    const cursorRef = { current: cursor }
+
+    // jsdom does not implement the Web Animations API.
+    expect(typeof cursor.animate).not.toBe("function")
+
+    const { unmount } = renderHook(() =>
+      useSelectionDemo(textRef, cursorRef, true),
+    )
+    expect(() => unmount()).not.toThrow()
+
+    text.remove()
+    cursor.remove()
+  })
+
+  it("measures and animates when Element.animate is available", () => {
+    const text = document.createElement("span")
+    text.textContent = "hello"
+    const cursor = document.createElement("span")
+    const host = document.createElement("div")
+    host.append(text, cursor)
+    document.body.append(host)
+
+    const animateSpy = vi.fn().mockReturnValue({ cancel: vi.fn() })
+    // jsdom has no WAAPI; stub it directly on the element under test.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(cursor as any).animate = animateSpy
+    Object.defineProperty(cursor, "offsetParent", {
+      value: host,
+      configurable: true,
+    })
+    vi.spyOn(host, "getBoundingClientRect").mockReturnValue({
+      x: 0,
+      y: 0,
+      width: 100,
+      height: 40,
+      top: 0,
+      left: 0,
+      right: 100,
+      bottom: 40,
+      toJSON: () => ({}),
+    })
+    // jsdom doesn't implement Range.prototype.getClientRects at all (not
+    // just a stub - the property is absent), so vi.spyOn has nothing to
+    // wrap. Assign it directly instead.
+    const originalGetClientRects = Range.prototype.getClientRects
+    Range.prototype.getClientRects = vi.fn().mockReturnValue([
+      {
+        x: 0,
+        y: 0,
+        width: 60,
+        height: 20,
+        top: 0,
+        left: 0,
+        right: 60,
+        bottom: 20,
+        toJSON: () => ({}),
+      },
+    ] as unknown as DOMRectList)
+
+    const textRef = { current: text }
+    const cursorRef = { current: cursor }
+    const { unmount } = renderHook(() =>
+      useSelectionDemo(textRef, cursorRef, true),
+    )
+
+    expect(animateSpy).toHaveBeenCalledTimes(1)
+    const [keyframes, options] = animateSpy.mock.calls[0]
+    expect(keyframes.length).toBeGreaterThan(0)
+    expect(options).toMatchObject({ iterations: Infinity, easing: "linear" })
+
+    unmount()
+    host.remove()
+    Range.prototype.getClientRects = originalGetClientRects
+    vi.restoreAllMocks()
+  })
+})
diff --git a/packages/extension/src/components/onboarding/useSelectionDemo.ts b/packages/extension/src/components/onboarding/useSelectionDemo.ts
new file mode 100644
index 00000000..fa8ffbe9
--- /dev/null
+++ b/packages/extension/src/components/onboarding/useSelectionDemo.ts
@@ -0,0 +1,186 @@
+import { RefObject, useEffect, useRef } from "react"
+
+// A visual-line rect in the coordinate space needed to build keyframes.
+// Deliberately a plain object (not DOMRect) so buildKeyframes() is testable
+// without a DOM.
+export type LineRect = { x: number; y: number; width: number; height: number }
+
+const LINE_MOVE_MS = 900
+const TAIL_HOLD_MS = 1200
+// Fraction of the total animation spent hidden while jumping between two
+// lines - long enough to fully hide the jump, short enough to stay
+// unnoticed as a "flicker" rather than a pause.
+const GAP_FRACTION = 0.015
+
+function clampOffset(offset: number): number {
+  return Math.min(1, Math.max(0, Number(offset.toFixed(4))))
+}
+
+// Builds Web Animations API keyframes that walk an absolutely-positioned
+// cursor element left-to-right along each visual line in `lines` (both
+// `lines` and `host` are in the same coordinate space, typically viewport
+// coordinates from getBoundingClientRect/getClientRects - the caller
+// subtracts nothing, this function does), hiding the jump between lines
+// behind a brief opacity dip so it reads as "the cursor left the page and
+// re-entered at the next line" rather than a teleport.
+//
+// Exported for direct unit testing - this is where the actual geometry
+// logic lives; the hook around it is mostly measurement plumbing.
+export function buildKeyframes(lines: LineRect[], host: LineRect): Keyframe[] {
+  if (lines.length === 0) return []
+
+  const sumWidth = lines.reduce((sum, l) => sum + l.width, 0) || 1
+  const gapCount = lines.length - 1
+  const gapFraction = gapCount > 0 ? GAP_FRACTION : 0
+  const totalMoveMs = LINE_MOVE_MS * lines.length
+  const holdFraction = TAIL_HOLD_MS / (totalMoveMs + TAIL_HOLD_MS)
+  // Remaining budget after the gaps and the tail hold, distributed across
+  // lines proportional to their width so a long line takes longer to
+  // traverse than a short one.
+  const moveFraction = 1 - holdFraction - gapFraction * gapCount
+
+  const frames: Keyframe[] = []
+  let offset = 0
+  let lastTransform = ""
+
+  lines.forEach((line, i) => {
+    const startX = line.x - host.x
+    const endX = line.x + line.width - host.x
+    const y = line.y - host.y
+    const endTransform = `translate(${endX}px, ${y}px)`
+
+    if (frames.length === 0) {
+      frames.push({
+        offset: 0,
+        transform: `translate(${startX}px, ${y}px)`,
+        opacity: 1,
+      })
+    }
+
+    offset += moveFraction * (line.width / sumWidth)
+    frames.push({
+      offset: clampOffset(offset),
+      transform: endTransform,
+      opacity: 1,
+    })
+    lastTransform = endTransform
+
+    const next = lines[i + 1]
+    if (next) {
+      const nextStart = `translate(${next.x - host.x}px, ${next.y - host.y}px)`
+      offset += gapFraction / 2
+      frames.push({
+        offset: clampOffset(offset),
+        transform: endTransform,
+        opacity: 0,
+      })
+      offset += gapFraction / 2
+      frames.push({
+        offset: clampOffset(offset),
+        transform: nextStart,
+        opacity: 0,
+      })
+      frames.push({
+        offset: clampOffset(offset),
+        transform: nextStart,
+        opacity: 1,
+      })
+      lastTransform = nextStart
+    }
+  })
+
+  frames.push({ offset: 1, transform: lastTransform, opacity: 1 })
+  return frames
+}
+
+function rectSignature(rects: DOMRect[]): string {
+  return rects.map((r) => `${r.x | 0},${r.y | 0},${r.width | 0}`).join("|")
+}
+
+// Demonstrates "drag to select" on a loop by measuring the rendered lines of
+// `textRef`'s content at runtime (via Range.getClientRects()) and animating
+// `cursorRef` - an absolutely-positioned I-beam glyph, a sibling of the
+// text, not a child - along them. Runtime measurement (rather than
+// hardcoded pixel keyframes) is what makes this locale-proof: every one of
+// the extension's 14 locales wraps this string differently, and the card is
+// responsive.
+//
+// `cursorRef`'s nearest positioned ancestor (`offsetParent`) is used as the
+// coordinate host, so the caller must give the card itself (or a wrapper
+// around both the text and the cursor) `position: relative`.
+export function useSelectionDemo(
+  textRef: RefObject<HTMLElement | null>,
+  cursorRef: RefObject<HTMLElement | null>,
+  enabled: boolean,
+) {
+  const signatureRef = useRef("")
+  const animationRef = useRef<Animation | null>(null)
+
+  useEffect(() => {
+    const text = textRef.current
+    const cursor = cursorRef.current
+    // `cursor.animate` is absent in jsdom (no test environment implements
+    // WAAPI), which is exactly the no-op we want in tests - no separate
+    // "are we in a test" branch needed.
+    if (!enabled || !text || !cursor || typeof cursor.animate !== "function") {
+      return
+    }
+
+    let cancelled = false
+
+    const measure = () => {
+      if (cancelled) return
+      const host = cursor.offsetParent as HTMLElement | null
+      if (!host) return
+
+      const range = document.createRange()
+      range.selectNodeContents(text)
+      const rects = Array.from(range.getClientRects()).filter(
+        (r) => r.width > 0.5 && r.height > 0.5,
+      )
+      // Empty when the card is hidden or not laid out yet. No-op and wait
+      // for the ResizeObserver below to fire once a box appears - don't
+      // cancel any animation already running from a prior measurement.
+      if (rects.length === 0) return
+
+      const signature = rectSignature(rects)
+      if (signature === signatureRef.current && animationRef.current) return
+      signatureRef.current = signature
+
+      const hostRect = host.getBoundingClientRect()
+      const keyframes = buildKeyframes(rects, hostRect)
+      if (keyframes.length === 0) return
+
+      animationRef.current?.cancel()
+      animationRef.current = cursor.animate(keyframes, {
+        duration: LINE_MOVE_MS * rects.length + TAIL_HOLD_MS,
+        iterations: Infinity,
+        easing: "linear",
+      })
+    }
+
+    const scheduleMeasure = () => {
+      requestAnimationFrame(measure)
+    }
+
+    // Observe the card (the text's parent), not the cursor itself - the
+    // cursor is `position: absolute; pointer-events: none`, so it can never
+    // affect the card's box and therefore can't create a resize-observer
+    // feedback loop.
+    const ro = new ResizeObserver(scheduleMeasure)
+    ro.observe(text.parentElement ?? text)
+
+    measure()
+    // Re-measure once webfonts finish loading - a late font swap can change
+    // line-wrap points after the first measurement.
+    document.fonts?.ready?.then(scheduleMeasure)
+
+    return () => {
+      cancelled = true
+      ro.disconnect()
+      animationRef.current?.cancel()
+      animationRef.current = null
+      signatureRef.current = ""
+    }
+  }, [enabled, textRef, cursorRef])
+}
diff --git a/packages/extension/src/components/option/ImportExport.tsx b/packages/extension/src/components/option/ImportExport.tsx
index c894f5d1..3b9b218a 100644
--- a/packages/extension/src/components/option/ImportExport.tsx
+++ b/packages/extension/src/components/option/ImportExport.tsx
@@ -270,6 +270,7 @@ export function ImportExport() {
           hasShownReviewRequest = false,
           hasDismissedPromptHistoryBanner = false,
           hasShownHubShareToast = false,
+          hasShownOnboarding = false,
         } = await enhancedSettings.get()
         const data = await migrate({
           ...importJson,
@@ -277,6 +278,7 @@ export function ImportExport() {
           hasShownReviewRequest,
           hasDismissedPromptHistoryBanner,
           hasShownHubShareToast,
+          hasShownOnboarding,
           stars: [],
         })
         await Settings.set(data)
diff --git a/packages/extension/src/components/option/Option.tsx b/packages/extension/src/components/option/Option.tsx
index 87b3d1f0..af785e07 100644
--- a/packages/extension/src/components/option/Option.tsx
+++ b/packages/extension/src/components/option/Option.tsx
@@ -7,6 +7,7 @@ import { APP_ID, VERSION, SCREEN } from "@/const"
 import { ANALYTICS_EVENTS, sendEvent } from "@/services/analytics"
 
 import { Popup } from "@/components/Popup"
+import { SelectContextProvider } from "@/providers/SelectContextProvider"
 import { TableOfContents } from "@/components/option/TableOfContents"
 import { ImportExport } from "@/components/option/ImportExport"
 import { UserSupport } from "@/components/option/UserSupport"
@@ -93,11 +94,13 @@ export function Option() {
               ref={setPreviewElm}
               style={{ marginBottom: Math.max(popupHeight + 5, 30) }}
             >
-              <Popup
-                positionElm={previewElm}
-                isPreview={true}
-                ref={setPopupElm}
-              />
+              <SelectContextProvider>
+                <Popup
+                  positionElm={previewElm}
+                  isPreview={true}
+                  ref={setPopupElm}
+                />
+              </SelectContextProvider>
             </div>
             <div className="pt-3">
               <HubBanner />
diff --git a/packages/extension/src/const.ts b/packages/extension/src/const.ts
index 3fc9ffd7..799bdba4 100644
--- a/packages/extension/src/const.ts
+++ b/packages/extension/src/const.ts
@@ -271,6 +271,7 @@ export enum SCREEN {
   SERVICE_WORKER = "ServiceWorker",
   COMMAND_HUB = "CommandHub",
   COMMAND_FORM = "CommandForm",
+  ONBOARDING = "Onboarding",
 }
 
 export const POPUP_OPTION = {
@@ -384,6 +385,8 @@ export const PAGE_HTML_MAX_CHARS = 1_000_000
 
 export const OPTION_PAGE_PATH = "src/options_page.html"
 
+export const ONBOARDING_PAGE_PATH = "src/onboarding_page.html"
+
 export const COMMAND_USAGE = {
   REVIEW_THRESHOLD: 100,
   REVIEW_INTERVAL: 50,
diff --git a/packages/extension/src/content_script.tsx b/packages/extension/src/content_script.tsx
index 3a978a65..06bb51ff 100644
--- a/packages/extension/src/content_script.tsx
+++ b/packages/extension/src/content_script.tsx
@@ -22,25 +22,31 @@ try {
     </ErrorBoundary>,
   )
 
-  const insertCss = (elm: ShadowRoot, filePath: string) => {
+  const insertCss = async (elm: ShadowRoot, filePath: string) => {
     const url = chrome.runtime.getURL(filePath)
-    fetch(url)
-      .then((res) => res.text())
-      .then((css) => {
-        const style = document.createElement("style")
-        style.append(document.createTextNode(css))
-        elm.insertBefore(style, elm.firstChild)
-      })
-      .catch((error) => {
-        console.error(`Failed to load CSS file: ${filePath}`, error)
-        Sentry.captureException(error)
-      })
+    try {
+      const css = await (await fetch(url)).text()
+      const style = document.createElement("style")
+      style.append(document.createTextNode(css))
+      elm.insertBefore(style, elm.firstChild)
+    } catch (error) {
+      console.error(`Failed to load CSS file: ${filePath}`, error)
+      Sentry.captureException(error)
+    }
   }
 
   if (!isDebug) {
-    // Putting styles into ShadowDom
-    insertCss(shadow, "/assets/components.css")
-    insertCss(shadow, "/assets/content_script.css")
+    // Putting styles into ShadowDom.
+    // The exact set of CSS files that content_script.tsx depends on can be
+    // split across multiple content-hashed chunks (e.g. components shared
+    // with other entry points), so __CONTENT_SCRIPT_CSS_FILES__ is a
+    // placeholder swapped for the real file list after the build finishes
+    // hashing chunks, instead of hardcoding filenames here.
+    ;(async () => {
+      for (const filePath of __CONTENT_SCRIPT_CSS_FILES__) {
+        await insertCss(shadow, `/${filePath}`)
+      }
+    })()
   }
 
   // Hide the rootDom while printing.
diff --git a/packages/extension/src/hooks/pageAction/usePageActionRunner.ts b/packages/extension/src/hooks/pageAction/usePageActionRunner.ts
index fb1872da..3a97f6ea 100644
--- a/packages/extension/src/hooks/pageAction/usePageActionRunner.ts
+++ b/packages/extension/src/hooks/pageAction/usePageActionRunner.ts
@@ -15,11 +15,13 @@ export function usePageActionRunner() {
 
   useEffect(() => {
     const listener = (param: any, _sender: any, response: any) => {
+      console.debug("Received TabCommand.execPageAction:", param)
       execute(param).then((result) => {
         response(result)
       })
       return true
     }
+    console.debug("Adding listener for TabCommand.execPageAction")
     Ipc.addListener(TabCommand.execPageAction, listener)
     return () => {
       Ipc.removeListener(TabCommand.execPageAction)
diff --git a/packages/extension/src/hooks/useDetectLinkCommand.ts b/packages/extension/src/hooks/useDetectLinkCommand.ts
index 9ca6965a..7cbda806 100644
--- a/packages/extension/src/hooks/useDetectLinkCommand.ts
+++ b/packages/extension/src/hooks/useDetectLinkCommand.ts
@@ -21,6 +21,10 @@ import {
 } from "@/services/dom"
 import { getScreenSize } from "@/services/screen"
 import { sendEvent, ANALYTICS_EVENTS } from "@/services/analytics"
+import {
+  dispatchCommandExecuted,
+  isOnboardingPage,
+} from "@/components/onboarding/onboardingEvents"
 
 const isTargetEvent = (e: MouseEvent): boolean => {
   return (
@@ -40,8 +44,7 @@ type DetectLinkCommandReturn = {
 }
 
 type SubHookReturn =
-  | Omit<DetectLinkCommandReturn, "showIndicator">
-  | Record<string, never>
+  Omit<DetectLinkCommandReturn, "showIndicator"> | Record<string, never>
 
 const empty = {
   inProgress: false,
@@ -77,7 +80,16 @@ export function useDetectLinkCommand(): DetectLinkCommandReturn {
         changeState: onChangeState,
         target,
       })
-      sendEvent(ANALYTICS_EVENTS.LINK_COMMAND, { event_label: "link_preview" })
+
+      if (!isOnboardingPage(location.href)) {
+        sendEvent(ANALYTICS_EVENTS.LINK_COMMAND, {
+          event_label: "link_preview",
+        })
+      }
+      dispatchCommandExecuted({
+        commandId: command.id,
+        commandType: command.openMode,
+      })
     },
     [command],
   )
diff --git a/packages/extension/src/hooks/usePopupContext.tsx b/packages/extension/src/hooks/usePopupContext.tsx
new file mode 100644
index 00000000..d531f7f1
--- /dev/null
+++ b/packages/extension/src/hooks/usePopupContext.tsx
@@ -0,0 +1,16 @@
+import { createContext, useContext } from "react"
+import { SIDE, ALIGN } from "@/const"
+
+export type ContextType = {
+  isPreview?: boolean
+  inTransition?: boolean
+  inOnboarding?: boolean
+  side: SIDE
+  align: ALIGN
+}
+
+export const popupContext = createContext<ContextType>({} as ContextType)
+
+export const usePopupContext = () => {
+  return useContext(popupContext)
+}
diff --git a/packages/extension/src/hooks/usePrefersReducedMotion.ts b/packages/extension/src/hooks/usePrefersReducedMotion.ts
new file mode 100644
index 00000000..6ea3451b
--- /dev/null
+++ b/packages/extension/src/hooks/usePrefersReducedMotion.ts
@@ -0,0 +1,28 @@
+import { useEffect, useState } from "react"
+
+const QUERY = "(prefers-reduced-motion: reduce)"
+
+// Tracks the OS-level "reduce motion" preference. Tailwind's `motion-reduce:`
+// variant already handles CSS-only animations, but JS-driven effects (the
+// selection demo's Web Animations API keyframes, the confetti burst) need
+// this to decide whether to run at all.
+export function usePrefersReducedMotion(): boolean {
+  const [prefersReduced, setPrefersReduced] = useState(
+    () => typeof window !== "undefined" && window.matchMedia(QUERY).matches,
+  )
+
+  useEffect(() => {
+    const mql = window.matchMedia(QUERY)
+    const onChange = () => setPrefersReduced(mql.matches)
+
+    if (mql.addEventListener) {
+      mql.addEventListener("change", onChange)
+      return () => mql.removeEventListener("change", onChange)
+    }
+    // Safari < 14 fallback.
+    mql.addListener(onChange)
+    return () => mql.removeListener(onChange)
+  }, [])
+
+  return prefersReduced
+}
diff --git a/packages/extension/src/hooks/useSelectContext.tsx b/packages/extension/src/hooks/useSelectContext.tsx
index 8b938a25..0dccca81 100644
--- a/packages/extension/src/hooks/useSelectContext.tsx
+++ b/packages/extension/src/hooks/useSelectContext.tsx
@@ -2,8 +2,10 @@ import { createContext, useContext } from "react"
 
 export type ContextType = {
   selectionText: string
+  setSelectionText: (text: string) => void
   target: Element | null
   setTarget: (elm: Element | null) => void
+  setDetectSelectionEnabled: (enabled: boolean) => void
 }
 
 export const selectContext = createContext<ContextType>({} as ContextType)
diff --git a/packages/extension/src/hooks/useSettings.test.tsx b/packages/extension/src/hooks/useSettings.test.tsx
index 15888080..a8d8d46b 100644
--- a/packages/extension/src/hooks/useSettings.test.tsx
+++ b/packages/extension/src/hooks/useSettings.test.tsx
@@ -376,6 +376,7 @@ describe("useSettings hooks", () => {
         hasShownReviewRequest: false,
         hasDismissedPromptHistoryBanner: false,
         hasShownHubShareToast: false,
+        hasShownOnboarding: false,
       } as SettingsType
 
       mockEnhancedSettings.getSection.mockResolvedValueOnce(mockSettings)
@@ -696,6 +697,7 @@ describe("useSettings hooks", () => {
         hasShownReviewRequest: false,
         hasDismissedPromptHistoryBanner: false,
         hasShownHubShareToast: false,
+        hasShownOnboarding: false,
       } as SettingsType
 
       mockEnhancedSettings.getSection.mockResolvedValueOnce(mockSettings)
diff --git a/packages/extension/src/lib/contentScriptCss.ts b/packages/extension/src/lib/contentScriptCss.ts
new file mode 100644
index 00000000..a66f4928
--- /dev/null
+++ b/packages/extension/src/lib/contentScriptCss.ts
@@ -0,0 +1,8 @@
+// Placeholder token embedded into the built content_script bundle via Vite's
+// `define`, then swapped for the real CSS file list in the emitted JS asset
+// by removeCssFromContentScript's writeBundle hook (see vite-plugin-manifest.ts).
+// The real list isn't known until crxjs finishes hashing chunks, so it can't
+// be supplied through `define` directly - same approach as vite-plugin-pwa's
+// `self.__WB_MANIFEST` injection.
+export const CONTENT_SCRIPT_CSS_PLACEHOLDER =
+  "__CONTENT_SCRIPT_CSS_FILES_PLACEHOLDER__"
diff --git a/packages/extension/src/lib/vite-plugin-manifest.ts b/packages/extension/src/lib/vite-plugin-manifest.ts
index 82cd1e19..94a2cd44 100644
--- a/packages/extension/src/lib/vite-plugin-manifest.ts
+++ b/packages/extension/src/lib/vite-plugin-manifest.ts
@@ -1,6 +1,31 @@
 import type { Plugin } from "vite"
 import type { OutputAsset } from "rollup"
 import fs from "node:fs"
+import path from "node:path"
+import { CONTENT_SCRIPT_CSS_PLACEHOLDER } from "./contentScriptCss"
+
+// Swaps the CONTENT_SCRIPT_CSS_PLACEHOLDER array literal embedded in the
+// built JS for the real content_script CSS file list. The list isn't known
+// until crxjs finishes hashing chunks, so it can't be supplied via Vite's
+// `define` directly - instead we patch it into whichever emitted chunk
+// contains the placeholder, the same way vite-plugin-pwa injects its
+// `self.__WB_MANIFEST` precache list.
+function injectContentScriptCssFiles(distDir: string, cssFiles: string[]) {
+  const assetsDir = path.join(distDir, "assets")
+  const placeholderPattern = new RegExp(
+    `\\[\\s*["']${CONTENT_SCRIPT_CSS_PLACEHOLDER}["']\\s*\\]`,
+  )
+  for (const fileName of fs.readdirSync(assetsDir)) {
+    if (!fileName.endsWith(".js")) continue
+    const filePath = path.join(assetsDir, fileName)
+    const code = fs.readFileSync(filePath, "utf-8")
+    if (!placeholderPattern.test(code)) continue
+    fs.writeFileSync(
+      filePath,
+      code.replace(placeholderPattern, JSON.stringify(cssFiles)),
+    )
+  }
+}
 
 export default function removeCssFromContentScript(): Plugin {
   return {
@@ -22,6 +47,18 @@ export default function removeCssFromContentScript(): Plugin {
         // content_script.tsx injects CSS manually into its Shadow root, so
         // manifest-level CSS injection must be suppressed.
         for (const cs of content_scripts) {
+          // content_script.tsx's own CSS graph can be split across multiple
+          // chunks (e.g. shared components also used by other entry points
+          // end up in separate, content-hashed CSS files). Hand the exact
+          // list crxjs computed to content_script.tsx by patching it into
+          // the built bundle, instead of relying on hardcoded, hash-fragile
+          // filenames.
+          if (
+            cs.css &&
+            cs.js?.some((f: string) => f.includes("content_script.tsx"))
+          ) {
+            injectContentScriptCssFiles("./dist", cs.css)
+          }
           delete cs.css
         }
 
diff --git a/packages/extension/src/onboarding_page.html b/packages/extension/src/onboarding_page.html
new file mode 100644
index 00000000..44054244
--- /dev/null
+++ b/packages/extension/src/onboarding_page.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html translate="no">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+    <title>Onboarding</title>
+  </head>
+
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <script type="module" src="/src/onboarding_page.tsx"></script>
+  </body>
+</html>
diff --git a/packages/extension/src/onboarding_page.tsx b/packages/extension/src/onboarding_page.tsx
new file mode 100644
index 00000000..65c8c593
--- /dev/null
+++ b/packages/extension/src/onboarding_page.tsx
@@ -0,0 +1,32 @@
+import React from "react"
+import ReactDOM from "react-dom/client"
+import { OnboardingPage } from "@/components/onboarding/OnboardingPage"
+import { getCurrentLocale } from "@/services/i18n"
+import { initSentry, Sentry, ErrorBoundary } from "@/lib/sentry"
+
+import "@/components/global.css"
+import "@/components/Animation.css"
+
+// Initialize Sentry for the onboarding page
+initSentry().catch((error) => {
+  console.error("Failed to initialize Sentry in onboarding page:", error)
+})
+
+// Set the document language to the current locale
+document.documentElement.lang = getCurrentLocale()
+
+const root = document.getElementById("root")
+if (root) {
+  try {
+    ReactDOM.createRoot(root).render(
+      <React.StrictMode>
+        <ErrorBoundary>
+          <OnboardingPage />
+        </ErrorBoundary>
+      </React.StrictMode>,
+    )
+  } catch (error) {
+    console.error("Failed to render onboarding page:", error)
+    Sentry.captureException(error as Error)
+  }
+}
diff --git a/packages/extension/src/providers/SelectContextProvider.tsx b/packages/extension/src/providers/SelectContextProvider.tsx
index d9572828..4d32291c 100644
--- a/packages/extension/src/providers/SelectContextProvider.tsx
+++ b/packages/extension/src/providers/SelectContextProvider.tsx
@@ -1,26 +1,25 @@
-import { useState, ReactNode, useEffect } from "react"
+import { useState, ReactNode, useEffect, useCallback } from "react"
 import { Storage, SESSION_STORAGE_KEY } from "@/services/storage"
 import { getSelectionText } from "@/services/dom"
 import { ContextType, selectContext } from "@/hooks/useSelectContext"
 
 export const SelectContextProvider = ({
   children,
-  isPopupHover,
 }: {
   children: ReactNode
-  isPopupHover: boolean
 }) => {
   const [selectionText, _setSelectionText] = useState("")
   const [target, setTarget] = useState<Element | null>(null)
+  const [detectSelectionEnabled, setDetectSelectionEnabled] = useState(true)
 
-  useEffect(() => {
-    const setSelectionText = async (text: string) => {
-      _setSelectionText(text)
-      await Storage.set<string>(SESSION_STORAGE_KEY.SELECTION_TEXT, text)
-    }
+  const setSelectionText = useCallback(async (text: string) => {
+    _setSelectionText(text)
+    await Storage.set<string>(SESSION_STORAGE_KEY.SELECTION_TEXT, text)
+  }, [])
 
+  useEffect(() => {
     const onSelectionchange = async () => {
-      if (isPopupHover) return
+      if (!detectSelectionEnabled) return
       const text = getSelectionText()
       await setSelectionText(text)
     }
@@ -29,12 +28,14 @@ export const SelectContextProvider = ({
     return () => {
       document.removeEventListener("selectionchange", onSelectionchange)
     }
-  }, [isPopupHover])
+  }, [detectSelectionEnabled, setSelectionText])
 
   const value: ContextType = {
     selectionText,
+    setSelectionText,
     target,
     setTarget,
+    setDetectSelectionEnabled,
   }
 
   return (
diff --git a/packages/extension/src/services/analytics.test.ts b/packages/extension/src/services/analytics.test.ts
index 74040f23..de2de477 100644
--- a/packages/extension/src/services/analytics.test.ts
+++ b/packages/extension/src/services/analytics.test.ts
@@ -26,6 +26,23 @@ describe("getCommandCreateEvent", () => {
   })
 })
 
+describe("ANALYTICS_EVENTS onboarding events", () => {
+  it("defines the event names used by the onboarding flow", () => {
+    expect(ANALYTICS_EVENTS.ONBOARDING_START).toBe("onboarding_start")
+    expect(ANALYTICS_EVENTS.ONBOARDING_SKIP).toBe("onboarding_skip")
+    expect(ANALYTICS_EVENTS.ONBOARDING_TEXT_SELECTION).toBe(
+      "onboarding_text_selection",
+    )
+    expect(ANALYTICS_EVENTS.ONBOARDING_COMMAND_EXECUTE).toBe(
+      "onboarding_command_execute",
+    )
+    expect(ANALYTICS_EVENTS.ONBOARDING_VALUE_REACHED).toBe(
+      "onboarding_value_reached",
+    )
+    expect(ANALYTICS_EVENTS.ONBOARDING_COMPLETE).toBe("onboarding_complete")
+  })
+})
+
 describe("getHubAddEvent", () => {
   it.each([
     [OPEN_MODE.POPUP, ANALYTICS_EVENTS.HUB_ADD_SEARCH],
diff --git a/packages/extension/src/services/analytics.ts b/packages/extension/src/services/analytics.ts
index 58c92607..6f7ae25b 100644
--- a/packages/extension/src/services/analytics.ts
+++ b/packages/extension/src/services/analytics.ts
@@ -48,6 +48,13 @@ export const ANALYTICS_EVENTS = {
   COMMAND_EDIT: "command_edit",
   COMMAND_REMOVE: "command_remove",
   COMMAND_SHARE: "command_share",
+  // Onboarding events, used to track user progress through the onboarding flow.
+  ONBOARDING_START: "onboarding_start",
+  ONBOARDING_SKIP: "onboarding_skip",
+  ONBOARDING_TEXT_SELECTION: "onboarding_text_selection",
+  ONBOARDING_COMMAND_EXECUTE: "onboarding_command_execute",
+  ONBOARDING_VALUE_REACHED: "onboarding_value_reached",
+  ONBOARDING_COMPLETE: "onboarding_complete",
 } as const
 
 export type AnalyticsEventName =
diff --git a/packages/extension/src/services/ipc.ts b/packages/extension/src/services/ipc.ts
index ee859f60..ea8d3c9f 100644
--- a/packages/extension/src/services/ipc.ts
+++ b/packages/extension/src/services/ipc.ts
@@ -30,6 +30,7 @@ export enum BgCommand {
   getTabId = "getTabId",
   getActiveTabId = "getActiveTabId",
   setClipboard = "setClipboard",
+  closeTab = "closeTab",
   // Hub
   shareCommandToHub = "shareCommandToHub",
   editCommandToHub = "editCommandToHub",
@@ -380,8 +381,9 @@ export const Ipc = {
    * @returns Array of responses from each tab
    */
   async sendAllTab(command: IpcCommand, param?: unknown): Promise<any[]> {
+    const onboardingUrl = chrome.runtime.getURL("src/onboarding_page.html")
     const tabs = await chrome.tabs.query({
-      url: ["http://*/*", "https://*/*"],
+      url: ["http://*/*", "https://*/*", `${onboardingUrl}*`],
     })
     const ps = tabs
       .filter(
diff --git a/packages/extension/src/services/option/defaultSettings.test.ts b/packages/extension/src/services/option/defaultSettings.test.ts
index afc48198..a7bb1f2d 100644
--- a/packages/extension/src/services/option/defaultSettings.test.ts
+++ b/packages/extension/src/services/option/defaultSettings.test.ts
@@ -8,6 +8,7 @@ import { isLinkCommand } from "@/lib/utils"
 import { INSERT, toInsertTemplate } from "@/services/pageAction"
 import { getAiServicesFallback } from "@/services/aiPrompt"
 import { COMMAND_SOURCE_TYPE, COMMAND_SOURCE_ID } from "@/const"
+import { ONBOARDING_AI_PROMPT_COMMAND_ID } from "@/components/onboarding/onboardingCommand"
 
 const SYM_SELECTED_TEXT = toInsertTemplate(INSERT.SELECTED_TEXT)
 const SYM_URL = toInsertTemplate(INSERT.URL)
@@ -296,4 +297,18 @@ describe("getDefaultCommands", () => {
       expect((cmd as any).searchUrl).toContain("%pageUrl")
     }
   })
+
+  it("DS-25: all locale command sets should include the onboarding AiPrompt command", () => {
+    for (const locale of ALL_LOCALES) {
+      const commands = getDefaultCommands(locale)
+      const cmd = commands.find((c) => c.id === ONBOARDING_AI_PROMPT_COMMAND_ID)
+      expect(
+        cmd,
+        `Missing onboarding AiPrompt command for locale: ${locale}`,
+      ).toBeDefined()
+      expect((cmd as any).openMode).toBe("aiPrompt")
+      expect((cmd as any).aiPromptOption.prompt).toContain(SYM_SELECTED_TEXT)
+      expect((cmd as any).parentFolderId).toBeUndefined()
+    }
+  })
 })
diff --git a/packages/extension/src/services/option/defaultSettings.ts b/packages/extension/src/services/option/defaultSettings.ts
index aa50c24f..1d33be04 100644
--- a/packages/extension/src/services/option/defaultSettings.ts
+++ b/packages/extension/src/services/option/defaultSettings.ts
@@ -19,6 +19,7 @@ import {
   COMMAND_SOURCE_ID,
 } from "@/const"
 import { getAiServicesFallback } from "@/services/aiPromptFallback"
+import { createOnboardingAiPromptCommands } from "@/components/onboarding/onboardingCommand"
 
 // Derive icon URLs from ai-services.json (single source of truth)
 const _aiServices = getAiServicesFallback()
@@ -67,6 +68,7 @@ export const emptySettings: SettingsType = {
   hasShownReviewRequest: false,
   hasDismissedPromptHistoryBanner: false,
   hasShownHubShareToast: false,
+  hasShownOnboarding: false,
   shortcuts: { shortcuts: [] },
   windowOption: {
     sidePanelAutoHide: false,
@@ -204,6 +206,28 @@ export const PopupOption = {
   height: 700,
 }
 
+// Onboarding's Step2 AiPrompt command (see src/components/onboarding/).
+// Kept as a normal, permanent default command per locale rather than being
+// injected/removed around the onboarding flow. Per-locale title/prompt text
+// lives in onboardingCommand.ts; only the AI-service icon is resolved here.
+// Declared here (before DefaultCommands/LOCALE_COMMANDS use them below)
+// since `const` bindings are not hoisted.
+const ONBOARDING_AI_COMMANDS = createOnboardingAiPromptCommands()
+const CMD_ONBOARDING_AI_EN = ONBOARDING_AI_COMMANDS.en
+const CMD_ONBOARDING_AI_JA = ONBOARDING_AI_COMMANDS.ja
+const CMD_ONBOARDING_AI_ZH = ONBOARDING_AI_COMMANDS.zh
+const CMD_ONBOARDING_AI_KO = ONBOARDING_AI_COMMANDS.ko
+const CMD_ONBOARDING_AI_RU = ONBOARDING_AI_COMMANDS.ru
+const CMD_ONBOARDING_AI_DE = ONBOARDING_AI_COMMANDS.de
+const CMD_ONBOARDING_AI_FR = ONBOARDING_AI_COMMANDS.fr
+const CMD_ONBOARDING_AI_ES = ONBOARDING_AI_COMMANDS.es
+const CMD_ONBOARDING_AI_PT_BR = ONBOARDING_AI_COMMANDS["pt-br"]
+const CMD_ONBOARDING_AI_PT = ONBOARDING_AI_COMMANDS.pt
+const CMD_ONBOARDING_AI_HI = ONBOARDING_AI_COMMANDS.hi
+const CMD_ONBOARDING_AI_ID = ONBOARDING_AI_COMMANDS.id
+const CMD_ONBOARDING_AI_MS = ONBOARDING_AI_COMMANDS.ms
+const CMD_ONBOARDING_AI_IT = ONBOARDING_AI_COMMANDS.it
+
 export const DefaultCommands = [
   {
     id: "$$drag-1",
@@ -230,6 +254,7 @@ export const DefaultCommands = [
     },
     spaceEncoding: SPACE_ENCODING.PLUS,
   },
+  CMD_ONBOARDING_AI_EN,
   {
     id: "26c47b36-c3c8-528c-9ad2-c972dfc6f4df",
     revision: 0,
@@ -1818,6 +1843,7 @@ export const LOCALE_COMMANDS = {
   ja: [
     CMD_LINK_PREVIEW,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_JA,
     CMD_GOOGLE_IMAGE,
     CMD_AMAZON_JP,
     CMD_YAHOO_JAPAN,
@@ -1836,6 +1862,7 @@ export const LOCALE_COMMANDS = {
     CMD_LINK_PREVIEW,
     CMD_BAIDU,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_ZH,
     CMD_GOOGLE_IMAGE,
     CMD_JD,
     CMD_GEMINI_ZH,
@@ -1852,6 +1879,7 @@ export const LOCALE_COMMANDS = {
     CMD_LINK_PREVIEW,
     CMD_NAVER,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_KO,
     CMD_GOOGLE_IMAGE,
     CMD_COUPANG,
     CMD_GEMINI_KO,
@@ -1868,6 +1896,7 @@ export const LOCALE_COMMANDS = {
     CMD_LINK_PREVIEW,
     CMD_YANDEX,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_RU,
     CMD_GOOGLE_IMAGE,
     CMD_OZON,
     CMD_WILDBERRIES,
@@ -1884,6 +1913,7 @@ export const LOCALE_COMMANDS = {
   de: [
     CMD_LINK_PREVIEW,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_DE,
     CMD_GOOGLE_IMAGE,
     CMD_AMAZON_DE,
     CMD_EBAY_DE,
@@ -1900,6 +1930,7 @@ export const LOCALE_COMMANDS = {
   fr: [
     CMD_LINK_PREVIEW,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_FR,
     CMD_GOOGLE_IMAGE,
     CMD_AMAZON_FR,
     CMD_LEBONCOIN,
@@ -1916,6 +1947,7 @@ export const LOCALE_COMMANDS = {
   es: [
     CMD_LINK_PREVIEW,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_ES,
     CMD_GOOGLE_IMAGE,
     CMD_AMAZON_ES,
     CMD_EBAY_ES,
@@ -1934,6 +1966,7 @@ export const LOCALE_COMMANDS = {
   "pt-br": [
     CMD_LINK_PREVIEW,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_PT_BR,
     CMD_GOOGLE_IMAGE,
     CMD_AMAZON_BR,
     CMD_MERCADO_LIVRE_BR,
@@ -1950,6 +1983,7 @@ export const LOCALE_COMMANDS = {
   pt: [
     CMD_LINK_PREVIEW,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_PT,
     CMD_GOOGLE_IMAGE,
     CMD_AMAZON_ES,
     CMD_OLX_PT,
@@ -1966,6 +2000,7 @@ export const LOCALE_COMMANDS = {
   hi: [
     CMD_LINK_PREVIEW,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_HI,
     CMD_GOOGLE_IMAGE,
     CMD_AMAZON_IN,
     CMD_FLIPKART,
@@ -1982,6 +2017,7 @@ export const LOCALE_COMMANDS = {
   id: [
     CMD_LINK_PREVIEW,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_ID,
     CMD_GOOGLE_IMAGE,
     CMD_TOKOPEDIA,
     CMD_SHOPEE_ID,
@@ -1998,6 +2034,7 @@ export const LOCALE_COMMANDS = {
   ms: [
     CMD_LINK_PREVIEW,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_MS,
     CMD_GOOGLE_IMAGE,
     CMD_SHOPEE_MY,
     CMD_LAZADA_MY,
@@ -2014,6 +2051,7 @@ export const LOCALE_COMMANDS = {
   it: [
     CMD_LINK_PREVIEW,
     CMD_GOOGLE,
+    CMD_ONBOARDING_AI_IT,
     CMD_GOOGLE_IMAGE,
     CMD_AMAZON_IT,
     CMD_EBAY_IT,
diff --git a/packages/extension/src/services/pageAction/dispatcher.ts b/packages/extension/src/services/pageAction/dispatcher.ts
index 6d310a91..ba75cd9e 100644
--- a/packages/extension/src/services/pageAction/dispatcher.ts
+++ b/packages/extension/src/services/pageAction/dispatcher.ts
@@ -15,6 +15,7 @@ export const PageActionDispatcher = {
   },
 
   click: async (param: PageAction.Click): ActionReturn => {
+    console.debug(`Clicking element: ${param.label} (${param.selector})`)
     if (param.condition) {
       const { skip, error } = await resolveClickCondition(
         param.condition,
diff --git a/packages/extension/src/services/pageAction/elementWait.ts b/packages/extension/src/services/pageAction/elementWait.ts
index 19d6d4ea..757b2bc3 100644
--- a/packages/extension/src/services/pageAction/elementWait.ts
+++ b/packages/extension/src/services/pageAction/elementWait.ts
@@ -103,6 +103,7 @@ export function evaluateCondition(
   conditionType: PAGE_ACTION_CONDITION_TYPE,
   element: HTMLElement | null,
 ): boolean {
+  console.debug(`Evaluating condition ${conditionType} for element`, element)
   switch (conditionType) {
     case PAGE_ACTION_CONDITION_TYPE.empty:
       return element == null || isEmpty(getElementText(element))
diff --git a/packages/extension/src/services/pageAction/index.ts b/packages/extension/src/services/pageAction/index.ts
index 2a5fec79..53bda2fb 100644
--- a/packages/extension/src/services/pageAction/index.ts
+++ b/packages/extension/src/services/pageAction/index.ts
@@ -5,25 +5,4 @@ export type { PageAction } from "./dispatcher"
 export { RunningStatus } from "./status"
 export * from "./helper"
 export { PAGE_HTML_MAX_CHARS } from "@/const"
-
-export enum INSERT {
-  SELECTED_TEXT = "selectedText",
-  URL = "url",
-  CLIPBOARD = "clipboard",
-  LANG = "lang",
-  PAGE_HTML = "pageHtml",
-  SELECTION_HTML = "selectionHtml",
-}
-
-export const InsertSymbol = {
-  [INSERT.SELECTED_TEXT]: "SelectedText",
-  [INSERT.URL]: "Url",
-  [INSERT.CLIPBOARD]: "Clipboard",
-  [INSERT.LANG]: "Lang",
-  [INSERT.PAGE_HTML]: "PageHtml",
-  [INSERT.SELECTION_HTML]: "SelectionHtml",
-}
-
-/** Returns the template placeholder string for a given INSERT key, e.g. "{{Clipboard}}" */
-export const toInsertTemplate = (key: INSERT): string =>
-  `{{${InsertSymbol[key]}}}`
+export * from "./insertSymbols"
diff --git a/packages/extension/src/services/pageAction/insertSymbols.ts b/packages/extension/src/services/pageAction/insertSymbols.ts
new file mode 100644
index 00000000..eeb45c5f
--- /dev/null
+++ b/packages/extension/src/services/pageAction/insertSymbols.ts
@@ -0,0 +1,26 @@
+// Kept in their own module, separate from index.ts's barrel exports, so
+// callers that only need these template-placeholder symbols (e.g.
+// onboardingCommand.ts) don't have to pull in listener.ts's side effect of
+// registering a chrome.runtime.onMessage listener at import time (via
+// @/services/ipc).
+export enum INSERT {
+  SELECTED_TEXT = "selectedText",
+  URL = "url",
+  CLIPBOARD = "clipboard",
+  LANG = "lang",
+  PAGE_HTML = "pageHtml",
+  SELECTION_HTML = "selectionHtml",
+}
+
+export const InsertSymbol = {
+  [INSERT.SELECTED_TEXT]: "SelectedText",
+  [INSERT.URL]: "Url",
+  [INSERT.CLIPBOARD]: "Clipboard",
+  [INSERT.LANG]: "Lang",
+  [INSERT.PAGE_HTML]: "PageHtml",
+  [INSERT.SELECTION_HTML]: "SelectionHtml",
+}
+
+/** Returns the template placeholder string for a given INSERT key, e.g. "{{Clipboard}}" */
+export const toInsertTemplate = (key: INSERT): string =>
+  `{{${InsertSymbol[key]}}}`
diff --git a/packages/extension/src/services/settings/enhancedSettings.ts b/packages/extension/src/services/settings/enhancedSettings.ts
index 0a5b1fe2..3e26f36f 100644
--- a/packages/extension/src/services/settings/enhancedSettings.ts
+++ b/packages/extension/src/services/settings/enhancedSettings.ts
@@ -67,6 +67,7 @@ export class EnhancedSettings {
             hasShownReviewRequest: false,
             hasDismissedPromptHistoryBanner: false,
             hasShownHubShareToast: false,
+            hasShownOnboarding: false,
           }),
     ])
 
@@ -98,6 +99,7 @@ export class EnhancedSettings {
             hasShownReviewRequest: false,
             hasDismissedPromptHistoryBanner: false,
             hasShownHubShareToast: false,
+            hasShownOnboarding: false,
           }
 
     // Merge settings
@@ -185,6 +187,7 @@ export class EnhancedSettings {
       hasDismissedPromptHistoryBanner:
         data.userStats.hasDismissedPromptHistoryBanner,
       hasShownHubShareToast: data.userStats.hasShownHubShareToast,
+      hasShownOnboarding: data.userStats.hasShownOnboarding,
     } as SettingsType
   }
 
diff --git a/packages/extension/src/services/settings/settings.test.ts b/packages/extension/src/services/settings/settings.test.ts
index 39102bd3..561d8c60 100644
--- a/packages/extension/src/services/settings/settings.test.ts
+++ b/packages/extension/src/services/settings/settings.test.ts
@@ -194,6 +194,7 @@ describe("Settings", () => {
       hasShownReviewRequest: false,
       hasDismissedPromptHistoryBanner: false,
       hasShownHubShareToast: false,
+      hasShownOnboarding: false,
       stars: [] as Star[],
     }
 
@@ -215,6 +216,7 @@ describe("Settings", () => {
         hasDismissedPromptHistoryBanner:
           mockSettings.hasDismissedPromptHistoryBanner,
         hasShownHubShareToast: mockSettings.hasShownHubShareToast,
+        hasShownOnboarding: mockSettings.hasShownOnboarding,
       })
       expect(mockStorage.set).toHaveBeenCalledWith(
         STORAGE_KEY.SHORTCUTS,
@@ -635,6 +637,7 @@ describe("migrate function", () => {
       hasShownReviewRequest: false,
       hasDismissedPromptHistoryBanner: false,
       hasShownHubShareToast: false,
+      hasShownOnboarding: false,
       stars: [] as Star[],
     }
 
diff --git a/packages/extension/src/services/settings/settings.ts b/packages/extension/src/services/settings/settings.ts
index e70f8d69..40d5208a 100644
--- a/packages/extension/src/services/settings/settings.ts
+++ b/packages/extension/src/services/settings/settings.ts
@@ -138,6 +138,7 @@ export const Settings = {
       hasShownReviewRequest,
       hasDismissedPromptHistoryBanner,
       hasShownHubShareToast,
+      hasShownOnboarding,
       stars,
       ...restData
     } = data
@@ -147,6 +148,7 @@ export const Settings = {
       hasShownReviewRequest,
       hasDismissedPromptHistoryBanner,
       hasShownHubShareToast,
+      hasShownOnboarding,
     }
 
     ps.push(Storage.set<UserStats>(STORAGE_KEY.USER_STATS, userStats))
diff --git a/packages/extension/src/services/storage/index.ts b/packages/extension/src/services/storage/index.ts
index 713d05c7..1e3c4e87 100644
--- a/packages/extension/src/services/storage/index.ts
+++ b/packages/extension/src/services/storage/index.ts
@@ -58,6 +58,7 @@ const DEFAULTS = {
     hasShownReviewRequest: false,
     hasDismissedPromptHistoryBanner: false,
     hasShownHubShareToast: false,
+    hasShownOnboarding: false,
   },
   [STORAGE_KEY.SHORTCUTS]: {
     shortcuts: [],
diff --git a/packages/extension/src/types/index.ts b/packages/extension/src/types/index.ts
index e2ee4498..d325766a 100644
--- a/packages/extension/src/types/index.ts
+++ b/packages/extension/src/types/index.ts
@@ -181,6 +181,7 @@ export type UserStats = {
   hasShownReviewRequest: boolean
   hasDismissedPromptHistoryBanner: boolean
   hasShownHubShareToast: boolean
+  hasShownOnboarding: boolean
 }
 
 export type ShortcutCommand = {
diff --git a/packages/extension/src/types/onboarding.ts b/packages/extension/src/types/onboarding.ts
new file mode 100644
index 00000000..5fe7a1e3
--- /dev/null
+++ b/packages/extension/src/types/onboarding.ts
@@ -0,0 +1,21 @@
+export enum OnboardingStep {
+  INTRO = 0,
+  SEARCH = 1,
+  AI_PROMPT = 2,
+  LINK_PREVIEW = 3,
+  CUSTOMIZE = 4,
+  COMPLETE = 5,
+}
+
+// Sub-state within a single step: shown its explanation, waiting for the
+// user to select text, waiting for them to run the command, waiting for
+// them to come back from the popup/tab it opened, then showing the value
+// message. Not every step uses every phase (e.g. INTRO/CUSTOMIZE/COMPLETE
+// only ever use EXPLAIN).
+export enum StepPhase {
+  EXPLAIN = "explain",
+  WAIT_SELECTION = "wait_selection",
+  WAIT_EXECUTE = "wait_execute",
+  WAIT_RETURN = "wait_return",
+  VALUE_SHOWN = "value_shown",
+}
diff --git a/packages/extension/src/types/vite-env.d.ts b/packages/extension/src/types/vite-env.d.ts
index 6664dba0..f5f6673f 100644
--- a/packages/extension/src/types/vite-env.d.ts
+++ b/packages/extension/src/types/vite-env.d.ts
@@ -1,7 +1,7 @@
 /// <reference types="vite/client" />
 
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-interface ImportMetaEnv { }
+interface ImportMetaEnv {}
 
 interface ImportMeta {
   readonly env: ImportMetaEnv
@@ -10,3 +10,4 @@ interface ImportMeta {
 declare const __APP_VERSION__: string
 declare const __APP_NAME__: string
 declare const __AI_SERVICES_JSON__: unknown[]
+declare const __CONTENT_SCRIPT_CSS_FILES__: string[]
diff --git a/packages/extension/tailwind.config.js b/packages/extension/tailwind.config.js
index 63dc22b7..32a0efc6 100644
--- a/packages/extension/tailwind.config.js
+++ b/packages/extension/tailwind.config.js
@@ -40,6 +40,50 @@ module.exports = {
             transform: "scale(1)",
           },
         },
+        // Onboarding-only keyframes. Namespaced with an `onboarding-` prefix
+        // (see also the `onboarding-` animation names below) so they read as
+        // a related set alongside the rest of this file's keyframes.
+        "onboarding-rise": {
+          from: { opacity: "0", transform: "translateY(10px)" },
+          to: { opacity: "1", transform: "translateY(0)" },
+        },
+        "onboarding-ring": {
+          "0%, 100%": { boxShadow: "0 0 0 0 var(--onboarding-ring-color)" },
+          "50%": { boxShadow: "0 0 0 6px var(--onboarding-ring-color)" },
+        },
+        "onboarding-blink": {
+          "0%, 100%": { opacity: "1" },
+          "50%": { opacity: "0.45" },
+        },
+        // Drives the selection-demo highlight span: fades a selection-blue
+        // background in, holds, then fades it out, looping.
+        "onboarding-highlight": {
+          "0%, 10%": { backgroundColor: "rgb(191 219 254 / 0)" },
+          "44%, 70%": { backgroundColor: "rgb(191 219 254 / 1)" },
+          "82%, 100%": { backgroundColor: "rgb(191 219 254 / 0)" },
+        },
+        // The one-shot scale-in used for the the completion screen's party-popper icon.
+        "onboarding-pop": {
+          "0%": { opacity: "0", transform: "scale(0.72)" },
+          "100%": { opacity: "1", transform: "scale(1)" },
+        },
+        "onboarding-pop-2": {
+          "0%": {
+            opacity: "0",
+            transform: "scale(0.72) translate(-10px, 10px)",
+          },
+          "100%": { opacity: "1", transform: "scale(1)" },
+        },
+        // Gentle vertical bob used to draw extra attention to the onboarding
+        // callout bubble. Uses the standalone `translate` property (not
+        // `transform`) so it composes with, instead of overriding, the
+        // `transform` Radix Popper uses to rotate/position PopoverArrow -
+        // both the bubble and its arrow share this animation and must move
+        // in sync.
+        "onboarding-float": {
+          "0%, 100%": { translate: "0 0" },
+          "50%": { translate: "0 -4px" },
+        },
       },
       animation: {
         "accordion-down": "accordion-down 0.2s ease-out",
@@ -48,6 +92,16 @@ module.exports = {
         marquee2: "marquee2 var(--marquee-duration) linear infinite",
         "spin-slow": "spin 3s linear infinite",
         popup: "popup 0.3s cubic-bezier(0.34, 1.56, 0.64, 1) both",
+        "onboarding-rise":
+          "onboarding-rise 0.7s cubic-bezier(0.16, 1, 0.3, 1) both",
+        "onboarding-ring": "onboarding-ring 2.4s ease-in-out 0.6s infinite",
+        "onboarding-blink": "onboarding-blink 1.5s ease-in-out 0.3s infinite",
+        "onboarding-highlight": "onboarding-highlight 4s ease-in-out infinite",
+        "onboarding-pop":
+          "onboarding-pop 0.36s cubic-bezier(0.34, 1.4, 0.64, 1) both",
+        "onboarding-pop-2":
+          "onboarding-pop-2 0.36s cubic-bezier(0.34, 1.4, 0.64, 1) both",
+        "onboarding-float": "onboarding-float 1.4s ease-in-out infinite",
       },
       padding: {
         0.5: "2px",
diff --git a/packages/extension/vite.config.ts b/packages/extension/vite.config.ts
index 99e83a00..1a101b89 100644
--- a/packages/extension/vite.config.ts
+++ b/packages/extension/vite.config.ts
@@ -11,6 +11,7 @@ import removeCssFromContentScript from "./src/lib/vite-plugin-manifest"
 import refreshLocales from "./src/lib/vite-plugin-refresh-locales"
 import packageJson from "./package.json"
 import { importIfPlugin } from "./src/lib/vite-plugin-import-if"
+import { CONTENT_SCRIPT_CSS_PLACEHOLDER } from "./src/lib/contentScriptCss"
 
 const shouldUploadSourcemaps = process.env.UPLOAD_SOURCEMAP_TO_SENTRY === "true"
 
@@ -27,23 +28,23 @@ export default defineConfig(({ mode }) => {
 
   const activeManifest = isProduction
     ? {
-      ...manifest,
-      ...(extensionKey ? { key: extensionKey } : {}),
-      content_scripts: manifest.content_scripts.map((cs) => ({
-        ...cs,
-        matches: cs.matches.filter((m) => !m.includes("localhost")),
-      })),
-      externally_connectable: {
-        ...manifest.externally_connectable,
-        matches: manifest.externally_connectable.matches.filter(
-          (m) => !m.includes("localhost"),
-        ),
-      },
-    }
+        ...manifest,
+        ...(extensionKey ? { key: extensionKey } : {}),
+        content_scripts: manifest.content_scripts.map((cs) => ({
+          ...cs,
+          matches: cs.matches.filter((m) => !m.includes("localhost")),
+        })),
+        externally_connectable: {
+          ...manifest.externally_connectable,
+          matches: manifest.externally_connectable.matches.filter(
+            (m) => !m.includes("localhost"),
+          ),
+        },
+      }
     : {
-      ...manifest,
-      ...(extensionKey ? { key: extensionKey } : {}),
-    }
+        ...manifest,
+        ...(extensionKey ? { key: extensionKey } : {}),
+      }
 
   const plugins = [
     react(),
@@ -132,6 +133,11 @@ export default defineConfig(({ mode }) => {
         path.resolve(__dirname, "../hub/public/data/ai-services.json"),
         "utf-8",
       ),
+      // Replaced with the real content_script CSS file list post-build.
+      // See src/lib/contentScriptCss.ts.
+      __CONTENT_SCRIPT_CSS_FILES__: JSON.stringify([
+        CONTENT_SCRIPT_CSS_PLACEHOLDER,
+      ]),
     },
     resolve: {
       alias: {
@@ -144,20 +150,20 @@ export default defineConfig(({ mode }) => {
       pure:
         mode === "production"
           ? [
-            "console.log",
-            "console.debug",
-            "console.info",
-            "console.trace",
-            "console.dir",
-            "console.count",
-            "console.countReset",
-            "console.group",
-            "console.groupCollapsed",
-            "console.groupEnd",
-            "console.time",
-            "console.timeEnd",
-            "console.timeLog",
-          ]
+              "console.log",
+              "console.debug",
+              "console.info",
+              "console.trace",
+              "console.dir",
+              "console.count",
+              "console.countReset",
+              "console.group",
+              "console.groupCollapsed",
+              "console.groupEnd",
+              "console.time",
+              "console.timeEnd",
+              "console.timeLog",
+            ]
           : [],
     },
     build: {
@@ -166,31 +172,7 @@ export default defineConfig(({ mode }) => {
       rollupOptions: {
         input: {
           clipboard: "src/clipboard.html",
-        },
-        output: {
-          // Group all CSS module files into a named chunk so that the
-          // extracted CSS asset gets a predictable name ("components.css").
-          // This avoids content-based heuristics in assetFileNames.
-          manualChunks(id) {
-            if (/\.module\.css(\?.*)?$/.test(id)) {
-              return "components"
-            }
-          },
-          assetFileNames: (assetInfo) => {
-            // Filename-based detection: CSS modules are grouped into the
-            // "components" chunk above, so their CSS asset is named "components.css".
-            if (assetInfo.names?.[0] === "components.css") {
-              return `assets/components.css`
-            }
-            const keepNames = ["content_script.css"]
-            if (
-              assetInfo.names?.length > 0 &&
-              keepNames.includes(assetInfo.names[0])
-            ) {
-              return `assets/${assetInfo.names[0]}`
-            }
-            return "assets/[name]-[hash][extname]"
-          },
+          onboarding: "src/onboarding_page.html",
         },
       },
     },
diff --git a/yarn.lock b/yarn.lock
index 3cdb1bc6..80e06029 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2010,6 +2010,11 @@
   dependencies:
     "@babel/types" "^7.28.2"
 
+"@types/canvas-confetti@^1.9.0":
+  version "1.9.0"
+  resolved "https://registry.yarnpkg.com/@types/canvas-confetti/-/canvas-confetti-1.9.0.tgz#d1077752e046413c9881fbb2ba34a70ebe3c1773"
+  integrity sha512-aBGj/dULrimR1XDZLtG9JwxX1b4HPRF6CX9Yfwh3NvstZEm1ZL7RBnel4keCPSqs1ANRu1u2Aoz9R+VmtjYuTg==
+
 "@types/chai@^5.2.2":
   version "5.2.3"
   resolved "https://registry.yarnpkg.com/@types/chai/-/chai-5.2.3.tgz#8e9cd9e1c3581fa6b341a5aed5588eb285be0b4a"
@@ -2978,6 +2983,11 @@ caniuse-lite@^1.0.30001579, caniuse-lite@^1.0.30001806, caniuse-lite@^1.0.300018
   resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001809.tgz#e6cf71f14ddfe008f114dd2a846923be3c03a07b"
   integrity sha512-xxWVywk6a6Arlk+hymeycyn/VgqEfLDxupvhH/xiY5SJ/18kmi9o6MiO320DCUzypORHLtvh0I4i04tUhCNHNQ==
 
+canvas-confetti@^1.9.4:
+  version "1.9.4"
+  resolved "https://registry.yarnpkg.com/canvas-confetti/-/canvas-confetti-1.9.4.tgz#4412a5daa96afd0b4d70ecd66b65ce8db3022b2b"
+  integrity sha512-yxQbJkAVrFXWNbTUjPqjF7G+g6pDotOUHGbkZq2NELZUMDpiJ85rIEazVb8GTaAptNW2miJAXbs1BtioA251Pw==
+
 chai@^5.2.0:
   version "5.3.3"
   resolved "https://registry.yarnpkg.com/chai/-/chai-5.3.3.tgz#dd3da955e270916a4bd3f625f4b919996ada7e06"
@@ -6371,7 +6381,7 @@ stop-iteration-iterator@^1.1.0:
     es-errors "^1.3.0"
     internal-slot "^1.1.0"
 
-"string-width-cjs@npm:string-width@^4.2.0":
+"string-width-cjs@npm:string-width@^4.2.0", string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3:
   version "4.2.3"
   resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
   integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==
@@ -6389,15 +6399,6 @@ string-width@^3.0.0, string-width@^3.1.0:
     is-fullwidth-code-point "^2.0.0"
     strip-ansi "^5.1.0"
 
-string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.3:
-  version "4.2.3"
-  resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
-  integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==
-  dependencies:
-    emoji-regex "^8.0.0"
-    is-fullwidth-code-point "^3.0.0"
-    strip-ansi "^6.0.1"
-
 string-width@^5.0.1, string-width@^5.1.2:
   version "5.1.2"
   resolved "https://registry.yarnpkg.com/string-width/-/string-width-5.1.2.tgz#14f8daec6d81e7221d2a357e668cab73bdbca794"
@@ -6483,7 +6484,7 @@ string_decoder@~1.1.1:
   dependencies:
     safe-buffer "~5.1.0"
 
-"strip-ansi-cjs@npm:strip-ansi@^6.0.1":
+"strip-ansi-cjs@npm:strip-ansi@^6.0.1", strip-ansi@^6.0.0, strip-ansi@^6.0.1:
   version "6.0.1"
   resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9"
   integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==
@@ -6497,13 +6498,6 @@ strip-ansi@^5.0.0, strip-ansi@^5.1.0, strip-ansi@^5.2.0:
   dependencies:
     ansi-regex "^4.1.0"
 
-strip-ansi@^6.0.0, strip-ansi@^6.0.1:
-  version "6.0.1"
-  resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9"
-  integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==
-  dependencies:
-    ansi-regex "^5.0.1"
-
 strip-ansi@^7.0.1:
   version "7.2.0"
   resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-7.2.0.tgz#d22a269522836a627af8d04b5c3fd2c7fa3e32e3"
@@ -7219,7 +7213,7 @@ word-wrap@^1.2.5:
   resolved "https://registry.yarnpkg.com/word-wrap/-/word-wrap-1.2.5.tgz#d2c45c6dd4fbce621a66f136cbe328afd0410b34"
   integrity sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==
 
-"wrap-ansi-cjs@npm:wrap-ansi@^7.0.0":
+"wrap-ansi-cjs@npm:wrap-ansi@^7.0.0", wrap-ansi@^7.0.0:
   version "7.0.0"
   resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43"
   integrity sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==
@@ -7237,15 +7231,6 @@ wrap-ansi@^5.1.0:
     string-width "^3.0.0"
     strip-ansi "^5.0.0"
 
-wrap-ansi@^7.0.0:
-  version "7.0.0"
-  resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43"
-  integrity sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==
-  dependencies:
-    ansi-styles "^4.0.0"
-    string-width "^4.1.0"
-    strip-ansi "^6.0.0"
-
 wrap-ansi@^8.1.0:
   version "8.1.0"
   resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-8.1.0.tgz#56dc22368ee570face1b49819975d9b9a5ead214"