@amplitude/wizard 1.0.0 → 1.2.0

package/skills/integration/integration-ruby/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integration-ruby
-description: Amplitude integration for any Ruby application using the Ruby SDK
+description: Amplitude integration for any Ruby application using the amplitude-api gem
 metadata:
   author: Amplitude
   version: dev
@@ -36,15 +36,11 @@ The example project shows the target implementation pattern. Consult the documen
 - **Environment variables**: Always use environment variables for Amplitude keys. Never hardcode them.
 - **Minimal changes**: Add Amplitude code alongside existing integrations. Don't replace or restructure existing code.
 - **Match the example**: Your implementation should follow the example project's patterns as closely as possible.
-
-## Framework guidelines
-
-- amplitude-api is a commonly used Ruby SDK gem (add `gem 'amplitude-api'` to Gemfile)
-- Use AmplitudeAPI::Event and AmplitudeAPI.send_event for tracking; initialize with AmplitudeAPI.config.api_key
-- In CLIs and scripts, ensure events are flushed before exit
-- Use begin/rescue/ensure for proper cleanup patterns
-- Events take a user_id and event_type plus event_properties hash
+- **Unified SDK**: For new browser/frontend projects, use `@amplitude/unified` as the default SDK — it bundles Analytics, Session Replay, Experiment, and Guides & Surveys in a single package. Initialize with `initAll()`. Only use `@amplitude/analytics-browser` if the project already has it installed.
+- **Event naming**: Event names MUST use Title Case with spaces following the [Noun] + [Past-Tense Verb] pattern (e.g., "Button Clicked", "Sign Up Completed", "Cart Viewed"). Do NOT use snake_case, camelCase, or SCREAMING_SNAKE. Property names should use snake_case (e.g., button_text, page_url).
+- **No PII in events**: Never send PII (emails, full names, phone numbers, physical addresses, IP addresses) in `track()` event properties. PII belongs in `identify()` user properties only.
+- **Autocapture**: Enable autocapture in the init config to automatically capture sessions, page views, form interactions, and file downloads. Use the `autocapture` config option (not the deprecated `defaultTracking`).
 
 ## Identifying users
 
-Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. Call `amplitude.setUserId(userId)` to associate events with a known user, and use `amplitude.identify()` with an `Identify` object to set user properties. If both frontend and backend code exist, pass a consistent user/device ID via custom request headers to maintain event correlation.
+Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. Call `amplitude.setUserId(userId)` to associate events with a known user, and use `amplitude.identify()` with an `Identify` object to set user properties. Call `amplitude.reset()` on logout to unlink future events from the current user. If both frontend and backend code exist, pass a consistent user/device ID via custom request headers to maintain event correlation.

package/skills/integration/integration-ruby/references/amplitude-quickstart.md

@@ -81,7 +81,7 @@
     }
   </style>
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tocbot/4.25.0/tocbot.css">
-  <link href="/docs/css/site.css?id=cf9c3f0a1066ff8b5d94a25cd8d407e1" rel="stylesheet">
+  <link href="/docs/css/site.css?id=6e2f9e1efe9343c4ba65666223648444" rel="stylesheet">
   <link href="/docs/css/algolia.css?id=e343cc9490e043fefffa37d2817ddf8c" rel="stylesheet">
   <link href="/docs/css/dracula-prism.css?id=a5713888be640854bb66b8b74c1037ce" rel="stylesheet">
 <style>

package/skills/integration/integration-ruby/references/analytics.md

@@ -74,7 +74,7 @@
     }
   </style>
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tocbot/4.25.0/tocbot.css">
-  <link href="/docs/css/site.css?id=cf9c3f0a1066ff8b5d94a25cd8d407e1" rel="stylesheet">
+  <link href="/docs/css/site.css?id=6e2f9e1efe9343c4ba65666223648444" rel="stylesheet">
   <link href="/docs/css/algolia.css?id=e343cc9490e043fefffa37d2817ddf8c" rel="stylesheet">
   <link href="/docs/css/dracula-prism.css?id=a5713888be640854bb66b8b74c1037ce" rel="stylesheet">
 <style>

package/skills/integration/integration-ruby/references/basic-integration-1.0-begin.md

@@ -21,7 +21,9 @@ Do not skip server-side events - they capture actions that cannot be tracked cli
 
 Create a new file with a JSON array at the root of the project: .amplitude-events.json. It should include one object for each event we want to add: event name, event description, and the file path we want to place the event in. If events already exist, don't duplicate them; supplement them.
 
