@pablozaiden/webapp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo Zaidenvoren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @pablozaiden/webapp
+
+Opinionated Bun + React framework for single-server TypeScript webapps: one Bun process serves the React UI, API routes, passkey auth, API keys, device auth, realtime websocket state, settings, binary builds and Docker images.
+
+## Quick start
+
+Use one of the examples while the package is private:
+
+```bash
+bun install
+bun run dev:notes-todo
+bun run dev:kitchen-sink
+```
+
+Both examples run with Bun native hot reload through `bun --hot`, with no standalone frontend build server and no external `WEB_DIST_DIR`.
+
+## Main exports
+
+| Export | Use |
+| --- | --- |
+| `@pablozaiden/webapp/server` | `createWebAppServer`, route helpers, responses, SQLite store |
+| `@pablozaiden/webapp/web` | `WebAppRoot`, sidebar types, UI controls, realtime hooks |
+| `@pablozaiden/webapp/contracts` | Shared auth/config/device/API-key types |
+| `@pablozaiden/webapp/build` | Bun single-binary compile helper |
+
+See `docs/getting-started.md` for the minimum app shape and `examples/notes-todo` for a realistic app. Use `docs/github-actions.md` when adding CI, Docker and release workflows to an app built with the framework. Use `bun run screenshots` for reproducible manual visual captures. Release/publishing details for this package are in `docs/release.md`.

package/docs/auth-validation.md

@@ -0,0 +1,34 @@
+# Auth validation checklist
+
+Run this checklist before migrating an app or cutting a checkpoint.
+
+## Passkeys
+
+1. Start the app with passkeys enabled and an empty data dir.
+2. Confirm the bootstrap screen appears before the shell.
+3. Register a passkey with the browser/platform authenticator.
+4. Confirm the app shell loads and Settings shows passkey configured.
+5. Click Logout and confirm reload/login requires passkey authentication.
+6. Authenticate with the registered passkey and confirm the shell loads again.
+7. Delete passkey from Settings, confirm the dialog supports Escape, X and Cancel.
+8. Confirm deleting returns to bootstrap on reload.
+
+## API keys
+
+1. Create an API key from Settings and copy the token.
+2. Confirm the token is shown once.
+3. Call a protected API route with `Authorization: Bearer <token>`.
+4. Delete the key from Settings and confirm the confirmation dialog appears.
+5. Confirm the deleted token no longer authenticates.
+
+## Device auth
+
+1. Call `POST /api/auth/device` with `client_id` and `scope`.
+2. Open `verification_uri_complete` in the browser.
+3. Confirm the device approval screen shows client, scope, status and expiry.
+4. Approve the request and exchange `device_code` at `/api/auth/token`.
+5. Use the access token on a scoped route.
+6. Refresh with `/api/auth/refresh` and confirm a new refresh token is returned.
+7. Reuse the old refresh token and confirm `invalid_grant`.
+8. Reuse the consumed device code and confirm `invalid_grant`.
+9. Revoke the active device session from Settings and confirm refresh fails.

package/docs/auth.md

@@ -0,0 +1,35 @@
+# Auth and security
+
+The framework provides three auth modes designed to coexist.
+
+## Passkeys
+
+Passkeys follow a single-passkey bootstrap model:
+
+1. If no passkey exists, registration is allowed.
+2. Once a passkey exists, protected routes require an authenticated passkey browser session, API key, or device bearer token.
+3. Additional public registration is rejected after bootstrap.
+
+Settings owns passkey logout/delete UX.
+
+## API keys
+
+API keys are bearer tokens for scripts and agents. They are stored hashed in SQLite and shown only once at creation. Route `scopes` are enforced for API-key requests; `*` grants all scopes.
+
+Same-origin checks are skipped for API-key and device bearer requests unless a route sets `sameOrigin: "always"`, because non-browser clients usually do not send `Origin`.
+
+## Device auth
+
+Device auth is included in V1:
+
+1. Client calls `POST /api/auth/device` with optional `client_id` and `scope`.
+2. Server returns `device_code`, human `user_code`, `verification_uri`, and polling interval.
+3. Browser user opens `/device?user_code=...` and approves from the same-origin UI.
+4. Client exchanges the approved code at `/api/auth/token`.
+5. Access tokens are JWT bearer tokens; refresh tokens rotate on every refresh.
+
+Device codes are one-use. Reusing a consumed device code or stale refresh token returns `invalid_grant`.
+
+## Same-origin policy
+
+Cookie/browser mutations require matching `Origin` or `Referer` by default. Use `sameOrigin: "never"` only for deliberate public/server-to-server routes; use `sameOrigin: "always"` for especially sensitive endpoints even when bearer tokens are used.

