fix: build wheel from source so frontend static assets ship

.github/workflows/publish.yml

@@ -56,7 +56,12 @@ jobs:
           npm run build:backend
 
       - name: Build wheel + sdist
-        run: uv build --out-dir dist/
+        # Build both distributions directly from the source tree. A bare
+        # `uv build` builds the wheel *from the sdist*, and the sdist excludes
+        # the pre-built `static/` assets (gitignored, wheel-only artifacts) —
+        # so the published wheel would ship without the frontend. Passing both
+        # targets explicitly builds each from source, keeping static/ in the wheel.
+        run: uv build --sdist --wheel --out-dir dist/
 
       - name: Upload build artifacts
         uses: actions/upload-artifact@v7

examples/01-local-dev/README.md

@@ -13,7 +13,7 @@ database, so it is the fastest way to try the app or develop against it.
 1. **Configure environment.** Copy the template and set the required values:
 
    ```bash
-   cp .env.example .env
+   cp example.env .env
    ```
 
    Open `.env` and set `SESSION_SECRET_KEY` (the file shows the command to

examples/01-local-dev/example.env

@@ -0,0 +1,46 @@
+# =============================================================================
+# strands-compose-chat — local development configuration
+# Copy this file to ".env" in the same directory and fill in the values below.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# MANDATORY
+# -----------------------------------------------------------------------------
+
+# Signing key for session cookies. Must decode to at least 32 bytes.
+# Generate one with:
+#   python -c "import secrets; print(secrets.token_urlsafe(32))"
+SESSION_SECRET_KEY=
+
+# -----------------------------------------------------------------------------
+# COMMON
+# -----------------------------------------------------------------------------
+
+# Deployment mode: dev | test | prod.
+# Keep "dev" locally: it allows the default SQLite database and relaxed hosts.
+APP_ENV=dev
+
+# First-run administrator account, created automatically on startup.
+# Sign in with these, then create more users from the admin panel at /admin.
+ADMIN_BOOTSTRAP_USERNAME=admin
+ADMIN_BOOTSTRAP_PASSWORD=changeme
+
+# Title shown in the app header and browser tab.
+# CUSTOM_HEADER_TITLE=My Chat
+
+# Database connection. When unset, a local SQLite file (./strands-chat.sqlite)
+# is used, which is ideal for development. Uncomment to use Postgres instead.
+# DATABASE_URL=postgresql+psycopg://user:password@localhost:5432/dbname
+
+# -----------------------------------------------------------------------------
+# OPTIONAL — OIDC single sign-on (usually not needed for local development)
+# Configure one or more providers, then list their ids in OIDC_PROVIDERS.
+# Each provider reads OIDC_<ID>_* variables. Example for "entra":
+# -----------------------------------------------------------------------------
+
+# OIDC_PROVIDERS=["entra"]
+# OIDC_REDIRECT_URI=http://localhost:8000/auth/callback
+# OIDC_ENTRA_DISPLAY_NAME=Microsoft Entra
+# OIDC_ENTRA_DISCOVERY_URL=https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
+# OIDC_ENTRA_CLIENT_ID=<client-id>
+# OIDC_ENTRA_CLIENT_SECRET=<client-secret>

examples/02-docker/README.md

@@ -15,7 +15,7 @@ needed.
 1. **Configure environment.** Copy the template and set the required values:
 
    ```bash
-   cp .env.example .env
+   cp example.env .env
    ```
 
    Open `.env` and set `SESSION_SECRET_KEY` (the file shows the command to
@@ -53,7 +53,7 @@ docker compose down -v             # stop and delete the database volume
   `CORS_ALLOWED_ORIGINS`, and (if using SSO) `OIDC_REDIRECT_URI` to your public
   domain, and serve over HTTPS behind a reverse proxy. In `prod` the session
   cookie is HTTPS-only, so signing in over plain HTTP will not work — HTTPS is
-  required. See `.env.example` and the [examples overview](../README.md) for
+  required. See `example.env` and the [examples overview](../README.md) for
   ECS / Kubernetes guidance.
 
 ## Next steps

examples/02-docker/example.env

@@ -0,0 +1,62 @@
+# =============================================================================
+# strands-compose-chat — Docker Compose configuration
+# Copy this file to ".env" in the same directory and fill in the values below.
+# DATABASE_URL is provided by docker-compose.yaml and is NOT set here.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# MANDATORY
+# -----------------------------------------------------------------------------
+
+# Signing key for session cookies. Must decode to at least 32 bytes.
+# Generate one with:
+#   python -c "import secrets; print(secrets.token_urlsafe(32))"
+SESSION_SECRET_KEY=
+
+# First-run administrator account, created automatically on startup.
+# BOTH must be set, otherwise no admin user is created and you cannot sign in.
+# Use these to sign in, then create more users from the admin panel at /admin.
+ADMIN_BOOTSTRAP_USERNAME=admin
+ADMIN_BOOTSTRAP_PASSWORD=
+
+# -----------------------------------------------------------------------------
+# COMMON
+# -----------------------------------------------------------------------------
+
+# Deployment mode: dev | test | prod.
+# Keep "dev" to run and sign in over plain http://localhost out of the box.
+# For a real deployment set this to "prod" — see "GOING TO PRODUCTION" below.
+APP_ENV=dev
+
+# Allow self-service account registration.
+# Defaults to true when no OIDC provider is configured, false otherwise.
+# AUTH_REGISTRATION_ENABLED=false
+
+# Title shown in the app header and browser tab.
+# CUSTOM_HEADER_TITLE=My Chat
+
+# -----------------------------------------------------------------------------
+# GOING TO PRODUCTION
+# When you deploy for real, set APP_ENV=prod and serve over HTTPS behind a
+# reverse proxy. In "prod" the app:
+#   - rejects SQLite and wildcard ("*") CORS/hosts,
+#   - marks the session cookie HTTPS-only, so signing in over plain HTTP will
+#     silently fail — you MUST use HTTPS.
+# Then set the two values below to your real domain (no "*"):
+# -----------------------------------------------------------------------------
+
+# TRUSTED_HOSTS=["chat.example.com"]
+# CORS_ALLOWED_ORIGINS=["https://chat.example.com"]
+
+# -----------------------------------------------------------------------------
+# OPTIONAL — OIDC single sign-on
+# Configure one or more providers, then list their ids in OIDC_PROVIDERS.
+# Each provider reads OIDC_<ID>_* variables. Example for "entra":
+# -----------------------------------------------------------------------------
+
+# OIDC_PROVIDERS=["entra"]
+# OIDC_REDIRECT_URI=https://chat.example.com/auth/callback
+# OIDC_ENTRA_DISPLAY_NAME=Microsoft Entra
+# OIDC_ENTRA_DISCOVERY_URL=https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
+# OIDC_ENTRA_CLIENT_ID=<client-id>
+# OIDC_ENTRA_CLIENT_SECRET=<client-secret>

examples/README.md

@@ -10,7 +10,7 @@ these examples only provide the deployment glue around it.
 | [`02-docker`](02-docker) | Run a production-like stack on one host | PostgreSQL |
 
 Each example contains its own README with step-by-step instructions and an
-`.env.example` you copy to `.env`. The `.env` files are grouped into
+`example.env` you copy to `.env`. The `.env` files are grouped into
 **mandatory**, **common**, and **optional** settings.
 
 ## Configuration at a glance