From 7d36be297b0346eb08c163f424344ab65c7a468a Mon Sep 17 00:00:00 2001
From: JSONbored <49853598+JSONbored@users.noreply.github.com>
Date: Mon, 20 Jul 2026 22:04:35 -0700
Subject: [PATCH] docs(contributing): correct the false port-8080 strictPort
 claim (#7628)

SKILL.md claimed "Vite forces port 8080 regardless of what you
request." False outside a Lovable sandbox: strictPort: true in
@lovable.dev/vite-tanstack-config is gated on isSandbox -- on a
normal contributor machine, CI runner, or AI-agent worktree, port
8080 is a plain default with no strictPort, so an occupied 8080
silently shifts to the next free port with only one easy-to-miss
console line and no error.

Reproduced directly: ran the dev server with 8080 already occupied,
got "Port 8080 is in use, trying another one..." then a server on
8081, no sandbox warning. Exactly the failure mode the doc itself
warns about ("preview_screenshot-style tooling just hangs waiting for
the server"), except the doc framed the port as guaranteed instead of
best-effort -- misleading guidance for the exact audience (AI agents
following it literally) most likely to hardcode the port without
reading the startup log.

Corrects the doc to describe the actual behavior and tells the reader
to check the server's real Local: URL instead of assuming 8080.

Closes #7628
---
 .claude/skills/contributing-to-loopover/SKILL.md | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/.claude/skills/contributing-to-loopover/SKILL.md b/.claude/skills/contributing-to-loopover/SKILL.md
index f3a9c9c485..3d3674704b 100644
--- a/.claude/skills/contributing-to-loopover/SKILL.md
+++ b/.claude/skills/contributing-to-loopover/SKILL.md
@@ -267,9 +267,14 @@ merge instead of a one-shot close.
 below needs real, clickable thumbnail URLs — here's how to get them when you can't drag-and-drop into
 GitHub's web editor (which needs a human browser session an AI coding tool can't drive end-to-end):
 
-1. **Local dev server:** `npm --prefix apps/loopover-ui run dev` (Vite forces port **8080** regardless
-   of what you request — use that port in any launch config, or `preview_screenshot`-style tooling just
-   hangs waiting for the server). For an auth-gated page, use the sanctioned local-preview escape hatch
+1. **Local dev server:** `npm --prefix apps/loopover-ui run dev`. Vite *defaults* to port **8080**, but
+   only *forces* it — hard-failing if taken — inside a Lovable sandbox; `@lovable.dev/vite-tanstack-config`'s
+   `strictPort: true` is gated on `isSandbox`. On a normal contributor machine, CI runner, or AI-agent
+   worktree, an already-occupied 8080 silently shifts to the next free port with only one easy-to-miss
+   console line (`Port 8080 is in use, trying another one...`) and no error. **Read the server's actual
+   `Local:` URL from its startup output before hardcoding a port into any launch config** — don't assume
+   8080; `preview_screenshot`-style tooling that assumes it unconditionally just hangs waiting for a
+   server that's actually listening on 8081+. For an auth-gated page, use the sanctioned local-preview escape hatch
    instead of real GitHub OAuth: `useSession().signInPreview()` (`apps/loopover-ui/src/lib/api/session.ts`),
    gated on `import.meta.env.DEV` — it sets a synthetic session client-side with no network write. Click
    the "Continue with local preview" button in the sign-in wall rather than calling the hook indirectly