package/docs/deployment.md

@@ -0,0 +1,49 @@
+# Deployment
+
+## Single binary
+
+Use `buildWebAppBinary` from `@pablozaiden/webapp/build`.
+
+```ts
+import { buildWebAppBinary, getBunCompileTargetFromArgs } from "@pablozaiden/webapp/build";
+
+await buildWebAppBinary({
+  entrypoint: import.meta.resolve("./src/index.ts").replace("file://", ""),
+  outfile: "./dist/my-app",
+  target: getBunCompileTargetFromArgs(),
+  define: {
+    WEBAPP_VERSION: JSON.stringify(process.env["WEBAPP_VERSION"] ?? "0.0.0-development"),
+  },
+});
+```
+
+Run the binary with the same CLI contract:
+
+```bash
+MY_APP_PORT=3300 ./dist/my-app serve
+./dist/my-app version
+```
+
+## Docker
+
+Examples include Dockerfiles that copy a Bun-compiled Linux binary into a runtime image. Build the binary for the container architecture first, then build the image:
+
+```bash
+bun run --cwd examples/notes-todo build --target=bun-linux-arm64
+docker build -f examples/notes-todo/Dockerfile -t webapp-notes-todo:local .
+
+bun run --cwd examples/kitchen-sink build --target=bun-linux-arm64
+docker build -f examples/kitchen-sink/Dockerfile -t webapp-kitchen-sink:local .
+```
+
+The example Dockerfiles default to `node:22-bookworm` as a readily available Linux runtime base because the app itself is already a self-contained Bun binary. Use `--target=bun-linux-x64` and pass `--build-arg APP_BINARY=examples/notes-todo/dist/notes-todo-linux-x64` when building an x64 container from a different host. The container should set:
+
+```dockerfile
+ENV MY_APP_HOST=0.0.0.0
+ENV MY_APP_PORT=3000
+ENV MY_APP_DATA_DIR=/data
+```
+
+The framework has no external frontend asset directory, so the compiled binary contains the server and Bun HTML import graph.
+
+For full application CI/CD templates, including a production Dockerfile, PR checks, GHCR publishing on `main`, binary releases and Docker release images, see `docs/github-actions.md`.

package/docs/getting-started.md

@@ -0,0 +1,62 @@
+# Getting started
+
+Apps are one Bun application: backend routes, websocket, React UI and static assets are served by the same server. The framework does not support or require a standalone client dist directory.
+
+```ts
+import webIndex from "./index.html";
+import { createWebAppServer, defineRoutes, jsonResponse } from "@pablozaiden/webapp/server";
+
+const routes = defineRoutes({
+  "/api/items": {
+    GET: () => jsonResponse([{ id: "one", title: "One" }]),
+  },
+  "/api/webhooks/:source/:token": {
+    auth: "public",
+    sameOrigin: "never",
+    POST: () => jsonResponse({ ok: true }),
+  },
+});
+
+const app = createWebAppServer({
+  appName: "My App",
+  envPrefix: "MY_APP",
+  index: webIndex,
+  auth: { passkeys: true, apiKeys: true, deviceAuth: true },
+  realtime: { path: "/api/ws" },
+  routes,
+});
+
+await app.runFromCli();
+```
+
+Frontend entrypoints should import the framework CSS explicitly so Bun hot reload observes style changes:
+
+```ts
+import { WebAppRoot } from "@pablozaiden/webapp/web";
+import "@pablozaiden/webapp/web/styles.css";
+```
+
+Recommended dev script:
+
+```json
+{
+  "scripts": {
+    "dev": "bun --hot src/index.ts serve"
+  }
+}
+```
+
+The app configures an uppercase `envPrefix`; the framework reads only variables under that prefix:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `{PREFIX}_HOST` | `127.0.0.1` | Bind host |
+| `{PREFIX}_PORT` | `3000` | Bind port |
+| `{PREFIX}_DATA_DIR` | `./data` | SQLite persistence directory |
+| `{PREFIX}_LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error`; locks settings log-level control when set |
+| `{PREFIX}_DISABLE_PASSKEY` | unset | Development escape hatch |
+| `{PREFIX}_DISABLE_SAME_ORIGIN_CHECK` | unset | Development/testing escape hatch |
+| `{PREFIX}_PUBLIC_BASE_URL` | request origin | External URL for device auth links |
+| `{PREFIX}_AUTH_ISSUER` | `urn:{prefix}:webapp` | JWT issuer override |
+
+For CI/CD setup in apps built with the framework, use `docs/github-actions.md`. It includes copy-paste GitHub Actions and a production Dockerfile template.

