ms-qg 0.12.1__tar.gz

ms_qg-0.12.1/.claude/skills/qg-config-authoring/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: qg-config-authoring
+description: Use when adding to or editing the qg queue-generation configuration under qg_configs/ — standing up a new technology, adding an instrument, adding a plate layout with its QC samples and a queue pattern, or adding/adjusting an output format. Triggers when the user mentions qg_configs, instruments.csv, queue_patterns.toml, plate_layouts.toml, qc_layouts, samples.csv, output_formats.toml, adding an instrument / technology / QC sample / plate layout, or keeping the config files consistent. Explains which files each change touches and the cross-file rules qg_configuration() enforces at load.
+---
+
+# Authoring qg configuration
+
+`qg` is configuration-driven: technologies, instruments, samplers, plate layouts,
+QC samples, patterns, and output formats are all rows in CSVs or tables in TOML
+files under `qg_configs/`. Adding any of them is a config edit, not a code change.
+This skill is the playbook for the recurring edits and — crucially — the cross-file
+dependencies between them.
+
+## How to make a change (and the one rule that matters)
+
+The config files are **not** cross-validated incrementally as you edit them. They
+are validated as a set, at load, by `qg_configuration()`
+(`src/qg/config_models/loader.py:664`), which reads all twelve config files and then
+runs the cross-reference validators (`loader.py:122-261`). A mismatch surfaces there
+as a `ConfigValidationError` — **except** `ui/instrument_config.csv`, which is not
+cross-validated and instead fails later as a runtime lookup in the app. So:
+
+1. Make the edits across **all** the files a change touches (the stories below list them).
+2. Run `uv run qg-validate` (add `-c <dir>` for a non-default config dir). This loads
+   and cross-validates everything; a clean exit means the set is consistent.
+3. Keep `ui/instrument_config.csv` in sync by hand — `qg-validate` will not catch a
+   missing or mismatched row there.
+
+**The consistency rule — the QC-sample → reserved-position cascade.** Every QC sample
+id a queue pattern references (in its `start` / `middle` / `end` / `separation` /
+`middle_extended` lists) must:
+
+- exist in `core/structure/samples.csv` for the **same** `tech_area`, and
+- have a **reserved position** in a QC layout
+  (`core/position/qc_layouts_well.csv` for well samplers, `qc_layouts_tip.csv` for tip
+  samplers) for the `(tech_area, qc_layout_name, plate_layout)` the queue uses.
+
+This is why "add a QC sample to a pattern" is never a one-file edit: it cascades into
+the QC layout, and a new layout into the plate-layout and sampler-mapping files. The
+validators that enforce it are `_validate_pattern_sample_refs`,
+`_validate_layout_sample_refs`, and `_validate_pattern_layout_compatibility`
+(`loader.py:122-261`).
+
+For the full field-by-field schema of each file, see
+[docs/reference/config.md](../../../docs/reference/config.md). For the instrument-row
+specifics, see "Adding a New Instrument" in [AGENTS.md](../../../AGENTS.md).
+
+---
+
+## Story 1 — Stand up a new technology end-to-end
+
+This is the spine: every other story is a slice of it. The worked example below is a
+complete, minimal technology `Testing_v3` (one instrument, the reused Vanquish well
+sampler, the reused `xcalibur` output format, a new 12-well plate layout, three sample
+types, one QC pattern). It is exactly what `tests/test_config_authoring.py` builds and
+asserts is loadable, valid, and usable — copy it and adapt.
+
+Author the files in this order (technology → plate layout → pattern):
+
+**1. Declare the technology** — `qg_configs/ui/tech_area_defaults.toml`:
+
+```toml
+[Testing_v3]
+default_user = ""
+default_polarities = ["pos"]
+bfabric_areas = []
+```
+
+**2. Define the sample types** — append to `qg_configs/core/structure/samples.csv`
+(header: `tech_area,sample_id,sample_name,sample_type,level,description,inj_vol,file_name_template`):
+
+```csv
+Testing_v3,default,"",Unknown,,Default Testing_v3 user sample,2.0,{date}_{run}_C{container}_S{sample_id}_{sample_name}
+Testing_v3,QCv3,QCv3,QC,,Testing_v3 QC sample,2.0,{date}_{run}_C{container}_{sample_name}
+Testing_v3,cleanv3,cleanv3,Blank,,Testing_v3 column cleanup blank,2.0,{date}_{run}_C{container}_{sample_name}
+```
+
+Every technology needs a `default` row (the user-sample template). QC and blank rows
+are the injections a pattern can reference.
+
+**3. Add the instrument + its methods file.** Append to
+`qg_configs/core/formatting/instruments.csv`
+(header: `tech_area,instrument,methods_file,path_template`):
+
+```csv
+Testing_v3,TESTING_V3_1,methods/Testing_v3/TESTING_V3_1_methods.csv,D:\Data2San\p{container}\Testing_v3\TESTING_V3_1\{user}_{date}
+```
+
+Create the file the `methods_file` column points at,
+`qg_configs/core/methods/Testing_v3/TESTING_V3_1_methods.csv`
+(header: `sample_type,polarity,method_name,method_path`):
+
+```csv
+default,pos,DDA,C:\Xcalibur\methods\
+QCv3,pos,DDA,C:\Xcalibur\methods\__autoQC\QCv3
+```
+
+A single-polarity technology (`pos` only) needs just `pos` rows; metabolomics /
+lipidomics need both `pos` and `neg` because of polarity expansion. The `default` row
+covers user samples; add a per-QC row for any QC sample placed in the queue.
+
+**4. Add the plate layout + sampler mapping.** Append to
+`qg_configs/core/position/plate_layouts.toml`:
+
+```toml
+[TestingV3_12]
+rows = ["A", "B"]
+cols = [1, 2, 3, 4, 5, 6]
+```
+
+Map it to a sampler + queue type in
+`qg_configs/core/position/sampler_plate_layouts.csv`
+(header: `sampler,plate_layout,queue_type`):
+
+```csv
+Vanquish,TestingV3_12,Vial
+```
+
+(Reusing the existing `Vanquish` sampler — no `sampler.toml` edit needed. Adding a new
+sampler is a separate, larger change.)
+
+**5. Reserve QC positions** for the layout — append to
+`qg_configs/core/position/qc_layouts_well.csv`
+(header: `tech_area,qc_layout_name,plate_layout,sample_id,tray,row,col`):
+
+```csv
+Testing_v3,v3std,TestingV3_12,QCv3,B,B,6
+```
+
+`row` must be one of the layout's `rows` and `col` one of its `cols`. This is the
+reserved-position half of the cascade rule.
+
+**6. Create the pattern** that uses those QC samples — append to
+`qg_configs/core/structure/queue_patterns.toml`:
+
+```toml
+[Testing_v3.simple]
+description = "Testing_v3 simple pattern: QC at start and end"
+run_QC_after_n_samples = 4
+start = ["QCv3"]
+middle = []
+end = ["QCv3"]
+```
+
+Reference **only** sample ids defined for `Testing_v3` in `samples.csv`, and make sure
+each appears in the QC layout from step 5.
+
+**7. Expose it in the UI** — append to `qg_configs/ui/instrument_config.csv`
+(header: `tech_area,instrument,sampler,output_format,default_pattern`):
+
+```csv
+Testing_v3,TESTING_V3_1,Vanquish,xcalibur,simple
+```
+
+`sampler`, `output_format`, and `default_pattern` must all exist (in `sampler.toml`,
+`output_formats.toml`, and `queue_patterns.toml` respectively). This file is **not**
+cross-validated at load — double-check it manually.
+
+Then validate: `uv run qg-validate`. A clean exit means the technology is consistent
+and queue generation will resolve it.
+
+---
+
+## Story 2 — Add an instrument to an existing technology
+
+Three files, and they must agree (this is step 3 of Story 1, plus the UI row):
+
+- `qg_configs/core/formatting/instruments.csv` — a row whose `methods_file` points at…
+- `qg_configs/core/methods/<Technology>/<Instrument>_methods.csv` — the methods file you create.
+- `qg_configs/ui/instrument_config.csv` — one row per (instrument, sampler) pairing so
+  the instrument appears in the app menu.
+
+The `instruments.csv` `methods_file` path and the actual file must match exactly;
+`MethodsConfig.load()` discovers methods files from these rows. See "Adding a New
+Instrument" in [AGENTS.md](../../../AGENTS.md) for the full checklist.
+
+---
+
+## Story 3 — Add a plate layout, its QC samples, and a pattern
+
+This is the cascade in concrete form. Touches:
+
+- `qg_configs/core/position/plate_layouts.toml` — the geometry (`rows`, `cols`).
+- `qg_configs/core/position/sampler_plate_layouts.csv` — map the layout to a sampler + `queue_type`.
+- `qg_configs/core/structure/samples.csv` — any **new** QC / blank sample types.
+- `qg_configs/core/position/qc_layouts_well.csv` (well samplers) **or** `qc_layouts_tip.csv`
+  (tip samplers, e.g. Evosep) — a reserved position for **every** QC sample the pattern
+  will reference, for this `(tech_area, qc_layout_name, plate_layout)`.
+- `qg_configs/core/structure/queue_patterns.toml` — the pattern, referencing only those
+  QC sample ids.
+
+If you add a QC sample to a pattern but forget its reserved position,
+`_validate_pattern_layout_compatibility` fails at load with a message naming the
+required sample ids. Add the position; don't remove the reference.
+
+---
+
+## Story 4 — Add or adjust an output format
+
+One file: `qg_configs/core/formatting/output_formats.toml`. Each format is a base table
+plus a `columns` sub-table mapping output column name → internal field:
+
+```toml
+[xcalibur]
+description = "Thermo XCalibur format"
+file_extension = ".csv"
+writer = "xcalibur_csv"
+position_format = "{tray}:{grid_position}"
+grid_position_format = "{row},{col}"
+grid_position_conversion = "identity"
+
+[xcalibur.columns]
+"File Name" = "file_name"
+Path = "data_path"
+Position = "position"
+"Inj Vol" = "inj_vol"
+"Sample ID" = "sample_id"
+"Sample Name" = "sample_name"
+"Instrument Method" = "method"
+```
+
+`writer` must be a known writer (`xcalibur_csv`, `chronos_csv`, `hystar_xml`). To add a
+column for **one technology only**, use a per-tech overlay sub-table — it merges over
+the base `columns`:
+
+```toml
+# Metabolomics-only extra columns, inherited base columns otherwise
+[xcalibur_sii.columns.Metabolomics]
+"Sample Type" = "sample_type"
+"Level" = "level"
+```
+
+A literal value uses the `literal:` prefix (e.g. `"L3 Laboratory" = "literal:FGCZ"`).
+
+---
+
+## Verify your change
+
+```bash
+uv run qg-validate                 # loads + cross-validates the committed config
+uv run qg-validate -c <config_dir> # …or a custom config directory
+```
+
+Then generate a sample queue to confirm it is usable end-to-end — either through the
+app, or programmatically as `tests/test_config_authoring.py` does
+(`qg_configuration(<dir>)` → `QueueGenerator(cfg, queue_input).generate()`), or via the
+CLI: `uv run qg <input.json> -o <out.csv> -c <config_dir>`.
+
+If you add a real (committed) technology or instrument, also follow the Release Process
+in [AGENTS.md](../../../AGENTS.md): a `CHANGELOG.md` bullet and a version bump.

