@brendanbank/create-atrium-host 0.15.0

package/template/.env.example

@@ -0,0 +1,33 @@
+ENVIRONMENT=dev
+APP_TIMEZONE=UTC
+
+# Long random strings. `openssl rand -hex 48` for each.
+APP_SECRET_KEY=replace-me-with-openssl-rand-hex-48
+JWT_SECRET=replace-me-with-openssl-rand-hex-48
+JWT_ACCESS_TOKEN_EXPIRE_MINUTES=10080
+
+# The public URL the browser hits. Used in email links.
+APP_BASE_URL=http://localhost:8000
+
+# MySQL.
+MYSQL_ROOT_PASSWORD=root-pw-change-me
+MYSQL_DATABASE=__HOST_PKG__
+MYSQL_USER=__HOST_PKG__
+MYSQL_PASSWORD=db-pw-change-me
+DATABASE_URL=mysql+aiomysql://${MYSQL_USER}:${MYSQL_PASSWORD}@mysql:3306/${MYSQL_DATABASE}
+
+# WebAuthn — the host the credential is bound to (no scheme/port) and
+# the full origin the registration ceremony runs from. localhost is
+# fine for dev; switch to your real hostname in prod.
+WEBAUTHN_RP_ID=localhost
+WEBAUTHN_RP_NAME=__BRAND_NAME__
+WEBAUTHN_ORIGIN=http://localhost:8000
+
+# Mail. `console` prints to stdout; switch to `smtp` and fill
+# SMTP_HOST/SMTP_PORT/SMTP_USERNAME/SMTP_PASSWORD in prod.
+MAIL_BACKEND=console
+MAIL_FROM=no-reply@example.com
+
+# Pin the atrium base image. X.Y for patch uptake; X.Y.Z for fully
+# deterministic deploys.
+ATRIUM_IMAGE=ghcr.io/brendanbank/atrium:__ATRIUM_VERSION__

package/template/.github/dependabot.yml