-Track actions only, not pageviews. These can be captured automatically. Exceptions can be made for "viewed"-type events that correspond to the top of a conversion funnel.
+**Event names MUST use Title Case with spaces** following the [Noun] + [Past-Tense Verb] pattern (e.g., "Button Clicked", "Sign Up Completed", "Cart Viewed"). Do NOT use snake_case (button_clicked), camelCase (buttonClicked), or SCREAMING_SNAKE (BUTTON_CLICKED). Property names should use snake_case (e.g., button_text, page_url).
+
+Track actions only, not pageviews. These can be captured automatically via Amplitude's autocapture. Exceptions can be made for "viewed"-type events that correspond to the top of a conversion funnel.
 
 As you review files, make an internal note of opportunities to identify users. We'll need them for the next step.
 

package/skills/integration/integration-ruby/references/basic-integration-1.1-edit.md

@@ -5,8 +5,12 @@ description: Implement Amplitude event tracking in the identified files, followi
 
 For each of the files and events noted in .amplitude-events.json, make edits to capture events using Amplitude. Make sure to set up any helper files needed. Carefully examine the included example project code: your implementation should match it as closely as possible. Do not spawn subagents.
 
+For browser/frontend projects, use @amplitude/unified as the default SDK — it bundles Analytics, Session Replay, and Experiment in a single package. Only use @amplitude/analytics-browser if the project already has it installed.
+
 Use environment variables for Amplitude keys. Do not hardcode Amplitude keys.
 
+Event names MUST use Title Case with spaces following the [Noun] + [Past-Tense Verb] pattern (e.g., "Button Clicked", "Sign Up Completed", "Cart Viewed"). Do NOT use snake_case or camelCase for event names. Property names should use snake_case (e.g., button_text, page_url).
+
 If a file already has existing integration code for other tools or services, don't overwrite or remove that code. Place Amplitude code below it.
 
 For each event, add useful properties, and use your access to the Amplitude source code to ensure correctness. You also have access to documentation about creating new events with Amplitude. Consider this documentation carefully and follow it closely before adding events. Your integration should be based on documented best practices. Carefully consider how the user project's framework version may impact the correct Amplitude integration approach.
@@ -21,6 +25,185 @@ Remember: Do not alter the fundamental architecture of existing files. Make your
 
 Remember the documentation and example project resources you were provided at the beginning. Read them now.
 