ms_qg-0.12.1/.dockerignore

@@ -0,0 +1,26 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Config file
+.env
+
+# Virtual environments
+.venv
+__marimo__/
+.claude/
+queue_files/
+*.pdf
+*.svg
+.snakemake/
+*.html
+*_files/
+*.png
+plans/
+
+# actual data
+bfabric_cache

ms_qg-0.12.1/.env.example

@@ -0,0 +1,6 @@
+VALIDATION_BFABRIC_INSTANCE=https://fgcz-bfabric.uzh.ch/bfabric/
+SUPPORTED_BFABRIC_INSTANCES=["https://fgcz-bfabric.uzh.ch/bfabric/","https://fgcz-bfabric-test.uzh.ch/bfabric/"]
+# It's recommended to define a relatively long and safely random secret key
+#SECRET_KEY=
+_FEEDER_PWD="TODO"
+FEEDER_USER_CREDENTIALS={"https://fgcz-bfabric.uzh.ch/bfabric/":{"login":"pfeeder","password":"${_FEEDER_PWD}"},"https://fgcz-bfabric-test.uzh.ch/bfabric/":{"login":"pfeeder","password":"${_FEEDER_PWD}"}}

ms_qg-0.12.1/.github/workflows/ci.yml

@@ -0,0 +1,237 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  # Callable so publish.yml can run this whole suite as a release gate before
+  # building the image (restores GitLab's test -> build stage ordering).
+  workflow_call:
+    inputs:
+      # publish.yml passes a unique value here so the release-gate run gets its
+      # own concurrency group and can't be cancelled by a concurrent push to main
+      # (a tag release is already safe — its ref makes the group unique).
+      concurrency-group:
+        type: string
+        required: false
+        default: ""
+
+permissions:
+  contents: read
+
+# Mirror GitLab's workflow.auto_cancel.on_new_commit: interruptible — a new push
+# to the same ref cancels the in-flight run. When called as a release gate the
+# caller supplies a unique group (above), so the gate itself is never cancelled.
+concurrency:
+  group: ${{ inputs.concurrency-group || format('ci-{0}', github.ref) }}
+  cancel-in-progress: true
+
+jobs:
+  # Fast feedback: every non-browser test. No playwright, no apt — fails fast.
+  unit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install
+      - name: Sync (dev + portal)
+        run: uv sync --frozen
+      - name: Run unit tests
+        run: >-
+          uv run --no-sync pytest
+          --ignore=tests/gui
+          --ignore=tests/gui_local
+          --cov=qg
+          --cov-branch
+          --cov-report=xml:coverage.xml
+          --cov-report=term-missing:skip-covered
+      - name: Check changed-line coverage
+        if: github.event_name == 'pull_request'
+        run: >-
+          uv run --no-sync diff-cover coverage.xml
+          --compare-branch="origin/${{ github.base_ref }}"
+          --fail-under=60
+
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install
+      - name: Sync (dev + portal)
+        run: uv sync --frozen
+      - name: Ruff lint
+        run: uv run --no-sync ruff check . --output-format=github
+      - name: Ruff format
+        run: uv run --no-sync ruff format --check .
+      - name: Dependency declarations
+        run: uv run --no-sync deptry .
+
+  package-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install
+      - name: Sync core development environment
+        run: uv sync --frozen --no-group portal
+      - name: Build and inspect distributions
+        run: uv run --no-sync python scripts/package_smoke.py
+
+  # Floor gate: `pip install qg` on the oldest supported interpreter must import,
+  # expose its CLIs, resolve its bundled configs, and pass the non-browser suite.
+  # Installs the built wheel with pip (not uv sync) so this mirrors what a reader
+  # of the README actually runs, and guards the requires-python floor from drifting
+  # up to the development interpreter unnoticed.
+  install-floor:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          cache-suffix: floor
+      - name: Build wheel
+        run: uv build --wheel --out-dir dist
+      - name: Install the wheel on the floor interpreter
+        run: |
+          uv venv --python 3.13 --seed .venv-floor
+          .venv-floor/bin/pip install dist/ms_qg-*.whl pytest pytest-mock pytest-bdd xlsxwriter
+      - name: Import, CLI and bundled-config checks
+        run: |
+          .venv-floor/bin/python -c "import qg"
+          .venv-floor/bin/qg --help > /dev/null
+          .venv-floor/bin/python -c "from qg.config_models.loader import _DEFAULT_CONFIG_DIR as d; assert d.is_dir(), d"
+      - name: Run the non-browser suite against the installed wheel
+        run: >-
+          .venv-floor/bin/python -m pytest
+          --ignore=tests/gui
+          --ignore=tests/gui_local
+          -m "not bfabric and not bfabric_test_instance and not local_gui"
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          cache-suffix: docs
+      - name: Install Python
+        run: uv python install
+      - name: Sync docs environment
+        run: uv sync --frozen --only-group docs
+      - name: Build documentation (strict)
+        run: uv run --no-sync mkdocs build --strict
+
+  # Keep the checked-in Python sources aligned with the repository's Pyright
+  # configuration. This mirrors the local pre-commit hook.
+  pyright:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install
+      - name: Sync (dev + portal)
+        run: uv sync --frozen
+      - name: Run Pyright
+        run: uv run --no-sync python -m pyright
+
+  # Core-install gate: prove `qg` installs, imports, and its non-B-Fabric tests
+  # pass WITHOUT the portal extra (no bfabric/fastapi/starlette/python-gitlab).
+  # Syncs only the `dev` group, omitting the `portal` default-group; asserts
+  # bfabric is absent, then runs the B-Fabric-free suite. Guards the publication
+  # path (a plain `pip install qg` stays B-Fabric-free).
+  core-no-bfabric:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+          # Own cache namespace: this job installs a portal-less subset, so it
+          # must not share the uv.lock-keyed cache with the full-install jobs
+          # (otherwise whichever saves first freezes the wrong dependency set).
+          cache-suffix: core
+      - name: Install Python
+        run: uv python install
+      - name: Sync core only (no portal group)
+        run: uv sync --frozen --no-group portal
+      - name: Run core profile checks
+        run: uv run --no-sync --no-group portal python scripts/core_profile_check.py
+
+  # Browser suite: tests/gui (portal app) + tests/gui_local (standalone app),
+  # driven in headless Chromium via pytest-playwright. Runs on Microsoft's
+  # official Playwright image, which ships the browsers AND their ~67 apt system
+  # libs pre-baked — so this job needs no `playwright install` and no apt step.
+  # The image tag MUST track the `playwright` pin in uv.lock (currently 1.62.0);
+  # a mismatch surfaces as a clear "browser not found / version" error.
+  # Do NOT set PLAYWRIGHT_BROWSERS_PATH here, or the baked browsers hide.
+  gui:
+    runs-on: ubuntu-latest
+    container: mcr.microsoft.com/playwright:v1.62.0-noble
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      # setup-uv supports container jobs; if it ever fails to fetch/cache uv
+      # inside this image, the known-good fallback (used by the old GitLab job)
+      # is the static installer:
+      #   run: curl -LsSf https://astral.sh/uv/install.sh | sh && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install
+      - name: Sync (dev + portal)
+        run: uv sync --frozen
+      - name: Run GUI tests
+        run: uv run --no-sync pytest tests/gui tests/gui_local
+
+  # Static lint of the marimo apps. --strict makes warnings (e.g. the
+  # branch-expression rule, where a bare mo.md(...) inside if/elif/else is
+  # computed then discarded so the output never renders) fail the pipeline.
+  marimo-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install
+      - name: Sync (dev + portal)
+        run: uv sync --frozen
+      - name: marimo check (strict)
+        run: uv run --no-sync marimo check --strict src/qg/apps/queue_app.py src/qg/apps/queue_app_local.py src/qg/apps/config_editor.py