package/docs/github-actions.md

@@ -0,0 +1,421 @@
+# GitHub Actions for framework apps
+
+Use these templates for applications built with `@pablozaiden/webapp`. They follow the same deployment pattern as the reference apps:
+
+1. Pull requests install, build, test and smoke-test the Bun dev server.
+2. Merges to `main` publish a `main` Docker image to GHCR.
+3. Published GitHub releases upload standalone binaries.
+4. Published GitHub releases publish semver Docker images to GHCR.
+
+Replace these placeholders before committing:
+
+| Placeholder | Example | Meaning |
+| --- | --- | --- |
+| `my-app` | `notes` | Binary name, Docker user/group and local container name |
+| `MY_APP` | `NOTES` | `envPrefix` used by `createWebAppServer` |
+| `My App` | `Notes` | Human-readable app name |
+| `src/build.ts` | `apps/server/src/build.ts` | Build script path |
+| `dist/my-app` | `apps/server/dist/my-app` | Default binary path produced by `bun run build` |
+
+The templates assume these package scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "bun --hot src/index.ts serve",
+    "build": "bun src/build.ts",
+    "test": "bun test"
+  }
+}
+```
+
+If the app uses TypeScript typechecking separately, add a `tsc` script and call it from the PR workflow before tests.
+
+## Dockerfile
+
+Place this at `Dockerfile` in the app repository root. It builds the app inside Docker, copies only the standalone Bun binary into a slim runtime image, runs as a non-root user, and exposes `/api/health` as the container healthcheck.
+
+```dockerfile
+FROM oven/bun:1 AS builder
+WORKDIR /app
+COPY . .
+RUN bun install --frozen-lockfile
+RUN bun run build
+
+FROM debian:bookworm-slim
+WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    tini \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/dist/my-app /app/my-app
+
+RUN groupadd --system my-app && \
+    useradd --system --gid my-app --no-create-home my-app
+RUN mkdir -p /app/data && chown -R my-app:my-app /app/data
+
+ENV NODE_ENV=production
+ENV MY_APP_HOST=0.0.0.0
+ENV MY_APP_PORT=8080
+ENV MY_APP_DATA_DIR=/app/data
+
+EXPOSE 8080
+USER my-app
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:${MY_APP_PORT}/api/health || exit 1
+
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["/app/my-app", "serve"]
+```
+
+For apps that need extra OS packages, add them to the runtime `apt-get install` list. Keep `ca-certificates`, `curl` and `tini`.
+
+## Pull request workflow
+
+Place this at `.github/workflows/pr.yml`.
+
+The smoke job starts the native Bun hot-reload dev server, checks `/api/health`, validates that `/` returns HTML, and fetches the first JavaScript and CSS assets referenced by the page. Passkeys and same-origin checks are disabled only for CI startup smoke tests.
+
+```yaml
+name: Pull Request
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Run tests
+        run: bun run test
+
+  smoke-test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Smoke test app startup
+        shell: bash
+        run: |
+          set -euo pipefail
+          MY_APP_DISABLE_PASSKEY=true \
+          MY_APP_DISABLE_SAME_ORIGIN_CHECK=true \
+          MY_APP_PORT=3018 \
+          MY_APP_DATA_DIR="$(mktemp -d)" \
+            bun run dev > /tmp/my-app-pr-smoke.log 2>&1 &
+          app_pid="$!"
+          trap 'kill "$app_pid" 2>/dev/null || true' EXIT
+
+          for _ in {1..60}; do
+            if curl -fsS http://127.0.0.1:3018/api/health >/dev/null; then
+              break
+            fi
+            if ! kill -0 "$app_pid" 2>/dev/null; then
+              cat /tmp/my-app-pr-smoke.log
+              exit 1
+            fi
+            sleep 0.5
+          done
+          curl -fsS http://127.0.0.1:3018/api/health >/dev/null
+
+          html="$(curl -fsS -D /tmp/my-app-root-headers http://127.0.0.1:3018/)"
+          grep -qi '^content-type: text/html' /tmp/my-app-root-headers
+
+          js="$(printf '%s' "$html" | sed -n 's/.*src="\([^"]*\.js\)".*/\1/p' | head -n1)"
+          css="$(printf '%s' "$html" | sed -n 's/.*href="\([^"]*\.css\)".*/\1/p' | head -n1)"
+          test -n "$js"
+          test -n "$css"
+          js="${js#./}"; js="${js#/}"
+          css="${css#./}"; css="${css#/}"
+
+          curl -fsS -D /tmp/my-app-js-headers "http://127.0.0.1:3018/$js" >/dev/null
+          curl -fsS -D /tmp/my-app-css-headers "http://127.0.0.1:3018/$css" >/dev/null
+          grep -qi '^content-type: .*javascript' /tmp/my-app-js-headers
+          grep -qi '^content-type: text/css' /tmp/my-app-css-headers
+
+      - name: Smoke test Docker image
+        shell: bash
+        run: |
+          set -euo pipefail
+          docker build -t my-app-pr-smoke .
+          docker run --rm -d --name my-app-pr-smoke -p 3019:8080 \
+            -e MY_APP_DISABLE_PASSKEY=true \
+            -e MY_APP_DISABLE_SAME_ORIGIN_CHECK=true \
+            my-app-pr-smoke
+          trap 'docker logs my-app-pr-smoke || true; docker stop my-app-pr-smoke >/dev/null 2>&1 || true' EXIT
+
+          for _ in {1..60}; do
+            if curl -fsS http://127.0.0.1:3019/api/health >/dev/null; then
+              break
+            fi
+            sleep 0.5
+          done
+          curl -fsS http://127.0.0.1:3019/api/health >/dev/null
+
+          html="$(curl -fsS -D /tmp/my-app-docker-root-headers http://127.0.0.1:3019/)"
+          grep -qi '^content-type: text/html' /tmp/my-app-docker-root-headers
+
+          js="$(printf '%s' "$html" | sed -n 's/.*src="\([^"]*\.js\)".*/\1/p' | head -n1)"
+          css="$(printf '%s' "$html" | sed -n 's/.*href="\([^"]*\.css\)".*/\1/p' | head -n1)"
+          test -n "$js"
+          test -n "$css"
+          js="${js#./}"; js="${js#/}"
+          css="${css#./}"; css="${css#/}"
+
+          curl -fsS -D /tmp/my-app-docker-js-headers "http://127.0.0.1:3019/$js" >/dev/null
+          curl -fsS -D /tmp/my-app-docker-css-headers "http://127.0.0.1:3019/$css" >/dev/null
+          grep -qi '^content-type: .*javascript' /tmp/my-app-docker-js-headers
+          grep -qi '^content-type: text/css' /tmp/my-app-docker-css-headers
+```
+
+Add route-specific checks after the asset checks, for example a public ping endpoint or a readonly API that works with passkeys disabled.
+
+## Main branch Docker workflow
+
+Place this at `.github/workflows/docker-main.yml`.
+
+It publishes `ghcr.io/<owner>/<repo>:main` after merges to `main`, updates `package.json` to a pre-release version based on the latest GitHub release, and runs a container health smoke test.
+
+```yaml
+name: Docker Main
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Get latest release version
+        id: latest-release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          latest_tag="$(gh release view --json tagName -q '.tagName' 2>/dev/null || echo "v0.0.0")"
+          latest_version="${latest_tag#v}"
+          echo "version=${latest_version}" >> "$GITHUB_OUTPUT"
+
+      - name: Update package.json version
+        run: |
+          timestamp="$(date -u +"%Y-%m-%d-%H-%M")"
+          short_sha="${GITHUB_SHA::7}"
+          version="${{ steps.latest-release.outputs.version }}-main-${timestamp}-${short_sha}"
+          jq --arg v "$version" '.version = $v' package.json > package.json.tmp
+          mv package.json.tmp package.json
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Normalize image name
+        id: image
+        run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7
+        with:
+          context: .
+          push: true
+          load: true
+          tags: ${{ steps.image.outputs.name }}:main
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64
+
+      - name: Test container healthcheck
+        shell: bash
+        run: |
+          set -euo pipefail
+          docker run -d --name my-app-main-smoke -p 8080:8080 \
+            -e MY_APP_DISABLE_PASSKEY=true \
+            -e MY_APP_DISABLE_SAME_ORIGIN_CHECK=true \
+            ${{ steps.image.outputs.name }}:main
+          trap 'docker logs my-app-main-smoke || true; docker rm -f my-app-main-smoke >/dev/null 2>&1 || true' EXIT
+
+          for _ in {1..30}; do
+            status="$(docker inspect --format='{{.State.Health.Status}}' my-app-main-smoke 2>/dev/null || echo starting)"
+            if [ "$status" = "healthy" ]; then
+              break
+            fi
+            sleep 2
+          done
+
+          test "$(docker inspect --format='{{.State.Health.Status}}' my-app-main-smoke)" = "healthy"
+          curl -fsS http://127.0.0.1:8080/api/health >/dev/null
+```
+
+## Binary release workflow
+
+Place this at `.github/workflows/binary-release.yml`.
+
+It delegates cross-platform binary builds to the reusable binary release workflow and uploads checksummed assets to the GitHub release.
+
+```yaml
+name: Binary Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  binaries:
+    uses: pablozaiden/installer/.github/workflows/reusable-binary-release.yml@2e28bc9fbf69385ac5172e526a1268f72db02363
+    permissions:
+      contents: write
+    with:
+      prebuild_command: bun run build
+      binaries: |
+        [
+          {
+            "name": "my-app",
+            "asset_prefix": "my-app",
+            "build_command": "bun src/build.ts --target=$BUN_TARGET",
+            "output_path": "dist/my-app-$RELEASE_TARGET"
+          }
+        ]
+```
+
+If `bun run build` already builds a local default binary and your `src/build.ts` supports `--target`, keep `prebuild_command: bun run build` to validate the app before producing release assets.
+
+## Docker release workflow
+
+Place this at `.github/workflows/docker-release.yml`.
+
+It publishes versioned GHCR images when a GitHub release is published:
+
+```yaml
+name: Docker Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Update package.json version
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          jq --arg v "$version" '.version = $v' package.json > package.json.tmp
+          mv package.json.tmp package.json
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@68827325e0b33c7199eb31dd4e31fbe9023e06e3 # v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Normalize image name
+        id: image
+        run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6
+        with:
+          images: ${{ steps.image.outputs.name }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64,linux/arm64
+```
+
+## Build script for release assets
+
+The binary release workflow expects the app build script to accept `--target` and include the target suffix in the output filename. A minimal `src/build.ts`:
+
+```ts
+import { buildWebAppBinary, getBunCompileTargetFromArgs } from "@pablozaiden/webapp/build";
+
+const target = getBunCompileTargetFromArgs();
+const suffix = target ? `-${target.replace("bun-", "")}` : "";
+
+await buildWebAppBinary({
+  entrypoint: "src/index.ts",
+  outfile: `dist/my-app${suffix}`,
+  target,
+  define: {
+    WEBAPP_VERSION: JSON.stringify(process.env["WEBAPP_VERSION"] ?? "0.0.0-development"),
+  },
+});
+```
+
+## Adaptation checklist
+
+1. Replace `my-app` everywhere with the binary name.
+2. Replace `MY_APP` everywhere with the app `envPrefix`.
+3. Make sure `createWebAppServer({ envPrefix: "MY_APP" })` matches the workflow and Dockerfile env vars.
+4. Keep `/api/health` available; it is provided by the framework server.
+5. Add app-specific smoke checks after the generic health and asset checks.
+6. Keep passkey/same-origin disable flags only in CI smoke jobs, not production deploys.
+7. For monorepos, update `src/build.ts`, `dist/my-app` and build commands to the app package path.