+## Framework-specific guidelines
+
+Apply **only** the section that matches your active integration skill. Skip all other sections.
+
+### React — all variants
+_Applies to: react-vite, react-react-router-6, react-react-router-7-framework, react-react-router-7-data, react-react-router-7-declarative, react-tanstack-router-file-based, react-tanstack-router-code-based, tanstack-start, nextjs-app-router, nextjs-pages-router_
+
+- For feature flags, use the Amplitude Experiment React SDK hooks (`useVariantValue`, `useExperiment`) — they handle loading states and async fetch automatically
+- Add analytics track calls in event handlers where user actions occur, NOT in `useEffect` reacting to state changes
+- Do NOT use `useEffect` for data transformation — calculate derived values during render instead
+- Do NOT use `useEffect` to respond to user events — put that logic in the event handler itself
+- Do NOT use `useEffect` to chain state updates — calculate all related updates together in the event handler
+- Do NOT use `useEffect` to notify parent components — call the parent callback alongside `setState` in the event handler
+- To reset component state when a prop changes, pass the prop as the component's `key` instead of using `useEffect`
+- `useEffect` is ONLY for synchronizing with external systems (non-React widgets, browser APIs, network subscriptions)
+
+### Next.js (in addition to React guidelines above)
+_Applies to: nextjs-app-router, nextjs-pages-router_
+
+- For Next.js 15.3+, initialize Amplitude in `instrumentation-client.ts` for the simplest setup
+
+### TanStack Router / TanStack Start (in addition to React guidelines above)
+_Applies to: react-tanstack-router-file-based, react-tanstack-router-code-based, tanstack-start_
+
+- Use TanStack Router's built-in navigation events for pageview tracking instead of `useEffect`
+- Initialize Amplitude once in the root component — `__root.tsx` (file-based) or wherever `createRootRoute()` is called (code-based)
+
+### TanStack Start (in addition to React and TanStack Router guidelines above)
+_Applies to: tanstack-start_
+
+- Use `@amplitude/analytics-node` for server-side event tracking in API routes (`src/routes/api/`) — do NOT use `@amplitude/analytics-browser` on the server
+- Create a singleton Amplitude server client to avoid re-initialization on every request
+
+### Angular
+_Applies to: angular_
+
+- Use `inject()` instead of constructor injection for Amplitude in components and services
+- Create a dedicated `AmplitudeService` as a singleton root service that wraps the SDK
+- Always use standalone components over NgModules
+- Configure Amplitude credentials in `src/environments/environment.ts` — Angular reads env vars from these config files, not from `process.env`
+
+### SvelteKit
+_Applies to: sveltekit_
+
+- Set `paths.relative = false` in `svelte.config.js` if needed for client-side SDK compatibility with SSR
+- Use the Svelte MCP server tools to check Svelte documentation (`list-sections`, `get-documentation`) and validate components (`svelte-autofixer`) — run `svelte-autofixer` on every new or modified `.svelte` file before finishing
+
+### Astro — all variants
+_Applies to: astro-static, astro-ssr, astro-hybrid, astro-view-transitions_
+
+- Always use the `is:inline` directive on Amplitude script tags to prevent Astro from processing them and causing TypeScript errors
+- Use `PUBLIC_` prefix for client-side environment variables (e.g., `PUBLIC_AMPLITUDE_API_KEY`)
+- Create an `amplitude.astro` component in `src/components/` for reusable initialization across pages
+- Import the Amplitude component in a Layout and wrap all pages with that layout
+
+### Astro View Transitions (in addition to Astro base guidelines above)
+_Applies to: astro-view-transitions_
+
+- Wrap Amplitude initialization with a `window.__amplitude_initialized` guard to prevent re-initialization during soft navigation
+- Use the `astro:page-load` event instead of just `DOMContentLoaded` to re-run scripts after soft navigation
+
+### Astro SSR / Hybrid (in addition to Astro base guidelines above)
+_Applies to: astro-ssr, astro-hybrid_
+
+- Use `@amplitude/analytics-node` in API routes under `src/pages/api/` for server-side event tracking
+- Store the Amplitude node client as a singleton in `src/lib/amplitude-server.ts` to avoid creating multiple clients
+
+### Astro Hybrid (in addition to Astro SSR guidelines above)
+_Applies to: astro-hybrid_
+
+- In Astro 5, use `output: static` (the default) with an adapter — pages are prerendered by default
+- Use `export const prerender = false` to opt specific pages into SSR when they need server-side rendering
+- Only pages that need server-side Amplitude tracking (such as API-backed forms) should opt out of prerendering
+
+### Python — all variants
+_Applies to: python, django, fastapi, flask_
+
+- `amplitude-analytics` is the Python SDK package name
+- Install with `pip install amplitude-analytics` or `pip install -r requirements.txt` — do NOT use unquoted version specifiers like `>=` directly in shell commands
+- Always initialize with `Amplitude(api_key)` and configure via `Config()` — do NOT use module-level config
+- In CLIs and scripts: MUST call `client.shutdown()` before exit or all events are lost. Register it with `atexit.register(client.shutdown)` to flush on exit.
+- NEVER send PII in `track()` event properties (no emails, names, phone numbers, addresses, IPs, or user content). PII belongs in `identify()` user properties only. Safe event properties are metadata like `message_length`, `form_type`, boolean flags.
+- Source code for the SDK is available in the `venv/site-packages` directory
+
+### Django (in addition to Python guidelines above)
+_Applies to: django_
+
+- Initialize the Amplitude client in `AppConfig.ready()` with the API key from environment variables
+- Use a singleton pattern — create the client once and reuse it across requests
+
+### FastAPI (in addition to Python guidelines above)
+_Applies to: fastapi_
+
+- Initialize Amplitude in the `lifespan` context manager on startup; call `await amplitude.flush()` on shutdown
+- Use Pydantic Settings with `@lru_cache` on `get_settings()` for caching and easy test overrides
+- Use FastAPI dependency injection (`Depends`) for accessing `current_user` and settings in route handlers
+
+### Flask (in addition to Python guidelines above)
+_Applies to: flask_
+
+- Initialize Amplitude globally in `create_app()` (NOT per-request)
+- Blueprint registration happens AFTER Amplitude initialization in `create_app()`
+
+### JavaScript Node
+_Applies to: javascript_node_
+
+- `@amplitude/analytics-node` is the server-side SDK — do NOT use `@amplitude/analytics-browser` on the server
+- Track events in route handlers for meaningful user actions; every route that creates, updates, or deletes data should track an event
+- In long-running servers the SDK batches automatically — do NOT set `flushQueueSize` or `flushIntervalMillis` unless you have a specific reason
+- For short-lived processes (scripts, CLIs, serverless): call `await amplitude.flush()` before exit
+- Reverse proxy is NOT needed for server-side Node.js — only client-side JS may benefit from one to avoid ad blockers
+- Source code is available in the `node_modules` directory
+
+### JavaScript Web
+_Applies to: javascript_web_
+
+- `@amplitude/analytics-browser` is the browser SDK — do NOT import it in Node.js or server-side contexts
+- `amplitude.init()` MUST be called before any other Amplitude methods
+- Autocapture is available via the autocapture plugin but is NOT enabled by default — opt in explicitly if requested
+- Call `amplitude.reset()` on logout to unlink future events from the current user
+- For SPAs without a framework router, use the `pageViewTracking` option in `amplitude.init()` or manually call `amplitude.track('Page Viewed', { path })` for History API routing
+
+### Android
+_Applies to: android_
+
+- Adapt dependency configuration to the appropriate `build.gradle(.kts)` file for the project's Gradle version
+- Initialize Amplitude in the `Application` class's `onCreate()`: `Amplitude(Configuration(apiKey = ..., context = applicationContext)).also { amplitude = it }` — call this only once
+- Ensure every activity has an `android:label` to accurately track screen views
+
+### Swift
+_Applies to: swift_
+
+- Read configuration from environment variables via a dedicated enum using `ProcessInfo.processInfo.environment`; fatalError if `AMPLITUDE_API_KEY` is missing
+- When adding SPM dependencies to `project.pbxproj`, create three distinct objects with unique UUIDs: a `PBXBuildFile` (with `productRef`), an `XCSwiftPackageProductDependency` (with `package` and `productName`), and an `XCRemoteSwiftPackageReference` (with `repositoryURL` and `requirement`)
+- Check the latest release at https://github.com/amplitude/Amplitude-Swift/releases before setting `minimumVersion` — do not hardcode a stale version
+- For macOS with App Sandbox: add `ENABLE_OUTGOING_NETWORK_CONNECTIONS = YES` to build settings — do NOT disable the sandbox
+
+### React Native
+_Applies to: react-native_
+
+- `@amplitude/analytics-react-native` is the SDK package name
+- Use `react-native-config` to load `AMPLITUDE_API_KEY` from `.env` (embedded at build time, not runtime)
+- Requires `@react-native-async-storage/async-storage` and `@react-native-community/netinfo` as peer dependencies — install them alongside the SDK
+- Initialize Amplitude once at the top level (e.g., `App.tsx`) before any track calls
+
+### Expo
+_Applies to: expo_
+
+- `@amplitude/analytics-react-native` is the SDK package name (same as bare RN)
+- Use `expo-constants` with `app.config.js` extras for `AMPLITUDE_API_KEY` (NOT `react-native-config`)
+- Access it via `Constants.expoConfig?.extra?.amplitudeApiKey`
+- For `expo-router`, initialize Amplitude in `app/_layout.tsx` and track screen views manually: `amplitude.track('Screen Viewed', { screen: pathname })`
+- Requires `@react-native-async-storage/async-storage` and `@react-native-community/netinfo` as peer dependencies
+
+### Ruby
+_Applies to: ruby, ruby-on-rails_
+
+- `amplitude-api` gem (`gem 'amplitude-api'` in Gemfile)
+- Use `AmplitudeAPI::Event` and `AmplitudeAPI.send_event`; initialize with `AmplitudeAPI.config.api_key`
+- Events take `user_id`, `event_type`, and `event_properties` hash
+- Ensure events are flushed before exit; use `begin/rescue/ensure` for cleanup
+
+### Ruby on Rails (in addition to Ruby guidelines above)
+_Applies to: ruby-on-rails_
+
+- Initialize AmplitudeAPI in `config/initializers/amplitude.rb`
+- Create a dedicated service class for Amplitude tracking to keep controllers clean
+- Use background jobs for non-critical tracking to avoid slowing down request handling
+
+### Laravel
+_Applies to: laravel_
+
+- Create a dedicated `AmplitudeService` in `app/Services/` — do NOT scatter track calls throughout controllers
+- Register Amplitude config in `config/amplitude.php` using `env()` for all settings
+- Do NOT use Laravel's event system or observers for analytics — call track explicitly where actions occur
+- `amplitude/amplitude-php` is the PHP SDK package (community gem — check `composer.json` for availability)
+- Source code is available in the `vendor` directory after `composer install`
+- Initialize the Amplitude client once with your API key and reuse it throughout the application
+
 ## Status
 
 Status to report in this phase:

