chore: tidy local debug scripts

README.md

@@ -76,17 +76,17 @@ Run the API-backed local debug workspace when you need platform, run, platform_w
 
 ```bash
 git clone git@git.npc0.com:admin343/run.git run # once, if the ignored local checkout is missing
-scripts/local-debug-start.sh
+scripts/dev-start.sh
-scripts/local-debug-smoke.sh
+scripts/dev-smoke.sh
 ```
 
 See `docs/local-debug-workspace.md` for ports, disposable data roots, log files, reset steps, smoke evidence, and the required browser walkthrough. This workflow treats frontend local auth fallback as a verification failure.
-Use `LOCAL_DEBUG_SELF_START=true scripts/local-debug-smoke.sh` when you need the smoke command to own the temporary local stack for the duration of the verification.
+Use `LOCAL_DEBUG_SELF_START=true scripts/dev-smoke.sh` when you need the smoke command to own the temporary local stack for the duration of the verification.
 
 For local debug, prefer the managed scripts because they snapshot run source into the closed `.local-debug` build bucket and start the bootstrap worker from the built binary:
 
 ```bash
-scripts/local-debug-start.sh
+scripts/dev-start.sh
 ```
 
 ## Docker Deployment
@@ -154,8 +154,8 @@ Typical local debugging:
 cp platform/.env.example platform/.env
 cp platform_web/.env.example platform_web/.env
 
-scripts/local-debug-start.sh
+scripts/dev-start.sh
-scripts/local-debug-smoke.sh
+scripts/dev-smoke.sh
 ```
 
 Most common edits:

docs/local-debug-workspace.md

@@ -23,7 +23,7 @@ Use the managed local debug scripts for browser-facing verification. Do not star
 - Default platform API: `http://127.0.0.1:18080`.
 - Default platform_web: `http://127.0.0.1:5173`.
 - Default local debug root: `.local-debug/`.
-- Restart with `scripts/local-debug-stop.sh` followed by `scripts/local-debug-start.sh`.
+- Restart with `scripts/dev-stop.sh` followed by `scripts/dev-start.sh`.
 - Use `LOCAL_DEBUG_PLATFORM_PORT`, `LOCAL_DEBUG_WEB_PORT`, and `LOCAL_DEBUG_ROOT` only when a task explicitly needs an isolated stack.
 - When debugging an already-running local page, prefer the current `5173`/`18080` stack and inspect `.local-debug/logs/` before starting anything else.
 
@@ -31,7 +31,7 @@ Use the managed local debug scripts for browser-facing verification. Do not star
 
 ```bash
 git clone git@git.npc0.com:admin343/run.git run # once, if the ignored local checkout is missing
-scripts/local-debug-start.sh
+scripts/dev-start.sh
 ```
 
 The script prints the resolved platform URL, platform_web URL, log files, and the exact local account for browser login:
@@ -42,12 +42,12 @@ The script prints the resolved platform URL, platform_web URL, log files, and th
 Useful defaults can be overridden before running the script:
 
 ```bash
-LOCAL_DEBUG_PLATFORM_PORT=18081 LOCAL_DEBUG_WEB_PORT=5174 scripts/local-debug-start.sh
+LOCAL_DEBUG_PLATFORM_PORT=18081 LOCAL_DEBUG_WEB_PORT=5174 scripts/dev-start.sh
 ```
 
 ## Environment
 
-The scripts source `scripts/local-debug-env.sh`.
+The public commands use shared local debug helpers under `scripts/local-debug/`.
 
 Key platform variables:
 
@@ -85,13 +85,13 @@ Key frontend variables:
 Start the stack, then run:
 
 ```bash
-scripts/local-debug-smoke.sh
+scripts/dev-smoke.sh
 ```
 
 For one-command verification in environments that clean up background processes when a command returns, run:
 
 ```bash
-LOCAL_DEBUG_SELF_START=true scripts/local-debug-smoke.sh
+LOCAL_DEBUG_SELF_START=true scripts/dev-smoke.sh
 ```
 
 The smoke command verifies:
