diff --git a/justfile b/justfile
new file mode 100644
index 0000000..c83575a
--- /dev/null
+++ b/justfile
@@ -0,0 +1,107 @@
+set shell := ["bash", "-uc"]
+
+# Keep files created by containers owned by the host user.
+export UID := `id -u`
+export GID := `id -g`
+
+default:
+    @just --list
+
+# First-time setup: build, install PHP deps, create .env, migrate and seed.
+setup:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    if [ ! -f .env ]; then
+        cp .env.docker.example .env
+    fi
+
+    docker compose build
+    docker compose run --rm --no-deps app composer install
+
+    if ! grep -q '^APP_KEY=base64:' .env; then
+        docker compose run --rm --no-deps app php artisan key:generate --force
+    fi
+
+    docker compose up -d --wait db
+    docker compose run --rm app php artisan migrate --force
+
+    # Only seed the demo data on a fresh database.
+    if [ "$(docker compose exec -T db mysql -N -B -upollux -psecret pollux -e 'SELECT COUNT(*) FROM scopes' 2>/dev/null || echo 0)" = "0" ]; then
+        docker compose run --rm app php artisan db:seed --class=ConstantsSeeder --force
+        docker compose run --rm app php artisan db:seed --class=TestDataSeeder --force
+    else
+        echo "Database already seeded; skipping demo data."
+    fi
+
+    docker compose run --rm app php artisan db:seed --class=DevUserSeeder --force
+
+    echo "Setup complete. Run 'just up', then open http://localhost:8000"
+    echo "Login: dev@pollux.local / password"
+
+# Start the app and database in the foreground.
+up *args:
+    docker compose up --build {{args}}
+
+# Start the app and database in the background.
+start:
+    docker compose up -d --build
+
+# Stop the app and database.
+down:
+    docker compose down
+
+# Tail logs. Optionally pass a service name: just logs app
+logs *args:
+    docker compose logs -f {{args}}
+
+# Run an artisan command: just artisan route:list
+artisan *args:
+    docker compose run --rm app php artisan {{args}}
+
+# Run a composer command: just composer require foo/bar
+composer *args:
+    docker compose run --rm app composer {{args}}
+
+# Open a shell in the app container.
+shell:
+    docker compose run --rm app bash
+
+# Open a MySQL shell.
+db:
+    docker compose up -d --wait db
+    docker compose exec db mysql -upollux -psecret pollux
+
+# Run migrations.
+migrate:
+    docker compose run --rm app php artisan migrate
+
+# Add the demo/test dataset to an existing database.
+seed:
+    docker compose run --rm app php artisan db:seed --class=TestDataSeeder
+
+# Recreate the database and load the full dataset from database/seeds/data/real.
+seed-real:
+    docker compose run --rm app php artisan migrate:fresh
+    docker compose run --rm app php artisan db:seed --force
+    docker compose run --rm app php artisan db:seed --class=DevUserSeeder --force
+
+# Recreate the database and load test data.
+fresh:
+    docker compose run --rm app php artisan migrate:fresh
+    docker compose run --rm app php artisan db:seed --class=ConstantsSeeder
+    docker compose run --rm app php artisan db:seed --class=TestDataSeeder
+    docker compose run --rm app php artisan db:seed --class=DevUserSeeder
+
+# Run the test suite.
+test *args:
+    docker compose run --rm --no-deps app vendor/bin/phpunit {{args}}
+
+# Build frontend assets (uses the mise-pinned Node 10).
+assets:
+    mise exec -- npm install
+    mise exec -- npm run dev
+
+# Watch frontend assets.
+watch:
+    mise exec -- npm run watch