From a63543ba8a81b9ad5913ba96aacfc4683a67164f Mon Sep 17 00:00:00 2001
From: rcourtman <courtmanr@gmail.com>
Date: Tue, 24 Mar 2026 15:01:12 +0000
Subject: [PATCH] Align frontend workspace dev runtime commands

---
 CONTRIBUTING.md                                           | 8 ++++++++
 .../v6/internal/subsystems/deployment-installability.md   | 5 +++++
 frontend-modern/package.json                              | 4 ++++
 scripts/tests/test-hot-dev-bg.sh                          | 8 ++++++++
 4 files changed, 25 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 88a436f075..4d5b05efdd 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -80,11 +80,19 @@ examples where possible.
 
 - Managed dev runtime: `npm run dev`
 - Runtime status: `npm run dev:status`
+- Runtime logs: `npm run dev:logs`
+- Managed restart: `npm run dev:restart`
+- Managed backend restart: `npm run dev:backend-restart`
 - Browser recovery proof: `npm run dev:verify`
+- Foreground managed launcher: `npm run dev:foreground`
 - Frontend-only escape hatch: `cd frontend-modern && npm run dev:frontend-only`
 - Tests: `npm run test`
 - Lint: `npm run lint`
 - Format: `npm run format`
+
+The same managed runtime wrappers are available from `frontend-modern/` if you
+start there by habit, so `npm run dev`, `npm run dev:status`, and
+`npm run dev:verify` behave the same way from either workspace.
 - Production build: `npm run build` (syncs the Go embed copy in
   `internal/api/frontend-modern/dist` automatically).
 
diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md
index 3a82bb7d54..4f49981104 100644
--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md
+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md
@@ -183,6 +183,11 @@ must route operators back to the managed runtime entrypoint before falling back
 to process-killing folklore, otherwise the repo keeps reintroducing the same
 split-ownership `5173` versus `7655` confusion through secondary entry
 surfaces.
+When the frontend workspace exposes managed runtime wrappers, they must stay in
+operational parity with the repo-root entry surface for the canonical controls:
+start, status, logs, stop, restart, managed backend restart, verification, and
+the explicit foreground escape hatch. The only intentionally narrower frontend
+workspace exception is the named `dev:frontend-only` raw Vite escape hatch.
 That shared `scripts/install.sh` boundary must also keep one canonical service
 argument builder for the runtime flags it persists. Token-bearing install
 paths, token-file systemd paths, wrapper-script launches, and later service
diff --git a/frontend-modern/package.json b/frontend-modern/package.json
index 08acbb799a..b5e8021adb 100644
--- a/frontend-modern/package.json
+++ b/frontend-modern/package.json
@@ -15,9 +15,13 @@
   "homepage": "https://github.com/rcourtman/Pulse",
   "scripts": {
     "dev": "../scripts/hot-dev-bg.sh start --takeover",
+    "dev:logs": "../scripts/hot-dev-bg.sh logs",
+    "dev:restart": "../scripts/hot-dev-bg.sh restart --takeover",
+    "dev:backend-restart": "../scripts/hot-dev-bg.sh backend-restart",
     "dev:status": "../scripts/hot-dev-bg.sh status",
     "dev:stop": "../scripts/hot-dev-bg.sh stop",
     "dev:verify": "../scripts/hot-dev-bg.sh verify --takeover",
+    "dev:foreground": "../scripts/hot-dev.sh",
     "dev:frontend-only": "vite",
     "build": "node scripts/build-embed-assets.mjs",
     "preview": "vite preview",
diff --git a/scripts/tests/test-hot-dev-bg.sh b/scripts/tests/test-hot-dev-bg.sh
index 300254a58f..e616405260 100755
--- a/scripts/tests/test-hot-dev-bg.sh
+++ b/scripts/tests/test-hot-dev-bg.sh
@@ -193,9 +193,13 @@ with open(os.environ["PACKAGE_JSON_PATH"], "r", encoding="utf-8") as fh:
 
 for key in [
     "dev",
+    "dev:logs",
+    "dev:restart",
+    "dev:backend-restart",
     "dev:status",
     "dev:stop",
     "dev:verify",
+    "dev:foreground",
     "dev:frontend-only",
 ]:
     print(f"{key}={scripts.get(key, '')}")
@@ -203,9 +207,13 @@ PY
   )"
 
   assert_contains "frontend package exposes managed dev start" "${output}" "dev=../scripts/hot-dev-bg.sh start --takeover"
+  assert_contains "frontend package exposes managed dev logs" "${output}" "dev:logs=../scripts/hot-dev-bg.sh logs"
+  assert_contains "frontend package exposes managed dev restart" "${output}" "dev:restart=../scripts/hot-dev-bg.sh restart --takeover"
+  assert_contains "frontend package exposes managed backend restart" "${output}" "dev:backend-restart=../scripts/hot-dev-bg.sh backend-restart"
   assert_contains "frontend package exposes managed dev status" "${output}" "dev:status=../scripts/hot-dev-bg.sh status"
   assert_contains "frontend package exposes managed dev stop" "${output}" "dev:stop=../scripts/hot-dev-bg.sh stop"
   assert_contains "frontend package exposes managed dev verify" "${output}" "dev:verify=../scripts/hot-dev-bg.sh verify --takeover"
+  assert_contains "frontend package keeps foreground managed launcher" "${output}" "dev:foreground=../scripts/hot-dev.sh"
   assert_contains "frontend package keeps explicit frontend-only escape hatch" "${output}" "dev:frontend-only=vite"
 }