package/skills/integration/integration-ruby/references/basic-integration-1.3-conclude.md

@@ -7,21 +7,83 @@ description: Review and finalize the Amplitude integration implementation
 
 Before anything else, verify that the Amplitude environment variables are properly set up for production.
 
-1. Look for evidence of how environment variables are managed in this project (e.g., `.env`, `.env.local`, `.env.example`, `vercel.json`, `netlify.toml`, platform-specific config files, CI/CD config).
+1. Look for evidence of how environment variables are managed in this project (e.g., `.env`, `.env.local`, `.env.example`, `vercel.json`, platform-specific config files, CI/CD config).
 2. Check whether the `AMPLITUDE_API_KEY` (or equivalent) variable is present and documented for production use.
 3. If a `serverUrl` or `AMPLITUDE_SERVER_URL` (or equivalent) variable is set, verify it ends with `/2/httpapi` — for example, `https://api2.amplitude.com/2/httpapi`. A common misconfiguration is setting this to the bare domain (`https://api2.amplitude.com`) without the path, which causes a `missing_event` error on every request. Fix this if found.
 
-If you can clearly identify the deployment platform (Vercel, Netlify, AWS, Heroku, etc.), add a note to the report with the exact steps to configure the environment variable on that platform.
+If you can clearly identify the deployment platform, add a note to the report with the exact steps to configure the environment variable on that platform.
 
