docs: lifecycle screenshots + top-right nav pills

README.md

@@ -32,6 +32,10 @@ Network switch port discovery tool. Captures CDP (Cisco Discovery Protocol), LLD
 
 📖 **Docs:** <https://packetthrower.github.io/PortFinder/> · 📝 [**Changelog**](CHANGELOG.md)
 
+<p align="center">
+  <img src="docs-next/public/screenshots/macos.png" alt="PortFinder on macOS showing a captured LLDP result" width="420">
+</p>
+
 > **4.x is the pure-Rust rewrite.** Zed's [gpui](https://www.gpui.rs/)
 > replaces the Tauri 2 + Svelte 5 stack from the 3.x line, which is
 > preserved on the [`tauri-version`](https://github.com/packetThrower/PortFinder/tree/tauri-version)

docs-next/astro.config.mjs

@@ -19,11 +19,10 @@ export default defineConfig({
 			customCss: ['./src/styles/theme.css'],
 			components: {
 				Hero: './src/components/Hero.astro',
-				// Adds a "← packetThrower" back-link pill to the
-				// left of the default site title. The default
-				// component (logo + wordmark) is still rendered
-				// alongside it — see SiteTitle.astro.
-				SiteTitle: './src/components/SiteTitle.astro',
+				// Adds "← packetThrower" + "Docs" pills to the
+				// top-right, left of the GitHub icon — same pattern
+				// as Baudrun's docs site. See SocialIcons.astro.
+				SocialIcons: './src/components/SocialIcons.astro',
 			},
 			social: [
 				{

docs-next/src/components/SocialIcons.astro

@@ -0,0 +1,47 @@
+---
+// Override of Starlight's SocialIcons component. Renders two
+// quick-access pills on the left — a "← packetThrower" back-link
+// to the parent landing page, then a "Docs" pill to /install/ —
+// then defers to Starlight's default rendering (the GitHub icon,
+// etc.) for the rest. Wraps rather than re-implements so future
+// Starlight versions that change the social-icon pipeline still
+// work — we only own the `.pf-nav-pill` extras.
+//
+// The back-link is an absolute URL on purpose: Astro's configured
+// `base` is `/PortFinder/`, so a relative `/` would resolve to
+// `/PortFinder/` (this site's own root). The absolute form skips
+// the base prefix and reaches the actual parent at
+// https://packetthrower.github.io/.
+import Default from '@astrojs/starlight/components/SocialIcons.astro';
+---
+
+<a class="pf-nav-pill sl-flex" href="https://packetthrower.github.io/">
+	<span aria-hidden="true">←</span> packetThrower
+</a>
+
+<a class="pf-nav-pill sl-flex" href="/PortFinder/install/">
+	Docs
+</a>
+
+<Default {...Astro.props}><slot /></Default>
+
+<style>
+	.pf-nav-pill {
+		align-items: center;
+		gap: 0.4em;
+		padding: 0.35em 0.85em;
+		border-radius: 999px;
+		font-size: 0.88rem;
+		font-weight: 500;
+		text-decoration: none;
+		color: var(--sl-color-text);
+		box-shadow: inset 0 0 0 1px var(--sl-color-hairline);
+		transition:
+			color 140ms ease,
+			box-shadow 140ms ease;
+	}
+	.pf-nav-pill:hover {
+		color: var(--sl-color-text-accent);
+		box-shadow: inset 0 0 0 1px var(--sl-color-text-accent);
+	}
+</style>

docs-next/src/content/docs/install.mdx

@@ -22,6 +22,8 @@ Pre-built binaries for every release live on the [Releases page](https://github.
 ### Homebrew (recommended)
 
 ```bash
+brew tap packetThrower/tap
+brew trust packetThrower/tap   # Homebrew 6.0.0+: trust the tap before installing
 brew install --cask packetThrower/tap/portfinder
 ```
 

docs-next/src/content/docs/usage/gui.mdx

@@ -12,16 +12,31 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
 3. **Click Start.** Most switches send a discovery packet every 30–60 seconds, so it usually takes a few seconds for the first frame to arrive.
 4. **Read the result.** Switch name, IP, port, VLAN, voice VLAN, MTU, and model populate the result card.
 
-## On each platform
-
-Native widgets per platform — same workflow, different chrome.
+Each stage, on macOS:
 
 <Tabs>
-<TabItem label="macOS">
+<TabItem label="Ready">
+
+![PortFinder ready to capture — interface and protocol selected](/PortFinder/screenshots/macos_start.png)
+
+</TabItem>
+<TabItem label="Capturing">
+
+![PortFinder capturing — progress bar running, Stop button active](/PortFinder/screenshots/macos_sniffing.png)
+
+</TabItem>
+<TabItem label="Result">
 
-![PortFinder on macOS](/PortFinder/screenshots/macos.png)
+![PortFinder showing a captured LLDP result](/PortFinder/screenshots/macos.png)
 
 </TabItem>
+</Tabs>
+
+## On each platform
+
+Same workflow, different chrome — macOS is shown above.
+
+<Tabs>
 <TabItem label="Windows">
 
 ![PortFinder on Windows](/PortFinder/screenshots/windows.png)