@@ -0,0 +1,56 @@
+version: 2
+# Each ecosystem declares two groups:
+#   - *-version-updates   (applies-to: version-updates)
+#   - *-security-updates  (applies-to: security-updates)
+#
+# Without the explicit security-updates group, Dependabot opens one
+# PR per advisory even when the `groups` block is set for version
+# updates.
+updates:
+  - package-ecosystem: "pip"
+    directory: "/backend"
+    schedule:
+      interval: "weekly"
+    groups:
+      pip-version-updates:
+        applies-to: version-updates
+        patterns: ["*"]
+      pip-security-updates:
+        applies-to: security-updates
+        patterns: ["*"]
+
+  - package-ecosystem: "npm"
+    directory: "/frontend"
+    schedule:
+      interval: "weekly"
+    groups:
+      npm-version-updates:
+        applies-to: version-updates
+        patterns: ["*"]
+      npm-security-updates:
+        applies-to: security-updates
+        patterns: ["*"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions-version-updates:
+        applies-to: version-updates
+        patterns: ["*"]
+      actions-security-updates:
+        applies-to: security-updates
+        patterns: ["*"]
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      docker-version-updates:
+        applies-to: version-updates
+        patterns: ["*"]
+      docker-security-updates:
+        applies-to: security-updates
+        patterns: ["*"]

package/template/.github/workflows/ci.yml

@@ -0,0 +1,103 @@
+name: CI
+
+on:
+  pull_request:
+    paths-ignore:
+      - "**.md"
+      - "docs/**"
+      - "LICENCE.md"
+  push:
+    branches: [main, master]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  frontend:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.33.1
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+
+      - name: Install deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Unit tests
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build
+
+  smoke:
+    # Stand up the full stack (atrium image + this host extension on
+    # top), run migrations, seed an admin, hit /readyz. Catches the
+    # bootstrap-time failures (missing env, broken init_app, alembic
+    # chain mismatch) the frontend job won't see.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Prepare smoke .env
+        run: |
+          cat > .env <<'EOF'
+          ENVIRONMENT=dev
+          APP_TIMEZONE=UTC
+          APP_SECRET_KEY=smoke-secret
+          APP_BASE_URL=http://localhost:8000
+          MYSQL_ROOT_PASSWORD=smoke-root-pw
+          MYSQL_DATABASE=__HOST_PKG__
+          MYSQL_USER=__HOST_PKG__
+          MYSQL_PASSWORD=smoke-pw
+          DATABASE_URL=mysql+aiomysql://__HOST_PKG__:smoke-pw@mysql:3306/__HOST_PKG__
+          JWT_SECRET=smoke-jwt-secret
+          JWT_ACCESS_TOKEN_EXPIRE_MINUTES=10080
+          WEBAUTHN_RP_ID=localhost
+          WEBAUTHN_RP_NAME=__BRAND_NAME__
+          WEBAUTHN_ORIGIN=http://localhost:8000
+          MAIL_BACKEND=console
+          MAIL_FROM=no-reply@example.com
+          ATRIUM_IMAGE=ghcr.io/brendanbank/atrium:__ATRIUM_VERSION__
+          EOF
+
+      - name: Build + start stack
+        run: docker compose up -d --build
+
+      - name: Wait for API
+        run: |
+          for i in $(seq 1 40); do
+            if curl -fsS http://localhost:8000/readyz > /dev/null; then exit 0; fi
+            sleep 3
+          done
+          echo "API did not become ready" >&2
+          docker compose logs api
+          exit 1
+
+      - name: Run migrations
+        run: make migrate
+
+      - name: Seed admin
+        run: make seed-admin EMAIL=admin@example.com PASSWORD=smoke-pw-12345
+
+      - name: Backend smoke tests
+        run: make test-backend
+
+      - name: Dump stack logs on failure
+        if: failure()
+        run: docker compose logs

package/template/Dockerfile

@@ -0,0 +1,46 @@
+# __BRAND_NAME__ host extension image. Two stages:
+#
+#   1. frontend-builder — node + pnpm, builds the host SPA bundle
+#      (a single main.js dynamic-imported by atrium at runtime).
+#   2. runtime — FROM the published atrium image, pip-installs the
+#      host backend package into atrium's venv, and copies the host
+#      bundle into /opt/atrium/static/host so atrium serves it at
+#      /host/main.js (same origin as the SPA, no CORS).
+
+ARG ATRIUM_IMAGE=ghcr.io/brendanbank/atrium:__ATRIUM_VERSION__
+
+# ---- frontend-builder ----
+FROM node:25-alpine AS frontend-builder
+WORKDIR /app
+RUN npm install -g pnpm@10.33.1
+
+COPY frontend/package.json frontend/pnpm-lock.yaml* frontend/.npmrc ./
+RUN pnpm install --frozen-lockfile 2>/dev/null || pnpm install
+COPY frontend/ ./
+
+ARG VITE_API_BASE_URL=""
+ENV VITE_API_BASE_URL=${VITE_API_BASE_URL}
+RUN pnpm build
+
+# ---- runtime ----
+FROM ${ATRIUM_IMAGE} AS runtime
+
+USER root
+COPY backend /opt/host_app
+# atrium's runtime image uses uv to build the venv but doesn't install
+# pip into it. ensurepip bootstraps pip so we can install the host
+# package — slightly slower than uv but avoids adding uv to the
+# runtime image just for this one install.
+RUN /opt/venv/bin/python -m ensurepip --upgrade \
+ && /opt/venv/bin/python -m pip install --no-cache-dir /opt/host_app
+
+# Bake the host bundle into atrium's static dir at /host/main.js.
+COPY --from=frontend-builder /app/dist /opt/atrium/static/host
+
+USER app
+
+# Re-declare HEALTHCHECK on the derived image. The base atrium image
+# already ships one (curl /healthz on :8000), but image scanners flag
+# absence at the leaf Dockerfile because they don't trace inheritance.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
+    CMD curl -fsS http://localhost:8000/healthz || exit 1

package/template/Makefile

@@ -0,0 +1,67 @@
+# __BRAND_NAME__ — top-level Make targets.
+#
+# Convenience wrappers around the docker-compose stack. Most of these
+# assume you ran `make dev-bootstrap` first to bring everything up.
+
+COMPOSE := docker compose
+
+.PHONY: help dev-bootstrap up down build logs ps migrate \
+	seed-admin seed-bundle test test-frontend test-backend typecheck
+
+help:  ## show this help
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-18s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+dev-bootstrap: build up migrate  ## build, start, migrate; run me first
+	@echo
+	@echo "Stack is up. Next: make seed-admin EMAIL=you@example.com PASSWORD=..."
+	@echo "Then: make seed-bundle && open http://localhost:8000"
+
+up:  ## start the stack
+	$(COMPOSE) up -d
+
+down:  ## stop the stack (keeps data volume)
+	$(COMPOSE) down
+
+build:  ## (re)build the image
+	$(COMPOSE) build
+
+logs:  ## tail logs from all services
+	$(COMPOSE) logs -f
+
+ps:  ## list services
+	$(COMPOSE) ps
+
+migrate:  ## run atrium + host alembic chains
+	$(COMPOSE) exec -T api alembic upgrade head
+	$(COMPOSE) exec -T api alembic -c /opt/host_app/alembic.ini upgrade head
+
+seed-admin:  ## seed a super_admin (EMAIL=... PASSWORD=... [FULL_NAME=...])
+	@if [ -z "$(EMAIL)" ] || [ -z "$(PASSWORD)" ]; then \
+		echo "usage: make seed-admin EMAIL=you@example.com PASSWORD=secret [FULL_NAME='Your Name']"; \
+		exit 2; \
+	fi
+	$(COMPOSE) exec -T api python -m app.scripts.seed_admin \
+		--email "$(EMAIL)" --password "$(PASSWORD)" \
+		--full-name "$${FULL_NAME:-Admin}" --super-admin
+
+seed-bundle:  ## point system.host_bundle_url at /host/main.js
+	$(COMPOSE) exec -T api python -m __HOST_PKG__.scripts.seed_host_bundle /host/main.js
+
+# Tests. The atrium runtime image strips pytest/pytest-asyncio/httpx
+# to keep the prod image small; install on demand. The pip install is
+# idempotent (no-op if the deps are already there) but it does cost
+# one round-trip per invocation — bake a `dev` Dockerfile stage if
+# you'll be running tests often.
+test: test-frontend test-backend  ## run host tests (frontend + backend)
+
+test-frontend:  ## frontend unit tests via vitest
+	cd frontend && pnpm install --frozen-lockfile 2>/dev/null || (cd frontend && pnpm install)
+	cd frontend && pnpm test
+
+test-backend:  ## backend smoke tests inside the api container
+	$(COMPOSE) exec -u root -T api /opt/venv/bin/python -m pip install \
+		--quiet --no-cache-dir pytest pytest-asyncio httpx
+	$(COMPOSE) exec -T api /opt/venv/bin/python -m pytest /opt/host_app/tests
+
+typecheck:  ## tsc --noEmit on the host bundle
+	cd frontend && pnpm typecheck

package/template/README.md

@@ -0,0 +1,124 @@
+# __BRAND_NAME__
+
+A host extension on top of [atrium](https://github.com/brendanbank/atrium).
+Atrium ships the platform layer (auth, RBAC, audit, email, jobs,
+notifications, admin shell); this repo adds the domain-specific routes,
+models, and UI.
+
+## Quick start
+
+```bash
+cp .env.example .env
+# Edit .env: set APP_SECRET_KEY, JWT_SECRET (openssl rand -hex 48 each),
+# MYSQL_PASSWORD, MYSQL_ROOT_PASSWORD.
+
+make dev-bootstrap
+make seed-admin EMAIL=you@example.com PASSWORD='a-good-password'
+make seed-bundle
+open http://localhost:8000
+```
+
+Sign in with the seeded admin and the **__BRAND_NAME__** card appears on
+the home page, with a sidebar link to `/__HOST_NAME__`, an admin tab,
+and a profile-page card. Bump the counter to exercise the RBAC + audit
+path end to end.
+
+## Layout
+
+```
+__HOST_NAME__/
+  Dockerfile           # frontend-builder + FROM atrium runtime
+  compose.yaml         # api + worker + mysql
+  .env.example         # secrets template (copy to .env)
+  Makefile             # dev-bootstrap / migrate / seed-* / test
+  backend/             # host Python package (__HOST_PKG__)
+    pyproject.toml
+    alembic.ini
+    alembic/           # alembic_version_app chain (separate from atrium)
+    src/__HOST_PKG__/
+      bootstrap.py     # init_app(app), init_worker(host)
+      models.py        # HostBase + your tables
+      router.py        # FastAPI routes
+      scripts/seed_host_bundle.py
+    tests/             # pytest smoke tests
+  frontend/            # Vite library project (single main.js)
+    package.json
+    vite.config.ts     # uses @brendanbank/atrium-host-bundle-utils/vite
+    src/
+      main.tsx         # registry calls — ~10 lines
+      api.ts
+      queryClient.ts
+      __BRAND_PASCAL__Widget.tsx     # home widget + admin tab + page demo
+      __BRAND_PASCAL__Page.tsx
+      __BRAND_PASCAL__AdminTab.tsx
+      __BRAND_PASCAL__ProfileItem.tsx
+    src/test/          # vitest setup + worked example using @brendanbank/atrium-test-utils
+  .github/workflows/   # CI (typecheck + tests + smoke)
+```
+
+## What atrium gives you (don't reimplement)
+
+- Auth (password / TOTP / email OTP / WebAuthn) with role-mandatory 2FA
+- RBAC: roles + permissions + super_admin + impersonation
+- Account lifecycle: invite-only or self-serve signup, soft-delete + grace + hard-delete
+- Audit log + retention pruning
+- Email pipeline: templates per locale, durable outbox, retry/backoff
+- In-app notifications + SSE bell
+- Admin app-config (branding, system flags, translations, auth toggles)
+- Maintenance mode (super_admin bypass)
+
+If you find yourself writing one of these, stop — atrium has it. See
+the atrium repo's `CLAUDE.md` for the contract.
+
+## What lives in this repo
+
+- Your domain models (on `HostBase`, never `app.db.Base`)
+- Your routes (gated by `current_user` or `require_perm("...")`)
+- Your migrations (on the `alembic_version_app` chain)
+- Your frontend pages / widgets / admin tabs
+- Your background jobs (`host.scheduler.add_job` for ticks,
+  `host.register_job_handler` for durable queue work)
+
+## Adding things
+
+| You want to add               | Where it lives                                       | Wire it via                                                                |
+|-------------------------------|------------------------------------------------------|----------------------------------------------------------------------------|
+| HTTP endpoint                 | `__HOST_PKG__/router.py`                             | `app.include_router(router)` in `init_app`                                 |
+| New permission                | A new alembic migration                              | `seed_permissions_sync(op.get_bind(), [...], grants={...})`                |
+| Recurring tick                | `__HOST_PKG__/schedule.py` async function            | `host.scheduler.add_job(fn, "interval", seconds=N, ...)` in `init_worker`  |
+| Durable async job             | A handler `(session, job, payload) -> None`          | `host.register_job_handler(kind="...", handler=..., description="...")`    |
+| Admin-tunable flag            | A Pydantic `BaseModel` config class                  | `register_namespace("ns", Model, public=False)` in `init_app`              |
+| Per-user notification         | Inside the txn that mutated the row                  | `from app.services.notifications import notify_user`                       |
+| Outbound email (queued)       | A template row in `email_templates` + a callsite     | `from app.email.sender import enqueue_and_log`                             |
+| Audit row                     | Inside the txn that mutated the row                  | `from app.services.audit import record`                                    |
+| Home widget                   | A React component in `frontend/src/`                 | `reg.registerHomeWidget({ key, render })`                                  |
+| Dedicated route               | A page component                                     | `reg.registerRoute({ key, path, element, layout? })`                       |
+| Sidebar link                  | A label + path                                       | `reg.registerNavItem({ key, label, to, icon? })`                           |
+| Admin tab                     | A component, gated by a permission                   | `reg.registerAdminTab({ key, label, icon?, perm, element })`               |
+| Profile-page card             | A component                                          | `reg.registerProfileItem({ key, slot?, render, condition? })`              |
+
+For the full backend extension surface see
+[atrium's `docs/new-project/README.md`](https://github.com/brendanbank/atrium/blob/master/docs/new-project/README.md).
+
+## Tests
+
+```bash
+make test            # frontend unit tests + backend smoke tests
+make typecheck       # tsc --noEmit on the host bundle
+```
+
+## Pinning atrium
+
+`compose.yaml` reads `ATRIUM_IMAGE` from `.env` (default
+`ghcr.io/brendanbank/atrium:__ATRIUM_VERSION__`). Override to test
+against a specific release:
+
+```bash
+ATRIUM_IMAGE=ghcr.io/brendanbank/atrium:0.15.0 make build up
+```
+
+The frontend SDK packages
+(`@brendanbank/atrium-host-types`, `@brendanbank/atrium-host-bundle-utils`,
+`@brendanbank/atrium-test-utils`) version in lockstep with the image
+— a pin of `^__ATRIUM_VERSION__` matches any patch of the
+`__ATRIUM_VERSION__.x` line.

package/template/backend/alembic/env.py

@@ -0,0 +1,116 @@
+"""Host-side alembic environment.
+
+Three things differ from atrium's ``backend/alembic/env.py``:
+
+1. ``target_metadata`` points at the host's ``HostBase.metadata`` so
+   autogenerate only sees host tables. Atrium's tables are managed by
+   atrium's own chain — never touch them from here.
+2. ``version_table`` is set to ``alembic_version_app`` so the two
+   chains track their heads independently. They share the database
+   but never collide on a revision.
+3. ``process_revision_directives`` is wired to
+   ``emit_host_foreign_keys`` so columns declared with
+   ``HostForeignKey()`` get their cross-base ``ForeignKeyConstraint``
+   emitted into autogenerated migrations.
+"""
+from __future__ import annotations
+
+import asyncio
+from logging.config import fileConfig
+
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+from app.host_sdk.alembic import emit_host_foreign_keys
+from app.settings import get_settings
+
+# ``HostBase`` is the metadata target; importing it from
+# ``__HOST_PKG__.models`` also runs the package's ``__init__``, which
+# registers every model class on ``HostBase.metadata`` before
+# autogenerate inspects it.
+from __HOST_PKG__.models import HostBase
+
+VERSION_TABLE = "alembic_version_app"
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+if not config.get_main_option("sqlalchemy.url") or config.get_main_option(
+    "sqlalchemy.url"
+).startswith("driver://"):
+    config.set_main_option("sqlalchemy.url", get_settings().database_url)
+
+target_metadata = HostBase.metadata
+
+
+def _include_object(obj, name, type_, reflected, compare_to):
+    """Filter atrium tables out of autogenerate.
+
+    Both atrium and the host write to the same MySQL database. With
+    ``target_metadata = HostBase.metadata`` alembic sees atrium's
+    tables as "in the DB but not in the model" and would emit
+    ``drop_table`` ops for every one of them on the first
+    autogenerate. Only emit ops for tables (and child objects) that
+    live in ``HostBase.metadata``.
+    """
+    if type_ == "table":
+        return name in target_metadata.tables
+    if reflected:
+        parent = getattr(obj, "table", None)
+        if parent is not None and parent.name not in target_metadata.tables:
+            return False
+    return True
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        version_table=VERSION_TABLE,
+        include_object=_include_object,
+        process_revision_directives=emit_host_foreign_keys,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        version_table=VERSION_TABLE,
+        compare_type=True,
+        render_as_batch=False,
+        include_object=_include_object,
+        process_revision_directives=emit_host_foreign_keys,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

package/template/backend/alembic/script.py.mako

@@ -0,0 +1,27 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

package/template/backend/alembic/versions/0001_init.py

@@ -0,0 +1,92 @@
+"""__HOST_PKG__ initial schema + brand seed
+
+Revision ID: 0001_init
+Revises:
+Create Date: 2026-04-28
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from app.auth.rbac_seed import seed_permissions_sync
+from sqlalchemy.dialects.mysql import DATETIME as MysqlDATETIME
+
+revision: str = "0001_init"
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # Demo singleton table — delete this and `__HOST_PKG__/models.py`
+    # once you've added your real domain models. The router and the
+    # frontend widget reference it; remove those callsites at the
+    # same time.
+    op.create_table(
+        "__HOST_PKG___state",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=False),
+        sa.Column(
+            "message",
+            sa.String(length=255),
+            nullable=False,
+            server_default=sa.text("'Welcome to __BRAND_NAME__'"),
+        ),
+        sa.Column(
+            "counter",
+            sa.BigInteger(),
+            nullable=False,
+            server_default=sa.text("0"),
+        ),
+        sa.Column(
+            "updated_at",
+            MysqlDATETIME(fsp=6),
+            nullable=False,
+            server_default=sa.text("CURRENT_TIMESTAMP(6)"),
+            server_onupdate=sa.text("CURRENT_TIMESTAMP(6)"),
+        ),
+    )
+
+    # Singleton row so the demo route doesn't have to lazy-create.
+    op.execute(
+        "INSERT INTO __HOST_PKG___state (id, message, counter) "
+        "VALUES (1, 'Welcome to __BRAND_NAME__', 0)"
+    )
+
+    # Permissions belong with the schema. The runtime form
+    # (`seed_permissions`) exists for hosts that discover permissions
+    # at startup; for static codes, the migration form is the natural
+    # fit. Atrium auto-grants every seeded permission to super_admin;
+    # `grants` adds extra role bindings.
+    seed_permissions_sync(
+        op.get_bind(),
+        ["__HOST_PKG__.read", "__HOST_PKG__.write"],
+        grants={"admin": ["__HOST_PKG__.write"]},
+    )
+
+    # Materialise an initial BrandConfig so the SPA renders with the
+    # host's name + primary colour from the first page load. Atrium
+    # exposes this via /app-config and re-reads it within the 2 s
+    # cache TTL when the admin tweaks branding live.
+    brand = json.dumps(
+        {
+            "name": "__BRAND_NAME__",
+            "preset": "default",
+            "overrides": {"primaryColor": "__BRAND_PRIMARY__"},
+        }
+    )
+    op.execute(
+        sa.text(
+            "INSERT INTO app_settings (`key`, value) VALUES ('brand', :v) "
+            "ON DUPLICATE KEY UPDATE value = :v"
+        ).bindparams(v=brand)
+    )
+
+
+def downgrade() -> None:
+    # Permissions intentionally left in place — they're cheap to keep
+    # and removing them would orphan any UI that still references the
+    # code. Brand seed left alone for the same reason.
+    op.drop_table("__HOST_PKG___state")