-**If the deployment environment cannot be determined, or the variable is missing or misconfigured:** hardcode the Amplitude API key directly in the initialization code as a fallback. Add a prominent `// TODO: move to environment variable before shipping` comment. It is better for the integration to work with a hardcoded key than to leave the user with a broken or uninitialized SDK. Call this out clearly in the report's Next steps section.
+**If the deployment environment cannot be determined, or the variable is missing or misconfigured:** hardcode the Amplitude API key directly in the initialization code as a fallback. Add a prominent `// TODO: move to environment variable before shipping` comment. Call this out clearly in the report's Next steps section.
 
 ---
 
-Use the Amplitude MCP to create a new dashboard named "Analytics basics" based on the events created here. Make sure to use the exact same event names as implemented in the code. Populate it with up to five insights, with special emphasis on things like conversion funnels, churn events, and other business critical insights.
+## Chart and dashboard creation (REQUIRED)
 
-Search for a file called `.amplitude-events.json` and read it for available events. Do not spawn subagents.
+This step is **mandatory**. Do not skip it. Use the Amplitude MCP to create a dashboard and supporting charts for this project.
 
-Create the file amplitude-setup-report.md. It should include a summary of the integration edits, a table with the event names, event descriptions, and files where events were added, along with a list of links for the dashboard and insights created. Follow this format:
+### Step 1 — Load the chart/dashboard planning skill
+
+Load the **`amplitude-chart-dashboard-plan`** skill (taxonomy category via wizard-tools). Follow its guidance for all decisions in this section.
+
+### Step 2 — Read the event plan
+
+Search for and read `.amplitude-events.json`. This file lists every event that was instrumented. Use the exact event names from this file — do not normalize or rename them.
+
+### Step 3 — Identify product funnels from the instrumented events
+
+Group the events into 2–5 product funnels. Examples:
+- **Onboarding**: sign-up → first action → activation
+- **Core loop**: primary value action and its supporting events
+- **Conversion**: checkout, upgrade, or subscribe flow
+- **Retention**: events that indicate a returning user is re-engaging
+
+If Autocapture is enabled (web apps), note that `[Amplitude] Page Viewed` and `[Amplitude] Element Clicked` are available automatically even before custom events fire.
+
+### Step 4 — Plan the charts (before creating them)
+
+Following the `amplitude-chart-dashboard-plan` skill, plan up to 8 charts:
+
+- **1 funnel chart per product funnel** (2–5 charts) — conversion-oriented, all steps in order
+- **1–2 volume/trend charts** — daily uniques for the most critical events
+- **1–2 Autocapture charts** — top pages by volume (`[Amplitude] Page Viewed`), plus element clicks for web apps
+- **1 retention chart** — N-day retention anchored on the most important activation event
+
+### Step 5 — Create the charts via Amplitude MCP
+
+Use the Amplitude MCP to create each chart in the plan. Collect the returned chart IDs.
+
+### Step 6 — Create the dashboard
+
+Create a single dashboard using the Amplitude MCP with:
+- **Name**: `"[Product Name] Analytics — [Year]"` — use the product/app name from package.json or the app's title if available; fall back to `"Analytics Dashboard — [Year]"`
+- **Description**: `"Auto-generated by the Amplitude Wizard. Autocapture charts (page views, clicks) populate immediately. Custom event charts populate once those user flows are triggered."`
+- **Charts**: all chart IDs collected in Step 5, organized into sections by funnel (Acquisition → Activation → Core Loop → Conversion → Retention)
+
+### Step 7 — Write `.amplitude-dashboard.json`
+
+After the dashboard is created, write a file `.amplitude-dashboard.json` in the project root:
+
+```json
+{
+  "dashboardUrl": "<dashboard URL from MCP response>",
+  "dashboardId": "<dashboard ID>",
+  "charts": [
+    { "id": "<chart-id>", "title": "<chart title>", "type": "<funnel|line|retention>", "funnel": "<funnel name>" }
+  ],
+  "createdAt": "<ISO timestamp>"
+}
+```
+
+---
+
+## Setup report
+
+Create the file `amplitude-setup-report.md`. Include:
+- A summary of the integration edits
+- A table with event names, descriptions, and files where events were added
+- A list of the charts and dashboard created (with direct links)
+
+Follow this format:
 
 <wizard-report>
 # Amplitude post-wizard report