@@ -119,7 +119,7 @@ Run the automated browser acceptance suite when you need repeatable proof for th
 LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance scripts/browser-acceptance.sh
 ```
 
-By default the command safely resets the configured local debug root, starts platform, run worker, and platform_web, runs `scripts/local-debug-smoke.sh`, verifies browser-facing route contracts, and cleans up the self-started stack. Set `BROWSER_ACCEPTANCE_SELF_START=false` to run against an already-started local debug stack.
+By default the command safely resets the configured local debug root, starts platform, run worker, and platform_web, runs `scripts/dev-smoke.sh`, verifies browser-facing route contracts, and cleans up the self-started stack. Set `BROWSER_ACCEPTANCE_SELF_START=false` to run against an already-started local debug stack.
 
 Acceptance evidence is written to:
 
@@ -131,7 +131,7 @@ The evidence records stack URLs, the smoke seed evidence directory, first-party
 
 ## Browser Walkthrough
 
-After `scripts/local-debug-smoke.sh` passes, open platform_web:
+After `scripts/dev-smoke.sh` passes, open platform_web:
 
 ```text
 http://127.0.0.1:5173
@@ -154,13 +154,13 @@ Acceptance requires logical IDs, platform routes, job refs, log refs, artifact r
 ## Stop
 
 ```bash
-scripts/local-debug-stop.sh
+scripts/dev-stop.sh
 ```
 
 ## Reset
 
 ```bash
-scripts/local-debug-reset.sh
+scripts/dev-reset.sh
 ```
 
 Reset stops the local debug processes and deletes only the documented local debug root. By default that root is:
@@ -181,7 +181,7 @@ The start script wraps these commands with the local debug environment:
 
 ```bash
 (cd platform && go run ./cmd/platform)
-source scripts/local-debug-env.sh
+source scripts/local-debug/env.sh
 local_debug_build_bootstrap_run
 "$RUN_BOOTSTRAP_BIN"
 npm --prefix platform_web run dev -- --port 5173

plugins/docs/local-development.md

@@ -17,8 +17,8 @@ Manifest validation rejects raw host paths, raw credentials, direct run sockets,
 For full local stack proof, run the repository local debug workspace:
 
 ```bash
