diff --git a/scripts/dev.sh b/scripts/dev.sh
new file mode 100755
index 0000000..ce4dfcc
--- /dev/null
+++ b/scripts/dev.sh
@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Lifecycle for the local dev stack. All language tooling (pnpm, tests,
+# typecheck, drizzle-kit) runs in the long-running `tools` container.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Lifecycle for the local dev stack.
+
+Usage:
+  scripts/dev.sh up                       Start all dev services in the background.
+  scripts/dev.sh down                     Stop the stack.
+  scripts/dev.sh logs [service]           Tail logs (all services, or one).
+  scripts/dev.sh status                   Print 'OK' if tools is running, else exit 1.
+  scripts/dev.sh build [service]          Build images without starting.
+  scripts/dev.sh exec <cmd...>            Run a command inside the tools container.
+  scripts/dev.sh pnpm <args...>           Shortcut for: exec pnpm <args>
+  scripts/dev.sh shell                    Open an interactive shell in tools.
+  scripts/dev.sh restart-bot              Recreate the bot container only.
+
+Environment:
+  NO_SUDO=1   Skip the 'sudo' prefix (use if your user is in the docker group).
+EOF
+}
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "${ROOT_DIR}"
+
+# Export host UID/GID so the tools container can write files owned by you.
+export HOST_UID="$(id -u)"
+export HOST_GID="$(id -g)"
+
+SUDO="sudo"
+[[ "${NO_SUDO:-0}" == "1" ]] && SUDO=""
+COMPOSE=(${SUDO} docker compose --env-file .env.development -f docker-compose.base.yml -f docker-compose.dev.yml)
+
+case "${1:-}" in
+  -h|--help|help) usage; exit 0 ;;
+  "") usage >&2; exit 1 ;;
+esac
+
+if [[ ! -f .env.development ]]; then
+  echo "ERROR: .env.development not found at repo root." >&2
+  echo "       Copy envs/.env.example and fill in real values." >&2
+  exit 2
+fi
+
+cmd="${1}"
+shift || true
+
+case "${cmd}" in
+  up)
+    "${COMPOSE[@]}" up -d --build
+    "${COMPOSE[@]}" ps
+    ;;
+  down)
+    "${COMPOSE[@]}" down --remove-orphans
+    ;;
+  logs)
+    if [[ $# -ge 1 ]]; then
+      "${COMPOSE[@]}" logs -f "$1"
+    else
+      "${COMPOSE[@]}" logs -f
+    fi
+    ;;
+  status)
+    if "${COMPOSE[@]}" ps --status running --services 2>/dev/null | grep -q '^tools$'; then
+      echo OK
+    else
+      echo "ERROR: tools container not running. Run 'scripts/dev.sh up' first." >&2
+      exit 1
+    fi
+    ;;
+  build)
+    "${COMPOSE[@]}" build "$@"
+    ;;
+  exec)
+    if [[ $# -lt 1 ]]; then
+      echo "ERROR: exec requires a command" >&2
+      exit 2
+    fi
+    "${COMPOSE[@]}" exec -T tools "$@"
+    ;;
+  pnpm)
+    "${COMPOSE[@]}" exec -T tools pnpm "$@"
+    ;;
+  shell)
+    "${COMPOSE[@]}" exec tools sh
+    ;;
+  restart-bot)
+    "${COMPOSE[@]}" up -d --force-recreate --no-deps bot
+    ;;
+  *)
+    echo "unknown command: ${cmd}" >&2
+    usage >&2
+    exit 1
+    ;;
+esac