@@ -30,11 +92,19 @@ The wizard has completed a deep integration of your project. [Detailed summary o
 
 [table of events/descriptions/files]
 
-## Next steps
+## Analytics dashboard
+
+We've built a dashboard and [N] charts tied to your product flows:
 
-We've built some insights and a dashboard for you to keep an eye on user behavior, based on the events we just instrumented:
+[links to dashboard and individual charts]
 
-[links]
+The following charts use Autocapture and will populate as soon as any user visits the app (no additional instrumentation required):
+- [list Autocapture charts]
+
+The following charts rely on custom events and will populate once those flows are triggered:
+- [list custom event charts]
+
+## Next steps
 
 ### Environment variable configuration
 
@@ -42,11 +112,11 @@ We've built some insights and a dashboard for you to keep an eye on user behavio
 
 ### Agent skill
 
-We've left an agent skill folder in your project. You can use this context for further agent development when using Claude Code. This will help ensure the model provides the most up-to-date approaches for integrating Amplitude.
+We've left an agent skill folder in your project. You can use this context for further agent development when using Claude Code.
 
 </wizard-report>
 
-Upon completion, remove .amplitude-events.json.
+Upon completion, remove `.amplitude-events.json` and `.amplitude-dashboard.json`.
 
 ## Status
 

package/skills/integration/integration-ruby-on-rails/SKILL.md

@@ -36,20 +36,11 @@ The example project shows the target implementation pattern. Consult the documen
 - **Environment variables**: Always use environment variables for Amplitude keys. Never hardcode them.
 - **Minimal changes**: Add Amplitude code alongside existing integrations. Don't replace or restructure existing code.
 - **Match the example**: Your implementation should follow the example project's patterns as closely as possible.
-
-## Framework guidelines
-
-- Use the amplitude-api gem for Rails applications
-- Initialize AmplitudeAPI with your API key in config/initializers/amplitude.rb
-- Create a dedicated service class for Amplitude tracking to keep controllers clean
-- Use background jobs for non-critical tracking to avoid slowing down requests
-- Store API key in Rails credentials or environment variables, never hardcode
-- amplitude-api is a commonly used Ruby SDK gem (add `gem 'amplitude-api'` to Gemfile)
-- Use AmplitudeAPI::Event and AmplitudeAPI.send_event for tracking; initialize with AmplitudeAPI.config.api_key
-- In CLIs and scripts, ensure events are flushed before exit
-- Use begin/rescue/ensure for proper cleanup patterns
-- Events take a user_id and event_type plus event_properties hash
+- **Unified SDK**: For new browser/frontend projects, use `@amplitude/unified` as the default SDK — it bundles Analytics, Session Replay, Experiment, and Guides & Surveys in a single package. Initialize with `initAll()`. Only use `@amplitude/analytics-browser` if the project already has it installed.
+- **Event naming**: Event names MUST use Title Case with spaces following the [Noun] + [Past-Tense Verb] pattern (e.g., "Button Clicked", "Sign Up Completed", "Cart Viewed"). Do NOT use snake_case, camelCase, or SCREAMING_SNAKE. Property names should use snake_case (e.g., button_text, page_url).
+- **No PII in events**: Never send PII (emails, full names, phone numbers, physical addresses, IP addresses) in `track()` event properties. PII belongs in `identify()` user properties only.
+- **Autocapture**: Enable autocapture in the init config to automatically capture sessions, page views, form interactions, and file downloads. Use the `autocapture` config option (not the deprecated `defaultTracking`).
 
 ## Identifying users
 
-Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. Call `amplitude.setUserId(userId)` to associate events with a known user, and use `amplitude.identify()` with an `Identify` object to set user properties. If both frontend and backend code exist, pass a consistent user/device ID via custom request headers to maintain event correlation.
+Identify users during login and signup events. Refer to the example code and documentation for the correct identify pattern for this framework. Call `amplitude.setUserId(userId)` to associate events with a known user, and use `amplitude.identify()` with an `Identify` object to set user properties. Call `amplitude.reset()` on logout to unlink future events from the current user. If both frontend and backend code exist, pass a consistent user/device ID via custom request headers to maintain event correlation.

package/skills/integration/integration-ruby-on-rails/references/amplitude-quickstart.md

@@ -81,7 +81,7 @@
     }
   </style>
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tocbot/4.25.0/tocbot.css">
-  <link href="/docs/css/site.css?id=cf9c3f0a1066ff8b5d94a25cd8d407e1" rel="stylesheet">
+  <link href="/docs/css/site.css?id=6e2f9e1efe9343c4ba65666223648444" rel="stylesheet">
   <link href="/docs/css/algolia.css?id=e343cc9490e043fefffa37d2817ddf8c" rel="stylesheet">
   <link href="/docs/css/dracula-prism.css?id=a5713888be640854bb66b8b74c1037ce" rel="stylesheet">
 <style>