-scripts/local-debug-start.sh
+scripts/dev-start.sh
-scripts/local-debug-smoke.sh
+scripts/dev-smoke.sh
 ```
 
 That workflow registers `plugins/examples/dev-game-plugin/manifest.json`, creates a safe `server-local-debug` fixture through platform APIs, and verifies that plugin/browser evidence exposes only logical IDs, platform routes, job refs, log refs, artifact refs, and safe metadata.

scripts/README.md

@@ -0,0 +1,13 @@
+# Scripts
+
+Use these root-level commands for day-to-day work:
+
+- `scripts/dev-start.sh`: start the local platform API, run worker, and platform_web console.
+- `scripts/dev-smoke.sh`: seed and verify the API-backed local plugin/server fixtures.
+- `scripts/dev-stop.sh`: stop the managed local debug stack.
+- `scripts/dev-reset.sh`: stop the stack and delete only the safe local debug data root.
+- `scripts/browser-acceptance.sh`: run the full self-starting browser acceptance suite.
+- `scripts/check-structure.sh`: verify required repository structure.
+- `scripts/check-all.sh`: run structure, backend, frontend, and plugin checks.
+
+Implementation details for the managed local stack live under `scripts/local-debug/`. Prefer the root commands above instead of calling those internals directly.

scripts/browser-acceptance.sh

@@ -2,8 +2,8 @@
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-# shellcheck source=scripts/local-debug-env.sh
+# shellcheck source=scripts/local-debug/env.sh
-source "$ROOT_DIR/scripts/local-debug-env.sh"
+source "$ROOT_DIR/scripts/local-debug/env.sh"
 
 export BROWSER_ACCEPTANCE_EVIDENCE_DIR="${BROWSER_ACCEPTANCE_EVIDENCE_DIR:-$LOCAL_DEBUG_ROOT/browser-acceptance}"
 export LOCAL_DEBUG_PLATFORM_URL="${LOCAL_DEBUG_PLATFORM_URL:-$(local_debug_platform_url)}"
@@ -16,20 +16,20 @@ cleanup() {
     LOCAL_DEBUG_ROOT="$LOCAL_DEBUG_ROOT" \
     LOCAL_DEBUG_PLATFORM_PORT="$LOCAL_DEBUG_PLATFORM_PORT" \
     LOCAL_DEBUG_WEB_PORT="$LOCAL_DEBUG_WEB_PORT" \
-      "$ROOT_DIR/scripts/local-debug-stop.sh" >/dev/null 2>&1 || true
+    "$ROOT_DIR/scripts/dev-stop.sh" >/dev/null 2>&1 || true
   fi
 }
 
 if [[ "$SELF_STARTED" == "true" ]]; then
   trap cleanup EXIT
-  "$ROOT_DIR/scripts/local-debug-reset.sh"
+  "$ROOT_DIR/scripts/dev-reset.sh"
-  "$ROOT_DIR/scripts/local-debug-start.sh"
+  "$ROOT_DIR/scripts/dev-start.sh"
 else
   curl -fsS "$LOCAL_DEBUG_PLATFORM_URL/healthz" >/dev/null
   curl -fsS "$LOCAL_DEBUG_WEB_URL" >/dev/null
 fi
 
-"$ROOT_DIR/scripts/local-debug-smoke.sh"
+"$ROOT_DIR/scripts/dev-smoke.sh"
 
 mkdir -p "$BROWSER_ACCEPTANCE_EVIDENCE_DIR"
 node "$ROOT_DIR/platform_web/acceptance/browser-acceptance.mjs"

scripts/check-structure.sh

@@ -4,6 +4,8 @@ set -euo pipefail
 required_paths=(
   "AGENTS.md"
   "README.md"
+  "scripts/README.md"
+  "scripts/browser-acceptance.sh"
   "scripts/check-all.sh"
   "platform/AGENTS.md"
   "platform/README.md"
@@ -96,6 +98,15 @@ required_paths=(
   "plugins/examples/scum-server-plugin/actions/status.json"
   "plugins/scripts/validate-manifest.ts"
   "plugins/tests/manifest-validation.test.ts"
+  "scripts/dev-start.sh"
+  "scripts/dev-smoke.sh"
+  "scripts/dev-stop.sh"
+  "scripts/dev-reset.sh"
+  "scripts/local-debug/env.sh"
+  "scripts/local-debug/start.sh"
+  "scripts/local-debug/smoke.sh"
+  "scripts/local-debug/stop.sh"
+  "scripts/local-debug/reset.sh"
   "openspec/changes/bootstrap-game-server-platform-architecture/proposal.md"
   "openspec/changes/bootstrap-game-server-platform-architecture/design.md"
   "openspec/changes/bootstrap-game-server-platform-architecture/tasks.md"

scripts/dev-reset.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec "$ROOT_DIR/scripts/local-debug/reset.sh" "$@"

scripts/dev-smoke.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec "$ROOT_DIR/scripts/local-debug/smoke.sh" "$@"

scripts/dev-start.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec "$ROOT_DIR/scripts/local-debug/start.sh" "$@"

scripts/dev-stop.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec "$ROOT_DIR/scripts/local-debug/stop.sh" "$@"

scripts/local-debug/env.sh

@@ -4,7 +4,7 @@
 set -euo pipefail
 
 LOCAL_DEBUG_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-LOCAL_DEBUG_ROOT_DIR="$(cd "$LOCAL_DEBUG_SCRIPT_DIR/.." && pwd)"
+LOCAL_DEBUG_ROOT_DIR="$(cd "$LOCAL_DEBUG_SCRIPT_DIR/../.." && pwd)"
 
 export LOCAL_DEBUG_ROOT="${LOCAL_DEBUG_ROOT:-$LOCAL_DEBUG_ROOT_DIR/.local-debug}"
 export LOCAL_DEBUG_LOG_DIR="${LOCAL_DEBUG_LOG_DIR:-$LOCAL_DEBUG_ROOT/logs}"
@@ -157,7 +157,7 @@ local_debug_prepare_run_build_source() {
 {
   "sourceDir": "$RUN_SOURCE_DIR",
   "buildSourceRoot": "$RUN_BUILD_SOURCE_ROOT",
-  "createdBy": "scripts/local-debug-env.sh"
+  "createdBy": "scripts/local-debug/env.sh"
 }
 EOF
 }

scripts/local-debug/reset.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-# shellcheck source=scripts/local-debug-env.sh
+# shellcheck source=scripts/local-debug/env.sh
-source "$ROOT_DIR/scripts/local-debug-env.sh"
+source "$ROOT_DIR/scripts/local-debug/env.sh"
 
 case "$LOCAL_DEBUG_ROOT" in
   "$ROOT_DIR/.local-debug" | /private/tmp/browser-local-debug-* | /tmp/browser-local-debug-*)
@@ -15,7 +15,7 @@ case "$LOCAL_DEBUG_ROOT" in
     ;;
 esac
 
-"$ROOT_DIR/scripts/local-debug-stop.sh"
+"$ROOT_DIR/scripts/dev-stop.sh"
 
 printf 'deleting local debug root only: %s\n' "$LOCAL_DEBUG_ROOT"
 rm -rf "$LOCAL_DEBUG_ROOT"

scripts/local-debug/smoke.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-# shellcheck source=scripts/local-debug-env.sh
+# shellcheck source=scripts/local-debug/env.sh
-source "$ROOT_DIR/scripts/local-debug-env.sh"
+source "$ROOT_DIR/scripts/local-debug/env.sh"
 
 PLATFORM_URL="$(local_debug_platform_url)"
 API_URL="$PLATFORM_URL/api/v1"
@@ -244,7 +244,7 @@ if (!plugin.gameClientBridge?.commands?.length) {
 }
 if (missing.length > 0) {
   console.error(`SCUM plugin registration is stale or incomplete: missing ${missing.join(", ")}`);
-  console.error("Run scripts/local-debug-reset.sh, restart the local debug stack, then rerun scripts/local-debug-smoke.sh.");
+  console.error("Run scripts/dev-reset.sh, restart the local debug stack, then rerun scripts/dev-smoke.sh.");
   process.exit(1);
 }
 NODE

scripts/local-debug/start.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-# shellcheck source=scripts/local-debug-env.sh
+# shellcheck source=scripts/local-debug/env.sh
-source "$ROOT_DIR/scripts/local-debug-env.sh"
+source "$ROOT_DIR/scripts/local-debug/env.sh"
 
 mkdir -p "$LOCAL_DEBUG_LOG_DIR" "$LOCAL_DEBUG_PID_DIR" "$PLATFORM_DATA_DIR" "$PLATFORM_LOG_DIR" "$RUN_WORKSPACE_ROOT" "$RUN_SPOOL_ROOT" "$RUN_BUILD_BUCKET_ROOT"
 mkdir -p "$GOCACHE"
@@ -197,7 +197,7 @@ Login with:
   password: operator-local
 
 Run smoke verification:
-  scripts/local-debug-smoke.sh
+  scripts/dev-smoke.sh
 
 Open local console:
   $(local_debug_web_url)

scripts/local-debug/stop.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-# shellcheck source=scripts/local-debug-env.sh
+# shellcheck source=scripts/local-debug/env.sh
-source "$ROOT_DIR/scripts/local-debug-env.sh"
+source "$ROOT_DIR/scripts/local-debug/env.sh"
 
 if [[ ! -d "$LOCAL_DEBUG_PID_DIR" ]]; then
   printf 'no local debug pid directory at %s\n' "$LOCAL_DEBUG_PID_DIR"