feat(docs): improve onboarding clarity and remove deprecated overlay references

packages/website/src/content/docs/docs/about.mdx

@@ -13,6 +13,10 @@ Spotlight started out as a [Hackweek project](https://syntax.fm/show/666/hackwee
 > Spotlight is Sentry for Development. Inspired by an old project, Django Debug Toolbar, Spotlight brings a rich debug
 overlay into development environments, and it does it by leveraging the existing power of Sentry's SDKs
 
+:::note[Historical Context]
+The original "overlay" concept has evolved. Spotlight now provides a [Desktop App](/docs/desktop-app/) and [CLI](/docs/cli/) featuring a browser-based UI instead of an embedded overlay. (More context in [this GitHub issue](https://github.com/getsentry/spotlight/issues/891#issue-3302059597).)
+:::
+
 You get the power of Sentry's telemetry (through its SDKs) without needing Sentry's production monitoring. If you already use Sentry, that's great. All you need is enabling Spotlight in your SDK and run Spotlight locally. If you are not using Sentry, you need to install the free and open source Sentry SDKs to get started. If you want to use Sentry later on, this saves you the initial setup. Just add your Sentry DSNs into your projects and off you go!
 
 ## Three Ways to Use Spotlight
@@ -21,7 +25,7 @@ Spotlight provides three powerful tools for debugging and development:
 
 ### 1. Local Development Tool
 
-A real-time debugging overlay that displays errors, traces, logs, and profiles directly in your browser or dedicated desktop app. See everything happening in your application as it happens.
+A real-time debugging UI that displays errors, traces, logs, and profiles in the Desktop App or browser. See everything happening in your application as it happens.
 
 **Perfect for:**
 - Visual debugging during development
@@ -93,4 +97,4 @@ If you are already using Sentry SDKs in your application try the following:
 ---
 
 [^1]: Currently Python, Ruby, PHP, and all JS-based SDKs support this env variable. If your choice of SDK doesn't support it, you can still use Spotlight by enabling the `spotlight` option in its init configuration. Also you can let us know of your interest and we'll add support for the env variable.
-[^2]: If you don't have `npx` around, you can use `docker run -p 8969 ghcr.io/getsentry/spotlight:latest`, or head over to our [GitHub Releases page](https://github.com/getsentry/spotlight/releases/latest) and download a binary for your system. Alternatively, we provide an Electron-based application that can be used to run the Sidecar as well as a dedicated instance of the overlay. There are some limitations to this method, but it is particularly useful [for headless or mobile environments](/docs/setup/headless/). <DownloadButton>Download for Mac</DownloadButton>
+[^2]: If you don't have `npx` around, you can use `docker run -p 8969:8969 ghcr.io/getsentry/spotlight:latest`, or check the [CLI installation options](/docs/cli/#installation). Alternatively, we provide a [Desktop App](/docs/desktop-app/) that bundles everything together. <DownloadButton>Download for Mac</DownloadButton>

packages/website/src/content/docs/docs/architecture.mdx

@@ -1,53 +1,47 @@
 ---
-title: Architecture of Spotlight
+title: Architecture
+description: How Spotlight works under the hood
 ---
-import { LinkCard } from '@astrojs/starlight/components';
+import { LinkCard, CardGrid } from '@astrojs/starlight/components';
 
 import Architecture from "../../../../public/images/simple-event-flow.png";
 
 <img src={Architecture.src} width="80%" alt="Spotlight Architecture" />
 
-### Description
+## How It Works
 
-At a high level, Spotlight consists of two components:
+Spotlight consists of two components bundled in `@spotlightjs/spotlight`:
 
-1. A standalone UI (`@spotlightjs/overlay`) that runs independently in your browser or as a desktop application. The UI is a React application that displays your application's telemetry data in real-time.
+1. **Sidecar Server** - A local HTTP server that receives telemetry from your application and streams it to connected clients using [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
 
-2. A proxy server (`@spotlightjs/sidecar`) which receives telemetry from your application and streams it to the UI. This is achieved via a simple HTTP relay, allowing SDKs to push events to it, and allowing the UI to receive events using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).
+2. **UI** - A React application that displays telemetry data in real-time. Available as a [Desktop App](/docs/desktop-app/) or browser-based UI at `localhost:8969`.
 
-For convenience, these packages are combined in a single package (`@spotlightjs/spotlight`), which is the recommended way to run Spotlight.
-This means that adoption in most projects is as simple as:
+## Data Flow
 
-```shell
-# Run the Spotlight sidecar with UI
-npx @spotlightjs/spotlight
-
-# Or install globally
-npm install -g @spotlightjs/spotlight
-spotlight
 ```
-
-Enabling Spotlight in your application's SDK:
-
-```typescript
-import * as Sentry from '@sentry/node';
-
-// Enable Spotlight for development
-Sentry.init({
-  dsn: 'your-dsn',
-  spotlight: process.env.NODE_ENV === 'development',
-});
+Your App → Sentry SDK → Sidecar (port 8969) → UI
+                              ↓
+                        [In-memory store]
+                              ↓
+                    Desktop App / Browser / MCP
 ```
 
-Or simply set the environment variable:
+1. Your application sends telemetry via Sentry SDK
+2. Sidecar receives and stores events in memory
+3. Connected clients (UI, MCP) receive events via SSE
+4. Events are displayed in real-time
 
-```shell
-export SENTRY_SPOTLIGHT=1
-```
+## Multiple Clients
 
-You can send any kind of events to the Sidecar, it forwards them to the Spotlight UI where integrations process and display the data.
+A single sidecar can serve multiple clients simultaneously:
+- **Desktop App** - Dedicated window with built-in UI
+- **Browser** - Web UI at `http://localhost:8969`
+- **CLI** - Stream events to terminal with `spotlight tail`
+- **MCP** - AI assistants query events via Model Context Protocol
 
-<LinkCard title="Sidecar" description="Understand what the sidecar does" href="/docs/sidecar/" />
+## Learn More
 
-Spotlight by default has a Sentry integration, if you are using a Sentry SDK and enable the Spotlight connection (only required on the Server), Spotlight is able
-to render Traces/Errors and more in your frontend.
+<CardGrid>
+  <LinkCard title="Getting Started" href="/docs/setup/" description="Choose how to run Spotlight" />
+  <LinkCard title="Sidecar Details" href="/docs/sidecar/" description="Configuration and SDK integration" />
+</CardGrid>

packages/website/src/content/docs/docs/cli/index.mdx

@@ -23,7 +23,7 @@ The Spotlight CLI (`spotlight`) integrates Spotlight into your terminal workflow
   <TabItem label="npx">
     No installation needed:
     ```bash
-    npx @spotlightjs/spotlight run npm run dev
+    npx @spotlightjs/spotlight run
     ```
   </TabItem>
   <TabItem label="npm global">
@@ -32,8 +32,9 @@ The Spotlight CLI (`spotlight`) integrates Spotlight into your terminal workflow
     ```
   </TabItem>
   <TabItem label="Binary">
+    Download standalone binary to `~/.local/bin/spotlight`:
     ```bash
-    curl -q https://spotlightjs.com/install.sh | sh
+    curl -sL https://spotlightjs.com/install.sh | sh
     ```
   </TabItem>
   <TabItem label="Docker">

packages/website/src/content/docs/docs/contribute/development.mdx

@@ -8,13 +8,13 @@ description: How to run and test Spotlight locally.
 You can run the Sidecar with `SPOTLIGHT_CAPTURE=1` to write the captured data to a file.
 So for example if any Sentry SDK sends an envelope to the Sidecar, it will be written to a file in the current directory looking like this: `application_x_sentry_envelope-1701167447043.txt`.
 
-All these files can be put into `./packages/overlay/_fixtures` and used for testing.
+All these files can be put into `./packages/spotlight/_fixtures` and used for testing.
 Also, they can be attached to Github issues to reproduce bugs.
 
 ### Send sample data to Spotlight
 
-If you run `pnpm sample` in `./packages/overlay` it will send a sample event to the Sidecar and therefore to Spotlight.
-All `.txt` files that are contained in `./packages/overlay/_fixtures` will be sent.
+If you run `pnpm sample` in `./packages/spotlight` it will send a sample event to the Sidecar and therefore to Spotlight.
+All `.txt` files that are contained in `./packages/spotlight/_fixtures` will be sent.
 This can be very handy when testing Spotlight locally.
 
 {/* TODO: Document how to run Spotlight against Spotlight */}
@@ -23,10 +23,10 @@ This can be very handy when testing Spotlight locally.
 
 To get detailed browser console logs for debugging, open the following URL in your browser while the Sidecar is running:
 
-- [`https://localhost:8969/#spotlight-debug`](https://localhost:8969/#spotlight-debug)
+- [`http://localhost:8969/#spotlight-debug`](http://localhost:8969/#spotlight-debug)
 
 This will enable advanced debug output in the browser console.  
-> **Tip:** This is especially useful for inspecting Sidecar behavior. (It may also work with the Overlay, but is primarily intended for the Sidecar.)
+> **Tip:** This is especially useful for inspecting Sidecar behavior.
 
 ### Inspect Sidecar Stream
 

packages/website/src/content/docs/docs/contribute/index.mdx

@@ -42,7 +42,7 @@ pnpm build
 
 ## Development
 
-Depending on what you're doing there's two paths to develop against the overlay.
+Depending on what you're doing there's two paths to develop against Spotlight.
 
 ### With existing data
 
@@ -55,13 +55,13 @@ pnpm dev
 Send sample fixtures to the sidecar with:
 
 ```shell
-pnpm run --filter @spotlightjs/overlay sample
+pnpm run --filter @spotlightjs/spotlight sample
 ```
 
 This will send all the sample data to Spotlight. You can also pick a specific file and pass that as an argument to the script instead:
 
 ```shell
-pnpm run --filter @spotlightjs/overlay sample envelope_php_error.txt
+pnpm run --filter @spotlightjs/spotlight sample envelope_php_error.txt
 ```
 
 ### Linking against an existing project
@@ -89,9 +89,6 @@ The monorepo is mostly straight forward, but here's a quick summary:
 ```
 spotlight
 └── packages
-    ├── overlay      // @spotlightjs/overlay   - the main overlay
-    ├── sidecar      // @spotlightjs/sidecar   - the sidecar (proxy) for streaming data
-    ├── spotlight    // @spotlightjs/spotlight - the main spotlight package, combining overlay and sidecar
-    ├── tsconfig     // @spotlightjs/tsconfig  - shared tsconfig
-    └── website      // @spotlightjs/website   - the main overlay
+    ├── spotlight    // @spotlightjs/spotlight - main package (UI, sidecar, CLI, Electron app)
+    └── website      // @spotlightjs/website   - documentation website
 ```

packages/website/src/content/docs/docs/desktop-app/index.mdx

@@ -212,7 +212,7 @@ Customize the interface:
 - **Panel layout**: Configure which panels are visible
 
 ## When to Use Desktop App vs CLI vs Browser
-
+ 
 Choose the right tool for your workflow:
 
 ### Use Desktop App When:
@@ -227,10 +227,7 @@ Choose the right tool for your workflow:
 - ✅ You're automating with scripts
 - ✅ You want machine-readable output
 
-### Use Browser UI When:
-- ✅ You want overlay on your application
-- ✅ You're debugging frontend web apps
-- ✅ You want integrated developer experience
+Both options provide access to the same UI—the Desktop App has it built-in, while the CLI serves it at [http://localhost:8969](http://localhost:8969).
 
 [Learn more about CLI →](/docs/cli/)