package/skills/integration/integration-ruby-on-rails/references/analytics.md

@@ -74,7 +74,7 @@
     }
   </style>
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/tocbot/4.25.0/tocbot.css">
-  <link href="/docs/css/site.css?id=cf9c3f0a1066ff8b5d94a25cd8d407e1" rel="stylesheet">
+  <link href="/docs/css/site.css?id=6e2f9e1efe9343c4ba65666223648444" rel="stylesheet">
   <link href="/docs/css/algolia.css?id=e343cc9490e043fefffa37d2817ddf8c" rel="stylesheet">
   <link href="/docs/css/dracula-prism.css?id=a5713888be640854bb66b8b74c1037ce" rel="stylesheet">
 <style>

package/skills/integration/integration-ruby-on-rails/references/basic-integration-1.0-begin.md

@@ -21,7 +21,9 @@ Do not skip server-side events - they capture actions that cannot be tracked cli
 
 Create a new file with a JSON array at the root of the project: .amplitude-events.json. It should include one object for each event we want to add: event name, event description, and the file path we want to place the event in. If events already exist, don't duplicate them; supplement them.
 
-Track actions only, not pageviews. These can be captured automatically. Exceptions can be made for "viewed"-type events that correspond to the top of a conversion funnel.
+**Event names MUST use Title Case with spaces** following the [Noun] + [Past-Tense Verb] pattern (e.g., "Button Clicked", "Sign Up Completed", "Cart Viewed"). Do NOT use snake_case (button_clicked), camelCase (buttonClicked), or SCREAMING_SNAKE (BUTTON_CLICKED). Property names should use snake_case (e.g., button_text, page_url).
+
+Track actions only, not pageviews. These can be captured automatically via Amplitude's autocapture. Exceptions can be made for "viewed"-type events that correspond to the top of a conversion funnel.
 
 As you review files, make an internal note of opportunities to identify users. We'll need them for the next step.