ms_qg-0.12.1/.github/workflows/pages.yml

@@ -0,0 +1,57 @@
+name: pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install
+
+      # Docs-only: mkdocs-material lives in the `docs` group and the site needs
+      # no plugins that import the package, so we install just that group.
+      - name: Install docs dependencies
+        run: uv sync --frozen --only-group docs
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v6
+
+      - name: Build docs
+        run: uv run --no-sync mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: public
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

ms_qg-0.12.1/.github/workflows/publish.yml

@@ -0,0 +1,101 @@
+name: publish
+
+# CD for the GitHub remote: build the container image and push it to the GitHub
+# Container Registry (ghcr.io/<owner>/<repo>). GitLab separately retains the
+# production arm64 OCI-to-NFS path. Tagging a release (vX.Y.Z) publishes this
+# multi-platform image; workflow_dispatch supports an explicit GitHub build.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  IMAGE: ghcr.io/${{ github.repository }}
+
+jobs:
+  # Release gate: run the full CI suite against the tagged commit first. Mirrors
+  # GitLab's stages: [test, build] ordering — a red test stage blocks the build.
+  test:
+    uses: ./.github/workflows/ci.yml
+    with:
+      # Unique group so this gate run isn't cancelled by a concurrent push to main.
+      concurrency-group: release-gate-${{ github.run_id }}
+
+  build-push:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      # arm64 emulation so a single amd64 runner can build the arm64 leg.
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to ghcr.io
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Derive image tags and labels
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.IMAGE }}
+          # tag push -> the version tag (vX.Y.Z); manual dispatch -> the branch
+          # name (e.g. main), so manual builds get a readable tag, not sha-only.
+          tags: |
+            type=ref,event=tag
+            type=ref,event=branch
+            type=sha
+
+      # Builds the existing Dockerfile (uv base, portal extra by default, uvicorn
+      # entrypoint on :8000) for both platforms. The arm64 image is what the
+      # deploy host runs; amd64 lets the image run on amd64 dev machines too.
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  # Publishes the sdist and wheel to PyPI on a version tag, gated by the same CI
+  # suite. Uses PyPI Trusted Publishing (OIDC), so no API token is stored here;
+  # the PyPI project must list this repository and the `pypi` environment as a
+  # trusted publisher. Skipped on workflow_dispatch, where the version is usually
+  # already published and PyPI rejects a re-upload.
+  publish-pypi:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+      - name: Build sdist and wheel
+        run: uv build --out-dir dist
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always