Fix embedded frontend dev entrypoint guidance

docs/release-control/v6/internal/subsystems/agent-lifecycle.md

@@ -539,6 +539,12 @@ That same shared `internal/api/` boundary also assumes manual auth env writes
 and first-session status reads resolve the `.env` path through the shared
 auth-path helper, so lifecycle-adjacent setup and password flows do not each
 reconstruct their own `/etc/pulse/.env` fallback logic.
+That same shared `internal/api/` boundary also assumes generated developer
+warnings do not mis-teach the local runtime split: the embedded frontend notice
+under `internal/api/DO_NOT_EDIT_FRONTEND_HERE.md` may point operators to the
+shared backend on `:7655` when explaining the proxy relationship, but it must
+keep the hot-reload browser entrypoint on `http://127.0.0.1:5173` so lifecycle-
+adjacent setup and install guidance does not regress to the backend port.
 Those same lifecycle-adjacent setup and password flows must now also route
 `.env` writes through the shared writable auth-env helper instead of
 re-implementing config-path writes plus data-path fallback ordering inline.

docs/release-control/v6/internal/subsystems/api-contracts.md

@@ -372,6 +372,13 @@ surface as well: `internal/api/agent_install_command_shared.go`,
 `internal/api/config_setup_handlers.go`, and `internal/api/unified_agent.go`
 must carry a direct API-contract proof path instead of relying only on the
 generic `internal/api/` backend payload prefix.
+That same backend-owned `internal/api/` boundary also includes the generated
+embedded-frontend warning surface used during local development.
+`internal/api/DO_NOT_EDIT_FRONTEND_HERE.md` must direct developers to edit
+`frontend-modern/src`, identify `http://127.0.0.1:5173` as the hot-reload
+frontend dev shell, and describe `http://127.0.0.1:7655` as the proxied
+backend dependency instead of teaching `7655` as the browser-facing dev
+entrypoint.
 That shared frontend install-command helper must also stay under explicit proof
 routing instead of remaining an orphan utility: changes in
 `frontend-modern/src/utils/agentInstallCommand.ts` must carry the direct

docs/release-control/v6/internal/subsystems/storage-recovery.md

@@ -437,6 +437,12 @@ That same shared boundary also assumes manual auth env writes and auth-status
 reads resolve `.env` through the shared auth-path helper, so storage-adjacent
 recovery and setup flows do not keep neighboring `/etc/pulse/.env` fallback
 logic alive after the runtime data-dir authority has been centralized.
+That same shared `internal/api/` dependency also assumes generated developer
+warnings keep the local browser/runtime split accurate: the embedded frontend
+notice under `internal/api/DO_NOT_EDIT_FRONTEND_HERE.md` may describe `:7655`
+as the proxied backend dependency, but it must preserve
+`http://127.0.0.1:5173` as the hot-reload browser entrypoint so storage- and
+recovery-adjacent setup guidance does not drift back to the backend port.
 That same shared boundary now also owns writable auth-env fallback order, so
 storage-adjacent setup and recovery flows may not keep per-handler config-path
 write branches with private data-path fallback logic once the shared helper

internal/api/DO_NOT_EDIT_FRONTEND_HERE.md

@@ -16,8 +16,9 @@ This `frontend-modern` directory is **AUTO-GENERATED** during builds.
 
 ## How to edit frontend code
 1. Edit files in `${PULSE_REPOS_DIR}/pulse/frontend-modern/src/`
-2. The dev server (port 7655) will hot-reload
-3. When building for production, the Makefile copies it here
+2. The frontend dev shell on `http://127.0.0.1:5173` will hot-reload
+3. That dev shell proxies `/api` and `/ws` to the backend on `http://127.0.0.1:7655`
+4. When building for production, the Makefile copies it here
 
 ---
 This file exists to prevent confusion. The directory structure is intentional and required by Go's limitations.

internal/api/contract_test.go

@@ -4720,6 +4720,25 @@ func TestContract_UnifiedAuditLimitCapsOversizedRequests(t *testing.T) {
 	}
 }
 
+func TestContract_EmbeddedFrontendWarningUsesCanonicalDevEntrypoints(t *testing.T) {
+	path := filepath.Join("DO_NOT_EDIT_FRONTEND_HERE.md")
+	body, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read embedded frontend warning: %v", err)
+	}
+
+	text := string(body)
+	if !strings.Contains(text, "http://127.0.0.1:5173") {
+		t.Fatalf("embedded frontend warning must point to the frontend dev shell on 5173")
+	}
+	if !strings.Contains(text, "http://127.0.0.1:7655") {
+		t.Fatalf("embedded frontend warning must identify the backend on 7655")
+	}
+	if strings.Contains(text, "The dev server (port 7655) will hot-reload") {
+		t.Fatalf("embedded frontend warning must not describe 7655 as the hot-reload dev server")
+	}
+}
+
 func mustStreamEvent(t *testing.T, eventType string, data interface{}) chat.StreamEvent {
 	t.Helper()