chore(release): v1.0.2

Cut by rmancinas via the "Cut release" workflow. Pushing the tag triggers build.yml; deploy separately with tag=1.0.2.

.env.example

@@ -3,3 +3,33 @@ DATABASE_URL=mysql://jorgecuadros:jorgecuadros@localhost:3306/jorgecuadros
 SESSION_SECRET=change-me-to-a-random-string
 WEB_ORIGIN=http://localhost:3000
 NEXT_PUBLIC_API_ORIGIN=http://localhost:3001
+
+# Object storage (MinIO / S3) for document blobs and scanned receipt pages.
+# Without S3_ENDPOINT + credentials the API still boots, but every document
+# upload/download and the whole recibo OCR intake are disabled. Credentials fall
+# back to MINIO_ROOT_USER / MINIO_ROOT_PASSWORD when the S3_* pair is unset.
+S3_ENDPOINT=http://localhost:9000
+S3_BUCKET=jorgecuadros-documents
+S3_ACCESS_KEY=
+S3_SECRET_KEY=
+
+# Login the "Operaciones" screen runs mysqldump/mysql as. Optional locally: when
+# unset it falls back to the DATABASE_URL credentials, which a dev MySQL usually
+# grants enough for. Required in any deployment, where the application user has
+# only ALL ON jorgecuadros.* and mysqldump --single-transaction needs the global
+# RELOAD privilege. Host/port/database always come from DATABASE_URL.
+OPS_DB_ADMIN_USER=
+OPS_DB_ADMIN_PASSWORD=
+
+# Company info — printed in the header of every report (PDF + browser
+# print). Leave blank to use the placeholders. COMPANY_LOGO_PATH is
+# optional; when unset the API falls back to apps/api/assets/company_logo.png.
+COMPANY_NAME=Jorge Cuadros & Asociados
+COMPANY_ADDRESS_LINE1=
+COMPANY_ADDRESS_LINE2=
+COMPANY_CITY_STATE=
+COMPANY_PHONE=
+COMPANY_EMAIL=
+COMPANY_TAX_ID=
+COMPANY_WEBSITE=
+COMPANY_LOGO_PATH=

.gitea/workflows/deploy-galactus.yml

@@ -0,0 +1,319 @@
+# Manual PROD deploy to galactus — the office server, Portainer endpoint 3.
+#
+# galactus is STANDALONE Docker (`swarm: inactive`), so this workflow applies
+# the compose files under deploy/galactus/, NOT the Swarm files in deploy/.
+# .gitea/workflows/deploy.yml is the cubex/Swarm equivalent; the two are kept
+# separate on purpose because plain compose silently ignores Swarm's `deploy:`
+# keys rather than failing on them.
+#
+# This does NOT build. build.yml already built + pushed both images from one
+# matrix run, so api and web at the same tag are always in step.
+#
+# Order of operations, and why:
+#   1. db + minio           (scope=full only) — the API depends on both.
+#   2. pre-migrate backup   dumped INSIDE the still-running OLD api container,
+#                           so the file lands in the volume the Operaciones
+#                           restore screen reads. Must precede the migration.
+#   3. prisma migrate deploy  forward-only. Prisma has no down-migrations; see
+#                           docs/DEPLOY_AND_MIGRATIONS.md — expand/contract is
+#                           the rule, the backup is the emergency lever.
+#   4. app (api + web)      the new images.
+#   5. verify               ask the running API what it actually is.
+#
+# Rollback = re-dispatch with an older `tag`. That rolls back CODE only; the
+# schema stays forward. This is exactly why every schema change must be
+# backward-compatible with the previous release.
+#
+# Prereqs (once):
+#  - Gitea repo secrets, galactus-specific (suffix _GALACTUS so the cubex
+#    secrets keep working side by side):
+#      PORTAINER_URL_GALACTUS         https://100.103.77.46:9443
+#      PORTAINER_API_KEY_GALACTUS     Portainer access token for galactus
+#      PORTAINER_ENDPOINT_ID_GALACTUS 3
+#      PORTAINER_APP_STACK_NAME_GALACTUS    e.g. jorgecuadros-prod-app
+#      PORTAINER_DB_STACK_NAME_GALACTUS     e.g. jorgecuadros-prod-db
+#      PORTAINER_MINIO_STACK_NAME_GALACTUS  e.g. jorgecuadros-prod-minio
+#      DATABASE_URL_GALACTUS          mysql://jorgecuadros:<pass>@<galactus>:3306/jorgecuadros
+#      APP_API_ORIGIN_GALACTUS        browser-facing API URL
+#      APP_WEB_ORIGIN_GALACTUS        web public origin (API CORS)
+#      APP_S3_ENDPOINT_GALACTUS       server-side minio URL
+#      SESSION_SECRET_GALACTUS        64-hex (openssl rand -hex 32)
+#      MINIO_ROOT_USER / MINIO_ROOT_PASSWORD
+#      MYSQL_PASSWORD / MYSQL_ROOT_PASSWORD
+#  - The runner (which lives on cubex) must be able to reach BOTH
+#    galactus:9443 (Portainer) and galactus:3306 (MySQL, for migrate deploy).
+#    If it cannot reach 3306, run the migration by hand from a host that can
+#    and dispatch with skip_migrate=true.
+#  - ONE-TIME, on a database that predates migration history (i.e. one built
+#    with `prisma db push`): baseline it before the first run, or step 3 fails
+#    with P3005 "database schema is not empty":
+#      npx prisma@5 migrate resolve --applied 0000_init \
+#        --schema packages/database/prisma/schema.prisma
+
+name: Deploy to galactus
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Image tag to deploy (1.2.3 — no leading v — or sha-<short>, or latest)"
+        required: true
+        default: "latest"
+      scope:
+        description: "What to deploy"
+        type: choice
+        required: true
+        default: "app"
+        options:
+          - app
+          - full
+      bootstrap:
+        description: "First-ever deploy: allow the pre-migrate backup to be skipped when no API container exists yet"
+        type: boolean
+        required: false
+        default: false
+      skip_migrate:
+        description: "Skip prisma migrate deploy (use when the runner cannot reach MySQL and you migrated by hand)"
+        type: boolean
+        required: false
+        default: false
+
+env:
+  REGISTRY: git.mancinas.io
+
+jobs:
+  deploy:
+    name: Deploy ${{ github.event.inputs.tag }} (${{ github.event.inputs.scope }})
+    runs-on: docker
+    container:
+      image: node:20-alpine
+    steps:
+      - name: Install tools
+        # openssl: prisma's migration engine picks its musl/openssl build at
+        # runtime and cannot resolve one without it.
+        run: apk add --no-cache openssl ca-certificates git
+
+      - uses: actions/checkout@v4
+
+      # An unset secret arrives as an empty string, and the deploy action then
+      # fails with "Input required and not supplied: token" — which names the
+      # action's input, not the secret you forgot. Check them up front and say
+      # exactly which ones are missing.
+      - name: Preflight — required secrets
+        env:
+          PORTAINER_URL_GALACTUS: ${{ secrets.PORTAINER_URL_GALACTUS }}
+          PORTAINER_API_KEY_GALACTUS: ${{ secrets.PORTAINER_API_KEY_GALACTUS }}
+          PORTAINER_ENDPOINT_ID_GALACTUS: ${{ secrets.PORTAINER_ENDPOINT_ID_GALACTUS }}
+          PORTAINER_APP_STACK_NAME_GALACTUS: ${{ secrets.PORTAINER_APP_STACK_NAME_GALACTUS }}
+          PORTAINER_DB_STACK_NAME_GALACTUS: ${{ secrets.PORTAINER_DB_STACK_NAME_GALACTUS }}
+          PORTAINER_MINIO_STACK_NAME_GALACTUS: ${{ secrets.PORTAINER_MINIO_STACK_NAME_GALACTUS }}
+          DATABASE_URL_GALACTUS: ${{ secrets.DATABASE_URL_GALACTUS }}
+          SESSION_SECRET_GALACTUS: ${{ secrets.SESSION_SECRET_GALACTUS }}
+          APP_API_ORIGIN_GALACTUS: ${{ secrets.APP_API_ORIGIN_GALACTUS }}
+          APP_WEB_ORIGIN_GALACTUS: ${{ secrets.APP_WEB_ORIGIN_GALACTUS }}
+          APP_S3_ENDPOINT_GALACTUS: ${{ secrets.APP_S3_ENDPOINT_GALACTUS }}
+          MINIO_ROOT_USER: ${{ secrets.MINIO_ROOT_USER }}
+          MINIO_ROOT_PASSWORD: ${{ secrets.MINIO_ROOT_PASSWORD }}
+          MYSQL_PASSWORD: ${{ secrets.MYSQL_PASSWORD }}
+          MYSQL_ROOT_PASSWORD: ${{ secrets.MYSQL_ROOT_PASSWORD }}
+          SCOPE: ${{ github.event.inputs.scope }}
+        run: |
+          REQUIRED="PORTAINER_URL_GALACTUS PORTAINER_API_KEY_GALACTUS
+            PORTAINER_ENDPOINT_ID_GALACTUS PORTAINER_APP_STACK_NAME_GALACTUS
+            DATABASE_URL_GALACTUS SESSION_SECRET_GALACTUS
+            APP_API_ORIGIN_GALACTUS APP_WEB_ORIGIN_GALACTUS
+            APP_S3_ENDPOINT_GALACTUS MINIO_ROOT_USER MINIO_ROOT_PASSWORD
+            MYSQL_ROOT_PASSWORD"
+          if [ "$SCOPE" = "full" ]; then
+            REQUIRED="$REQUIRED PORTAINER_DB_STACK_NAME_GALACTUS
+              PORTAINER_MINIO_STACK_NAME_GALACTUS MYSQL_PASSWORD"
+          fi
+          missing=""
+          for name in $REQUIRED; do
+            eval "value=\${$name}"
+            [ -z "$value" ] && missing="$missing $name"
+          done
+          if [ -n "$missing" ]; then
+            echo "::error::missing repo secrets:$missing"
+            echo "::error::set them under Settings > Actions > Secrets"
+            exit 1
+          fi
+          echo "all required secrets present for scope=$SCOPE"
+
+      # --- full only: database ---------------------------------------------
+      - name: Deploy database stack
+        if: ${{ github.event.inputs.scope == 'full' }}
+        uses: cssnr/portainer-stack-deploy-action@v1
+        with:
+          url: ${{ secrets.PORTAINER_URL_GALACTUS }}
+          token: ${{ secrets.PORTAINER_API_KEY_GALACTUS }}
+          name: ${{ secrets.PORTAINER_DB_STACK_NAME_GALACTUS }}
+          file: deploy/galactus/jorgecuadros-db.compose.yml
+          type: file
+          standalone: true
+          endpoint: ${{ secrets.PORTAINER_ENDPOINT_ID_GALACTUS }}
+          env_data: |
+            {
+              "MYSQL_SERVER_ID": "1",
+              "MYSQL_PORT": "3306",
+              "MYSQL_DATABASE": "jorgecuadros",
+              "MYSQL_USER": "jorgecuadros",
+              "MYSQL_PASSWORD": "${{ secrets.MYSQL_PASSWORD }}",
+              "MYSQL_ROOT_PASSWORD": "${{ secrets.MYSQL_ROOT_PASSWORD }}"
+            }
+
+      # --- full only: object storage ---------------------------------------
+      - name: Deploy minio stack
+        if: ${{ github.event.inputs.scope == 'full' }}
+        uses: cssnr/portainer-stack-deploy-action@v1
+        with:
+          url: ${{ secrets.PORTAINER_URL_GALACTUS }}
+          token: ${{ secrets.PORTAINER_API_KEY_GALACTUS }}
+          name: ${{ secrets.PORTAINER_MINIO_STACK_NAME_GALACTUS }}
+          file: deploy/galactus/jorgecuadros-minio.compose.yml
+          type: file
+          standalone: true
+          endpoint: ${{ secrets.PORTAINER_ENDPOINT_ID_GALACTUS }}
+          env_data: |
+            {
+              "MINIO_API_PORT": "9000",
+              "MINIO_CONSOLE_PORT": "9001",
+              "MINIO_ROOT_USER": "${{ secrets.MINIO_ROOT_USER }}",
+              "MINIO_ROOT_PASSWORD": "${{ secrets.MINIO_ROOT_PASSWORD }}"
+            }
+
+      # --- restore point, taken while the OLD api container is still up ------
+      - name: Pre-migrate backup
+        env:
+          PORTAINER_URL: ${{ secrets.PORTAINER_URL_GALACTUS }}
+          PORTAINER_API_KEY: ${{ secrets.PORTAINER_API_KEY_GALACTUS }}
+          PORTAINER_ENDPOINT_ID: ${{ secrets.PORTAINER_ENDPOINT_ID_GALACTUS }}
+          DATABASE_URL: ${{ secrets.DATABASE_URL_GALACTUS }}
+          # The dump runs as root: --single-transaction issues FLUSH TABLES,
+          # which needs the global RELOAD privilege the application user
+          # deliberately does not have.
+          MYSQL_ROOT_PASSWORD: ${{ secrets.MYSQL_ROOT_PASSWORD }}
+          BACKUP_TAG: ${{ github.event.inputs.tag }}
+          ALLOW_MISSING_CONTAINER: ${{ github.event.inputs.bootstrap }}
+          # Portainer serves a self-signed certificate. Scoped to this step
+          # only, which does nothing but talk to Portainer.
+          NODE_TLS_REJECT_UNAUTHORIZED: "0"
+        run: node deploy/scripts/pre-migrate-backup.mjs
+
+      # --- schema, forward-only ---------------------------------------------
+      - name: Apply database migrations
+        if: ${{ github.event.inputs.skip_migrate != 'true' }}
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL_GALACTUS }}
+        run: |
+          set -e
+          SCHEMA=packages/database/prisma/schema.prisma
+          npx --yes prisma@5 migrate status --schema "$SCHEMA" || true
+          if ! npx --yes prisma@5 migrate deploy --schema "$SCHEMA"; then
+            echo "::error::migrate deploy failed. If this is P3005 (schema not empty),"
+            echo "::error::the database predates migration history — baseline it once with:"
+            echo "::error::  npx prisma@5 migrate resolve --applied 0000_init --schema $SCHEMA"
+            exit 1
+          fi
+
+      # --- make sure the host actually has the images ------------------------
+      # The deploy action's `pull: true` does not reliably refresh an already
+      # cached moving tag. Pull explicitly, or a "successful" deploy can leave
+      # the host serving an older build of the same tag.
+      - name: Pull images
+        env:
+          PORTAINER_URL: ${{ secrets.PORTAINER_URL_GALACTUS }}
+          PORTAINER_API_KEY: ${{ secrets.PORTAINER_API_KEY_GALACTUS }}
+          PORTAINER_ENDPOINT_ID: ${{ secrets.PORTAINER_ENDPOINT_ID_GALACTUS }}
+          REGISTRY: ${{ env.REGISTRY }}
+          REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
+          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+          IMAGES: ${{ github.repository_owner }}/jorgecuadros-api,${{ github.repository_owner }}/jorgecuadros-web
+          TAG: ${{ github.event.inputs.tag }}
+          NODE_TLS_REJECT_UNAUTHORIZED: "0"
+        run: node deploy/scripts/pull-images.mjs
+
+      # --- always: the app (web + api) -------------------------------------
+      - name: Deploy app stack
+        uses: cssnr/portainer-stack-deploy-action@v1
+        with:
+          url: ${{ secrets.PORTAINER_URL_GALACTUS }}
+          token: ${{ secrets.PORTAINER_API_KEY_GALACTUS }}
+          name: ${{ secrets.PORTAINER_APP_STACK_NAME_GALACTUS }}
+          file: deploy/galactus/jorgecuadros-app.compose.yml
+          type: file
+          standalone: true
+          pull: true
+          endpoint: ${{ secrets.PORTAINER_ENDPOINT_ID_GALACTUS }}
+          env_data: |
+            {
+              "APP_TAG": "${{ github.event.inputs.tag }}",
+              "API_PORT": "3001",
+              "WEB_PORT": "3000",
+              "S3_BUCKET": "jorgecuadros-documents",
+              "API_ORIGIN": "${{ secrets.APP_API_ORIGIN_GALACTUS }}",
+              "WEB_ORIGIN": "${{ secrets.APP_WEB_ORIGIN_GALACTUS }}",
+              "S3_ENDPOINT": "${{ secrets.APP_S3_ENDPOINT_GALACTUS }}",
+              "DATABASE_URL": "${{ secrets.DATABASE_URL_GALACTUS }}",
+              "SESSION_SECRET": "${{ secrets.SESSION_SECRET_GALACTUS }}",
+              "SESSION_COOKIE_SECURE": "false",
+              "OPS_DB_ADMIN_USER": "root",
+              "OPS_DB_ADMIN_PASSWORD": "${{ secrets.MYSQL_ROOT_PASSWORD }}",
+              "MINIO_ROOT_USER": "${{ secrets.MINIO_ROOT_USER }}",
+              "MINIO_ROOT_PASSWORD": "${{ secrets.MINIO_ROOT_PASSWORD }}"
+            }
+
+      # --- prove it ----------------------------------------------------------
+      - name: Verify running version
+        env:
+          API_ORIGIN: ${{ secrets.APP_API_ORIGIN_GALACTUS }}
+          WEB_ORIGIN: ${{ secrets.APP_WEB_ORIGIN_GALACTUS }}
+          WANT: ${{ github.event.inputs.tag }}
+        # A stack naming a tag is not proof the containers run it. Ask BOTH
+        # tiers what they are, and require them to be the same commit: api and
+        # web are built from one matrix run, so a difference can only mean one
+        # of them did not actually get replaced.
+        run: |
+          set -e
+          apk add --no-cache curl >/dev/null
+          fetch_version() {
+            for i in $(seq 1 30); do
+              if curl -fsS "$1/version" > "$2"; then return 0; fi
+              echo "waiting for $1 ($i/30)..."
+              sleep 5
+            done
+            echo "::error::$1/version never answered"
+            return 1
+          }
+          fetch_version "$API_ORIGIN" /tmp/api.json
+          fetch_version "$WEB_ORIGIN" /tmp/web.json
+          cat /tmp/api.json; echo; cat /tmp/web.json; echo
+
+          API_SHA=$(node -e 'console.log(require("/tmp/api.json").gitSha)')
+          WEB_SHA=$(node -e 'console.log(require("/tmp/web.json").gitSha)')
+          API_VER=$(node -e 'console.log(require("/tmp/api.json").version)')
+
+          # Compare the COMMIT, not the version string: on a branch build both
+          # tiers report "master", so version equality proves nothing.
+          if [ "$API_SHA" != "$WEB_SHA" ]; then
+            echo "::error::api and web are different builds — api $API_SHA, web $WEB_SHA"
+            echo "::error::one of the images was not replaced; check the Pull images step"
+            exit 1
+          fi
+          echo "api and web agree: $API_SHA"
+
+          # A semver dispatch is additionally comparable to the tag itself:
+          # metadata-action's {{version}} turns tag v1.2.3 into image 1.2.3,
+          # while `latest` and `sha-*` report the branch or short sha instead.
+          case "$WANT" in
+            [0-9]*.[0-9]*.[0-9]*)
+              if [ "$API_VER" != "$WANT" ]; then
+                echo "::error::deployed $WANT but the API reports $API_VER"
+                exit 1
+              fi
+              echo "verified: running $API_VER"
+              ;;
+            *)
+              echo "dispatched '$WANT'; tiers report '$API_VER' (not directly comparable)"
+              ;;
+          esac

.gitea/workflows/deploy.yml

@@ -0,0 +1,321 @@
+# Manual PROD deploy to Portainer.
+#
+# This does NOT build — build.yml already builds + pushes the api/web images.
+# This workflow (re)applies the deploy/*.stack.yml files to the Portainer Swarm.
+# Trigger it by hand from the Actions tab ("Run workflow") and choose:
+#   - tag:   which already-published image tag to ship (default: latest)
+#   - scope: how much to deploy
+#       app  = web + api only (the usual app release)      [default]
+#       full = db + minio + web + api (bring up / update the whole platform)
+#
+# The `tag` input carries NO leading `v`: metadata-action's {{version}} turns
+# git tag v1.2.3 into image tag 1.2.3. Tag v1.2.3, dispatch 1.2.3.
+#
+# Order: db+minio (full only) -> pre-migrate backup -> prisma migrate deploy ->
+# app -> verify the API reports the version you asked for. Rollback = dispatch
+# an older tag; that rolls back CODE only, never the schema, which is why every
+# schema change must be expand/contract. See docs/DEPLOY_AND_MIGRATIONS.md.
+#
+# galactus (the office server) is standalone Docker, not this Swarm — it has its
+# own workflow, .gitea/workflows/deploy-galactus.yml.
+#
+# cssnr/portainer-stack-deploy-action creates each stack on first run and updates
+# it on every run, so no manual stack pre-creation in the Portainer UI. On a
+# `full` deploy the db + minio stacks are applied BEFORE the app (the API depends
+# on them). db + minio are stateful + pinned to node label jorgecuadros_db=true
+# (see their stack files) — re-applying them is idempotent and keeps their data.
+#
+# Prereqs (once):
+#  - one swarm node labelled jorgecuadros_db=true (db + minio + api pin there).
+#  - Gitea repo secrets set (Settings > Actions > Secrets):
+#      # Portainer
+#      PORTAINER_URL              https://192.168.4.212:9443
+#      PORTAINER_API_KEY          Portainer access token
+#      PORTAINER_ENDPOINT_ID      2  (the local Swarm endpoint)
+#      PORTAINER_APP_STACK_NAME   e.g. jorgecuadros-prod-app
+#      PORTAINER_DB_STACK_NAME    e.g. jorgecuadros-prod-db      (full only)
+#      PORTAINER_MINIO_STACK_NAME e.g. jorgecuadros-prod-minio   (full only)
+#      # App runtime
+#      DATABASE_URL               mysql://jorgecuadros:<pass>@192.168.4.212:3306/jorgecuadros
+#      SESSION_SECRET             64-hex (openssl rand -hex 32)
+#      APP_API_ORIGIN             http://192.168.4.212:3001  (browser-facing API URL)
+#      APP_WEB_ORIGIN             http://192.168.4.212:3000  (web public origin, API CORS)
+#      APP_S3_ENDPOINT            http://192.168.4.212:9000  (server-side minio URL)
+#      # Object storage (app + minio stack)
+#      MINIO_ROOT_USER            minio access key
+#      MINIO_ROOT_PASSWORD        minio secret key
+#      # Database stack (full only)
+#      MYSQL_PASSWORD             app-user password (matches DATABASE_URL)
+#      MYSQL_ROOT_PASSWORD        mysql root password
+#  - the runner must reach BOTH Portainer (9443) and MySQL (3306) — the
+#    migration step connects to the database directly. If it cannot reach 3306,
+#    migrate by hand and dispatch with skip_migrate=true.
+#  - ONE-TIME on a database built with `prisma db push` (i.e. every database
+#    that exists today): baseline it before the first run, or the migrate step
+#    fails with P3005 "database schema is not empty":
+#      npx prisma@5 migrate resolve --applied 0000_init \
+#        --schema packages/database/prisma/schema.prisma
+
+name: Deploy to Portainer
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Image tag to deploy (latest, sha-<short>, or vX.Y.Z)"
+        required: true
+        default: "latest"
+      scope:
+        description: "What to deploy"
+        type: choice
+        required: true
+        default: "app"
+        options:
+          - app
+          - full
+      bootstrap:
+        description: "First-ever deploy: allow the pre-migrate backup to be skipped when no API container exists yet"
+        type: boolean
+        required: false
+        default: false
+      skip_migrate:
+        description: "Skip prisma migrate deploy (use when the runner cannot reach MySQL and you migrated by hand)"
+        type: boolean
+        required: false
+        default: false
+
+env:
+  REGISTRY: git.mancinas.io
+
+jobs:
+  deploy:
+    name: Deploy (${{ github.event.inputs.scope }})
+    runs-on: docker
+    container:
+      image: node:20-alpine
+    steps:
+      - name: Install tools
+        # openssl: prisma's migration engine picks its musl/openssl build at
+        # runtime and cannot resolve one without it.
+        run: apk add --no-cache openssl ca-certificates git
+
+      - uses: actions/checkout@v4
+
+      # An unset secret arrives as an empty string, and the deploy action then
+      # fails with "Input required and not supplied: token" — which names the
+      # action's input, not the secret you forgot.
+      - name: Preflight — required secrets
+        env:
+          PORTAINER_URL: ${{ secrets.PORTAINER_URL }}
+          PORTAINER_API_KEY: ${{ secrets.PORTAINER_API_KEY }}
+          PORTAINER_ENDPOINT_ID: ${{ secrets.PORTAINER_ENDPOINT_ID }}
+          PORTAINER_APP_STACK_NAME: ${{ secrets.PORTAINER_APP_STACK_NAME }}
+          PORTAINER_DB_STACK_NAME: ${{ secrets.PORTAINER_DB_STACK_NAME }}
+          PORTAINER_MINIO_STACK_NAME: ${{ secrets.PORTAINER_MINIO_STACK_NAME }}
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          SESSION_SECRET: ${{ secrets.SESSION_SECRET }}
+          APP_API_ORIGIN: ${{ secrets.APP_API_ORIGIN }}
+          APP_WEB_ORIGIN: ${{ secrets.APP_WEB_ORIGIN }}
+          APP_S3_ENDPOINT: ${{ secrets.APP_S3_ENDPOINT }}
+          MINIO_ROOT_USER: ${{ secrets.MINIO_ROOT_USER }}
+          MINIO_ROOT_PASSWORD: ${{ secrets.MINIO_ROOT_PASSWORD }}
+          MYSQL_PASSWORD: ${{ secrets.MYSQL_PASSWORD }}
+          MYSQL_ROOT_PASSWORD: ${{ secrets.MYSQL_ROOT_PASSWORD }}
+          SCOPE: ${{ github.event.inputs.scope }}
+        run: |
+          REQUIRED="PORTAINER_URL PORTAINER_API_KEY PORTAINER_ENDPOINT_ID
+            PORTAINER_APP_STACK_NAME DATABASE_URL SESSION_SECRET
+            APP_API_ORIGIN APP_WEB_ORIGIN APP_S3_ENDPOINT
+            MINIO_ROOT_USER MINIO_ROOT_PASSWORD MYSQL_ROOT_PASSWORD"
+          if [ "$SCOPE" = "full" ]; then
+            REQUIRED="$REQUIRED PORTAINER_DB_STACK_NAME PORTAINER_MINIO_STACK_NAME
+              MYSQL_PASSWORD"
+          fi
+          missing=""
+          for name in $REQUIRED; do
+            eval "value=\${$name}"
+            [ -z "$value" ] && missing="$missing $name"
+          done
+          if [ -n "$missing" ]; then
+            echo "::error::missing repo secrets:$missing"
+            echo "::error::set them under Settings > Actions > Secrets"
+            exit 1
+          fi
+          echo "all required secrets present for scope=$SCOPE"
+
+      # --- full only: database ---------------------------------------------
+      - name: Deploy database stack
+        if: ${{ github.event.inputs.scope == 'full' }}
+        uses: cssnr/portainer-stack-deploy-action@v1
+        with:
+          url: ${{ secrets.PORTAINER_URL }}
+          token: ${{ secrets.PORTAINER_API_KEY }}
+          name: ${{ secrets.PORTAINER_DB_STACK_NAME }}
+          file: deploy/jorgecuadros-db.stack.yml
+          type: file
+          endpoint: ${{ secrets.PORTAINER_ENDPOINT_ID }}
+          env_data: |
+            {
+              "MYSQL_SERVER_ID": "1",
+              "MYSQL_PORT": "3306",
+              "MYSQL_DATABASE": "jorgecuadros",
+              "MYSQL_USER": "jorgecuadros",
+              "MYSQL_PASSWORD": "${{ secrets.MYSQL_PASSWORD }}",
+              "MYSQL_ROOT_PASSWORD": "${{ secrets.MYSQL_ROOT_PASSWORD }}"
+            }
+
+      # --- full only: object storage ---------------------------------------
+      - name: Deploy minio stack
+        if: ${{ github.event.inputs.scope == 'full' }}
+        uses: cssnr/portainer-stack-deploy-action@v1
+        with:
+          url: ${{ secrets.PORTAINER_URL }}
+          token: ${{ secrets.PORTAINER_API_KEY }}
+          name: ${{ secrets.PORTAINER_MINIO_STACK_NAME }}
+          file: deploy/jorgecuadros-minio.stack.yml
+          type: file
+          endpoint: ${{ secrets.PORTAINER_ENDPOINT_ID }}
+          env_data: |
+            {
+              "MINIO_API_PORT": "9000",
+              "MINIO_CONSOLE_PORT": "9001",
+              "MINIO_ROOT_USER": "${{ secrets.MINIO_ROOT_USER }}",
+              "MINIO_ROOT_PASSWORD": "${{ secrets.MINIO_ROOT_PASSWORD }}"
+            }
+
+      # --- restore point, taken while the OLD api container is still up ------
+      # Dumped INSIDE the running api container so the file lands in the volume
+      # the "Operaciones" restore screen reads — a dump on the runner would be
+      # unreachable by the only restore path this platform has.
+      - name: Pre-migrate backup
+        env:
+          PORTAINER_URL: ${{ secrets.PORTAINER_URL }}
+          PORTAINER_API_KEY: ${{ secrets.PORTAINER_API_KEY }}
+          PORTAINER_ENDPOINT_ID: ${{ secrets.PORTAINER_ENDPOINT_ID }}
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          # The dump runs as root: --single-transaction issues FLUSH TABLES,
+          # which needs the global RELOAD privilege the application user
+          # deliberately does not have.
+          MYSQL_ROOT_PASSWORD: ${{ secrets.MYSQL_ROOT_PASSWORD }}
+          BACKUP_TAG: ${{ github.event.inputs.tag }}
+          ALLOW_MISSING_CONTAINER: ${{ github.event.inputs.bootstrap }}
+          # Portainer serves a self-signed certificate. Scoped to this step
+          # only, which does nothing but talk to Portainer.
+          NODE_TLS_REJECT_UNAUTHORIZED: "0"
+        run: node deploy/scripts/pre-migrate-backup.mjs
+
+      # --- schema, forward-only ---------------------------------------------
+      # Prisma has no down-migrations: a code rollback does NOT roll the schema
+      # back. See docs/DEPLOY_AND_MIGRATIONS.md — every change must be
+      # expand/contract so the previous release still runs against the new
+      # schema. Run as a deploy STEP, never as the container CMD: N replicas
+      # would race each other applying the same migration.
+      - name: Apply database migrations
+        if: ${{ github.event.inputs.skip_migrate != 'true' }}
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+        run: |
+          set -e
+          SCHEMA=packages/database/prisma/schema.prisma
+          npx --yes prisma@5 migrate status --schema "$SCHEMA" || true
+          if ! npx --yes prisma@5 migrate deploy --schema "$SCHEMA"; then
+            echo "::error::migrate deploy failed. If this is P3005 (schema not empty),"
+            echo "::error::the database predates migration history — baseline it once with:"
+            echo "::error::  npx prisma@5 migrate resolve --applied 0000_init --schema $SCHEMA"
+            exit 1
+          fi
+
+      # --- make sure the host actually has the images ------------------------
+      # The deploy action's `pull: true` does not reliably refresh an already
+      # cached moving tag; without this a "successful" deploy can leave the host
+      # serving an older build of the same tag.
+      - name: Pull images
+        env:
+          PORTAINER_URL: ${{ secrets.PORTAINER_URL }}
+          PORTAINER_API_KEY: ${{ secrets.PORTAINER_API_KEY }}
+          PORTAINER_ENDPOINT_ID: ${{ secrets.PORTAINER_ENDPOINT_ID }}
+          REGISTRY: ${{ env.REGISTRY }}
+          REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
+          REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+          IMAGES: ${{ github.repository_owner }}/jorgecuadros-api,${{ github.repository_owner }}/jorgecuadros-web
+          TAG: ${{ github.event.inputs.tag }}
+          NODE_TLS_REJECT_UNAUTHORIZED: "0"
+        run: node deploy/scripts/pull-images.mjs
+
+      # --- always: the app (web + api) -------------------------------------
+      - name: Deploy app stack
+        uses: cssnr/portainer-stack-deploy-action@v1
+        with:
+          url: ${{ secrets.PORTAINER_URL }}
+          token: ${{ secrets.PORTAINER_API_KEY }}
+          name: ${{ secrets.PORTAINER_APP_STACK_NAME }}
+          file: deploy/jorgecuadros-app.stack.yml
+          type: file
+          pull: true
+          endpoint: ${{ secrets.PORTAINER_ENDPOINT_ID }}
+          env_data: |
+            {
+              "APP_TAG": "${{ github.event.inputs.tag }}",
+              "API_PORT": "3001",
+              "WEB_PORT": "3000",
+              "S3_BUCKET": "jorgecuadros-documents",
+              "API_ORIGIN": "${{ secrets.APP_API_ORIGIN }}",
+              "WEB_ORIGIN": "${{ secrets.APP_WEB_ORIGIN }}",
+              "S3_ENDPOINT": "${{ secrets.APP_S3_ENDPOINT }}",
+              "DATABASE_URL": "${{ secrets.DATABASE_URL }}",
+              "SESSION_SECRET": "${{ secrets.SESSION_SECRET }}",
+              "OPS_DB_ADMIN_USER": "root",
+              "OPS_DB_ADMIN_PASSWORD": "${{ secrets.MYSQL_ROOT_PASSWORD }}",
+              "MINIO_ROOT_USER": "${{ secrets.MINIO_ROOT_USER }}",
+              "MINIO_ROOT_PASSWORD": "${{ secrets.MINIO_ROOT_PASSWORD }}"
+            }
+
+      # --- prove it ----------------------------------------------------------
+      # A stack naming a tag is not proof the container is running it — a
+      # skipped pull leaves the old code up. Ask the API what it actually is.
+      - name: Verify running version
+        env:
+          API_ORIGIN: ${{ secrets.APP_API_ORIGIN }}
+          WEB_ORIGIN: ${{ secrets.APP_WEB_ORIGIN }}
+          WANT: ${{ github.event.inputs.tag }}
+        run: |
+          set -e
+          apk add --no-cache curl >/dev/null
+          fetch_version() {
+            for i in $(seq 1 30); do
+              if curl -fsS "$1/version" > "$2"; then return 0; fi
+              echo "waiting for $1 ($i/30)..."
+              sleep 5
+            done
+            echo "::error::$1/version never answered"
+            return 1
+          }
+          fetch_version "$API_ORIGIN" /tmp/api.json
+          fetch_version "$WEB_ORIGIN" /tmp/web.json
+          cat /tmp/api.json; echo; cat /tmp/web.json; echo
+
+          API_SHA=$(node -e 'console.log(require("/tmp/api.json").gitSha)')
+          WEB_SHA=$(node -e 'console.log(require("/tmp/web.json").gitSha)')
+          API_VER=$(node -e 'console.log(require("/tmp/api.json").version)')
+
+          # Compare the COMMIT, not the version string: on a branch build both
+          # tiers report "master", so version equality proves nothing.
+          if [ "$API_SHA" != "$WEB_SHA" ]; then
+            echo "::error::api and web are different builds — api $API_SHA, web $WEB_SHA"
+            echo "::error::one of the images was not replaced; check the Pull images step"
+            exit 1
+          fi
+          echo "api and web agree: $API_SHA"
+
+          case "$WANT" in
+            [0-9]*.[0-9]*.[0-9]*)
+              if [ "$API_VER" != "$WANT" ]; then
+                echo "::error::deployed $WANT but the API reports $API_VER"
+                exit 1
+              fi
+              echo "verified: running $API_VER"
+              ;;
+            *)
+              echo "dispatched '$WANT'; tiers report '$API_VER' (not directly comparable)"
+              ;;
+          esac

.gitea/workflows/release.yml

@@ -0,0 +1,166 @@
+# Cut a release: stamp the version across every package.json, commit, tag, push.
+#
+# This does NOT build and does NOT deploy. Pushing the `vX.Y.Z` tag is what
+# triggers build.yml, which publishes `X.Y.Z`, `X.Y`, `sha-<short>` and `latest`
+# image tags. Deploying stays a separate, deliberate act: once the build is
+# green, dispatch deploy-galactus.yml with `tag=X.Y.Z` (no leading v — the tag
+# carries the `v`, the image tag does not).
+#
+# Why a workflow instead of three local commands: the release commit is the one
+# thing that must be identical every time, and cutting it from a laptop is how
+# a manifest bump gets forgotten or a tag lands on an unpushed commit. Here the
+# only input is the number.
+#
+# Prereqs (once):
+#  - Repo secret RELEASE_TOKEN: a Gitea personal access token with
+#    write:repository on this repo. The built-in Actions token is deliberately
+#    NOT used — whether a push made with it re-triggers build.yml depends on the
+#    Gitea version, and a release that silently publishes no images is worse
+#    than one that fails. A PAT push is an ordinary push and always triggers.
+#    If build.yml somehow does not start, it has workflow_dispatch: run it
+#    against the new tag by hand.
+
+name: Cut release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Which part to bump (choose 'explicit' to type the number)"
+        type: choice
+        required: true
+        default: "minor"
+        options:
+          - patch
+          - minor
+          - major
+          - explicit
+      version:
+        description: "Exact version when bump=explicit (x.y.z, no leading v)"
+        required: false
+        default: ""
+
+jobs:
+  release:
+    name: Release
+    runs-on: docker
+    container:
+      image: node:20-alpine
+    steps:
+      - name: Install tools
+        run: apk add --no-cache git
+
+      - name: Preflight — RELEASE_TOKEN
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          set -eu
+          if [ -z "${RELEASE_TOKEN:-}" ]; then
+            echo "::error::Secret RELEASE_TOKEN is not set. Create a Gitea PAT with"
+            echo "::error::write:repository and add it as a repo secret named RELEASE_TOKEN."
+            exit 1
+          fi
+
+      # Full history + tags: the duplicate-tag check below is meaningless
+      # against a shallow clone, which has none of them.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: master
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Resolve the new version
+        id: ver
+        env:
+          BUMP: ${{ github.event.inputs.bump }}
+          EXPLICIT: ${{ github.event.inputs.version }}
+        run: |
+          set -eu
+          CURRENT=$(node -p "require('./package.json').version")
+          echo "current: $CURRENT"
+
+          if [ "$BUMP" = "explicit" ]; then
+            NEXT="$EXPLICIT"
+            if [ -z "$NEXT" ]; then
+              echo "::error::bump=explicit requires the version input."
+              exit 1
+            fi
+          else
+            NEXT=$(node -e '
+              const [cur, part] = process.argv.slice(1);
+              const m = /^(\d+)\.(\d+)\.(\d+)/.exec(cur);
+              if (!m) { console.error(`unparseable current version: ${cur}`); process.exit(1); }
+              let [maj, min, pat] = m.slice(1).map(Number);
+              if (part === "major") { maj += 1; min = 0; pat = 0; }
+              else if (part === "minor") { min += 1; pat = 0; }
+              else { pat += 1; }
+              process.stdout.write(`${maj}.${min}.${pat}`);
+            ' "$CURRENT" "$BUMP")
+          fi
+
+          # set-version.mjs validates the shape too, but failing here keeps the
+          # working tree clean when the input is a typo.
+          case "$NEXT" in
+            v*) echo "::error::Version must not carry a leading 'v' (got $NEXT)."; exit 1 ;;
+          esac
+          if ! printf '%s' "$NEXT" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$'; then
+            echo "::error::Invalid version: $NEXT (expected x.y.z)."
+            exit 1
+          fi
+          if [ "$NEXT" = "$CURRENT" ]; then
+            echo "::error::$NEXT is already the current version."
+            exit 1
+          fi
+          if git rev-parse -q --verify "refs/tags/v$NEXT" >/dev/null; then
+            echo "::error::Tag v$NEXT already exists. Releases are immutable — pick a new number."
+            exit 1
+          fi
+
+          echo "next: $NEXT"
+          echo "version=$NEXT" >> "$GITHUB_OUTPUT"
+
+      - name: Stamp the version across every manifest
+        run: node scripts/set-version.mjs "${{ steps.ver.outputs.version }}"
+
+      # A release whose only content is the version bump means the dispatch was
+      # a mistake — set-version.mjs already refused a no-op above, so an empty
+      # diff here means the manifests were somehow already at this number.
+      - name: Commit, tag, push
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          VERSION: ${{ steps.ver.outputs.version }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          set -eu
+          if git diff --quiet; then
+            echo "::error::No manifest changed. Nothing to release."
+            exit 1
+          fi
+
+          git config user.name "gitea-actions"
+          git config user.email "actions@git.mancinas.io"
+
+          git commit -a \
+            -m "chore(release): v${VERSION}" \
+            -m "Cut by ${ACTOR} via the \"Cut release\" workflow. Pushing the tag triggers build.yml; deploy separately with tag=${VERSION}."
+          git tag -a "v${VERSION}" -m "v${VERSION}"
+
+          # Re-point at an authenticated remote. The token is a secret, so Gitea
+          # masks it in the log; nothing here echoes the URL regardless.
+          git remote set-url origin \
+            "$(printf '%s' "${GITHUB_SERVER_URL}" | sed "s#://#://x-access-token:${RELEASE_TOKEN}@#")/${GITHUB_REPOSITORY}.git"
+
+          # One push for both refs: a commit that lands without its tag builds
+          # nothing and looks like a successful release.
+          git push origin "HEAD:master" "refs/tags/v${VERSION}"
+
+      - name: Summary
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          set -eu
+          echo "Released v${VERSION}."
+          echo ""
+          echo "build.yml is now building git.mancinas.io/rmancinas/jorgecuadros-{api,web}:${VERSION}."
+          echo "When it is green, dispatch 'Deploy to galactus' with:"
+          echo "  tag=${VERSION}  scope=app  bootstrap=false  skip_migrate=false"

PLAN.md

@@ -130,6 +130,27 @@ Given the amount of near-duplicate/overlapping data across snapshot tables (mult
 8. VPS provisioning + Tailscale + MySQL replication setup. `utility_dbo`'s schema is now available (full dump on disk — 55 tables; see Status), so the exact replicated table/column set and inbox-table shape can be finalized against the real portal DB and the portal PHP code (`my-jorgecuadros-web`) that reads/writes it.
 9. Sync worker (push replicated tables' relevant subset, poll inbox tables for payment/propane submissions) — depends on step 8. **The separate Phase B Access additive sync is implemented:** `migration/run_all.py --sync` and the admin `SYNC` job upsert legacy-owned rows without truncating the database or touching manual rows. Portal write points confirmed present in `utility_dbo`: `peticion_gas` (propane requests), PayPal payment writes, `notifications_settings`, `verification_codes` — these define the VPS→internal inbox set.
 10. Reports/email campaigns/admin — parity with old app's `reports.php`/`emailCampaigns.php` intent, rebuilt properly.
+11. **Receipt capture ("Editor") completion + three net-new ops features — NOT STARTED, spec written.** Full design in [`docs/RECEIPT_CAPTURE_SPEC.md`](docs/RECEIPT_CAPTURE_SPEC.md), from the 2026-07-25/26 meeting with Jorge:
+    - **Receipt capture module — DONE** (2026-07-27). The legacy "Editor" replacement, built on the single-movement capture from step 6. Wires up the previously-unused `Transaction.outstanding` (NOPAGO): capture flag on `POST /billing`, `?outstanding=` list filter, `POST /billing/:id/resolve-outstanding` (gated `ledger:create`, not `ledger:void` — resolving *completes* a capture), and exclusion from every balance aggregate exactly as the legacy `SALDOS ULTIMO 0`'s `HAVING NOPAGO = 0` did. Adds `POST /billing/batch` (one `$transaction`, check-level fields shared, per-line customer/amount) and `GET /billing/by-check`, plus the `cheque-count` report replacing `REPORTE CHEQUE COUNT` / `REPORTE POR CHEQUE` / `EDITA CHEQUE ALF|COUNT|NUM` — print/PDF/CSV/XLSX come free from the existing `/reportes/:slug` machinery. Web: `/estado-cuenta/lote` (the actual "Editor" screen, with live reconciliation against the physical check amount), plus an "Estado de pago" filter, a "sin fondos" row tag and a Resolver dialog on `/estado-cuenta`. No new abilities. Verified end-to-end against dev, API + browser.
+      **Two pre-existing bugs found and fixed while building it:** (a) `statement()` filtered `legacySourceTable: { notIn: [...] }`, which compiles to SQL `NOT IN` — and `NULL NOT IN (…)` is NULL, so **every app-captured movement was invisible on the customer statement** (438 rows in the movement browser vs 392 on the statement) while still appearing everywhere else. This would have made the whole receipt-capture feature look broken to staff. Now NULL-safe. (b) The balances *count* query omitted the void filter its own page query applied, so the row count disagreed with the rows.
+      **OCR seam:** `BillingService.createBatch(dto, opts)` is the single multi-row write path and carries three contract guarantees for the step-11 OCR module to post through — `items[i]` maps to `lines[i]` (so `StatementDocument.postedTransactionId` can be zipped back on), `opts.refs[i]` stamps `captureRef` with a duplicate-post guard that a *voided* row deliberately does not block, and `opts.source` is service-level only so an HTTP client cannot label hand-keyed rows as machine-captured. Backed by a new `TransactionCaptureSource` enum (MANUAL/BATCH/OCR) + `captureRef`, both nullable so the 40,136 migrated rows stay NULL rather than being mislabelled.
+    - **PDF/OCR auto-capture — DONE** (2026-08-01). The ingest→split→OCR→match→review pipeline for the 300+/month/service-provider statements staff key in by hand, built in `apps/api/src/statements/` and posting through §1.2's `createBatch` seam with `source: "OCR"` and a per-document `captureRef`. Web: `/recibos` + `/recibos/:id`. Abilities `statement:ingest`/`statement:review` (STAFF — the review step is what makes machine capture safe at that tier). OCR is self-hosted **Tesseract** behind a swappable `OcrProvider` interface; `tesseract-ocr`, `tesseract-ocr-data-spa` and `poppler-utils` were added to the API image.
+      **Every decision was driven by 10 real scans (46 pages).** Shipped-parser results on them: provider 46/46, account ref 43/46, amount 42/46, due date 44/46 — and against the dev database **39/46 (85%) exact auto-match, 40/46 (87%) identified**, the rest genuine review cases. The scans are pure images (no text layer), so OCR is mandatory, and they arrive **bundled one customer per page**.
+      **The three gaps are closed, and two of them were mis-stated in the spec.** (a) `TELEPHONE` now exists and is backfilled from `Property.phone1` only — coverage is 534/18/1 across phone1/2/3, so phone is one billed line per property, not three. (b) **Clave catastral ≠ predial**: `DATMEX.clave` (934 rows, `KA903009`) is what CESPT and predial bills actually print, while `predial` — what `PROPERTY_TAX.accountNumber` holds — has only 663 distinct values across 1135 rows and appears on no statement; the clave now lives on `Property.cadastralKey` as the matcher's secondary key and predial is left untouched. (c) Gas was **not** a dead end: 160 of the 334 `DATMEX.gas` values are real account numbers (the rest are `ESTACIONARIO`/`CILINDRO` descriptors), all recovered into `GAS.meterNumber`.
+      **Matching is scoped per service kind and never reads the customer name** — a CESPT receipt prints `ARNAIZ ROSAS ELSA AURORA` for an account this office holds under `CATT, RANDY`, because the name on a utility bill is the registrant, not the current owner. Normalisation is per provider: CFE strips leading zeros off `NO. DE SERVICIO`, Telnor strips the 664 LADA down to the stored local 7 digits. Where a provider prints a payment barcode it is preferred over the printed label (one CFE label OCR'd a digit too many while its barcode was correct) and the two are cross-checked, with disagreement forcing review. Confirming a document whose service had no reference writes it back, so gas and any other cold start is a one-time cost.
+    - **Multi-bank chequera — DONE** (2026-07-27). `Bank`/`BankAccount` models so Seguros (US bank) and Utilities (Mexican bank, currently SCOTHIA) can each have their own register. `bank_transactions` gained a **required** `bankAccountId` (plus an `(bankAccountId, transactionDate)` index, since every read is now filtered by account and ordered by date), and all 22,669 existing rows were backfilled onto a seeded "Utilities — Scotiabank (MXN)" account by `migration/backfill_bank_accounts.py` — a standalone step because `prisma db push` cannot add a required column to a populated table. It is idempotent and now runs inside `run_all.py` (both normal and `--sync`) ahead of `transform_bank.py`, which fails fast if the account is missing. Every read path in `bank.service.ts` is account-scoped, including `facets()` (which had no filter at all) and *both* raw-SQL rollups in `summary()`. API: `?bankAccountId=` is required on `list`/`stats`/`facets`/`summary` — **not** optional-with-an-all-accounts-default, since summing an MXN and a USD register repeats exactly the currency-collapsing mistake the billing module exists to prevent — plus a new `bank/accounts` + `bank/banks` sub-resource under a MANAGER `bank:manage-accounts` ability. Web: `/banco` gained an account picker (remembered per browser) and reads every figure in the selected account's currency, `/banco/cuentas` manages banks and accounts, and `/inicio`'s chequera card names the account it is showing instead of implying one register. An account's `currency` is immutable after creation by design — its booked movements are denominated in it. Verified against dev + browser: a second USD account showed full read/write isolation from the MXN register, whose totals were unchanged.
+    - **Customer-number recycling** — promotes the legacy `NUM id` (currently only inside `customer_legacy_refs`) into a first-class, reusable `Customer.customerNumber`, automates *finding* candidates for reuse (cancelled / 1-year-inactive), and auto-assigns the lowest free number at creation — the search is automated, the release/reuse decision stays a human action. Backfill needs care: ~140 utilities rows and all insurance-only customers have no real legacy number (synthetic `rownum_N`/`insrow_N` placeholders in `transform_customers.py`, not real `NUM id`s).
+    
+    Several open questions block parts of this (OCR provider/budget, the Seguros bank's identity, the clave-catastral-vs-predial mismatch, exact recycling triggers, and whether "recycling" should ever mean true data purge vs. archive-and-reuse-the-number) — see the spec's collected open-questions section.
+12. **Insurance features — NOT STARTED, spec written.** Full design in [`docs/INSURANCE_FEATURES_SPEC.md`](docs/INSURANCE_FEATURES_SPEC.md), the insurance half of the same 2026-07-25/26 meeting with Jorge that produced step 11:
+    - **Renewal notification emails** — a daily `@nestjs/schedule` sweep that mails the customer 30 days before expiry, 15 days before, and 7 days after, mapping onto `RenewalNotice.generation` 1/2/3 with **no schema change**. Sending is **Amazon SES** (`@aws-sdk/client-sesv2`, mirroring `StorageService`'s optional-client/degrade-don't-crash pattern) — the office already runs SES, so provider and budget are settled, not open. The letter body is the *existing* `aviso-renovacion` report (`reports.registry.ts:623-799`); `@@unique([policyId, generation])` is already-in-place idempotency, so a re-run cannot double-send. Volume ≈260 mails/month, and **815 of the 893 policyholders (91%) have an email**. Also adds the manual mark-as-sent mutation the report's own comment anticipates, so the report's permanently-zero `enviadas` total becomes real. Smallest useful piece — do first.
+    - **Liquidación batch workflow** — ~70% already built (`liquidated`/`liquidationNumber`/`liquidationDate` are wired through DTOs, list filter, stats, form and detail page); only the *batch* print-and-mark step is missing, against a live pending set of 226 policies. Adds a ramo-parameterized pending report plus `POST /policies/liquidate-batch` under a new MANAGER `policy:liquidate` ability. Parameterized by ramo, not MULT-only — legacy `TABLA LIQUIDA MF` served `MULT`, `INCENDIO` and `M EMPR` alike.
+    - **Certificate / "Solicitud Atlas"** — renders from the same `format: "letter"` machinery `aviso-renovacion` uses, then reaches customers as an extension of the step-8/9 replication (PDF generated here, pushed to MinIO, pointer replicated), **not** as a new public surface in this repo. Half-blocked: "Solicitud" has zero referent in the legacy system and normally means an *application form*, a different artifact from a certificate.
+    - **Carrier API integration (ANA Seguros + GMX)** — shape only (`CarrierConnector` + an import-review queue rather than direct `Policy` writes, matching how step 11's OCR results are routed). Carrier research done 2026-07-27: **the two carriers are one company** — both belong to **Grupo Valore** (ANA writes autos, GMX writes daños, which is exactly this database's `AUTO`/`LICENCIAS` vs `MULT`/`INCENDIO`/`M_EMPR` split), so it is one commercial relationship, not two. **ANA has a real live SOAP service** (`server.anaseguros.com.mx/ananetws/service.asmx`, ASP.NET `.asmx`) with a published operation list — catalogs, `CalculaValor`/`CalculaMSI`, `ValidaSerie`, `RecuperaCotizacion`, `Transaccion`. **GMX publishes no machine interface at all**, only human agent portals. ⚠️ **Critical mismatch:** every ANA operation serves *new-business quoting/issuance*, not "list the policies where I am agent of record" — so if the ask is inbound portfolio sync, no evidence exists that either carrier sells it. Blocked on one phone call to Grupo Valore ((55) 5480-4000) for credentials + a direction answer, not on further research. ("GDMX" in the meeting notes was a typo for `GMX` — confirmed 2026-07-27.)
+
+    **Two pre-existing defects were found while verifying this spec and should be fixed as part of the liquidación work:** (a) `policy_types` is missing its `INCENDIO` and `M_EMPR` rows and, because `policies_policyTypeId_fkey` is `ON DELETE SET NULL`, 5 `m_empr` policies silently lost their ramo — 4 of them are pending liquidación and are invisible to every ramo-filtered query; (b) the legacy settlement slots don't match what the target model assumed — `MULT`/`INCENDIO` carry two and `M EMPR` carries four, while `Policy` collapses to one, so ≤41 MULT second settlements were dropped in migration. Spec recommends moving settlement onto `PolicyPaymentInstallment` rather than adding a second slot.
+
+    **One long-standing open question is closed by this spec:** `DATGRAL.[NUM UTIL]` is authoritative for Utilities↔Seguros reconciliation and **`UTILSEG` must not be used** — its numbers resolve to unrelated people under every reading tested (name match 58/1,024 vs. 298/563 for `NUM UTIL`), and where the two sources overlap they contradict each other on 170 of 218 shared ids. This matters to step 11's customer-number recycling, which touches the same identity space.
 
 ## Status
 
@@ -139,6 +160,10 @@ Repo scaffolded at `jorgecuadros-platform/`: npm workspaces, NestJS API with a r
 
 **Portal live DB now in hand.** `utility_dbo.sql` (1.3 GB, 55 tables) and the portal codebase `my-jorgecuadros-web` (PHP/`mysqli`, Gitea repo, themed classic/modern, ~397 PHP files, core in `scripts/functions.php`) are both on disk — resolving the long-standing "`utility_dbo` schema unknown" blocker. Sync-relevant tables identified: statements/money (`utility_bills`, `accounting`, `email_alert_log`), customer/property (`home_owners`, `home_index`, `condominium`, `management`, `hoa_management`, `trust_assist`), portal-facing policy views (`fm2`/`fm3`/`fmt`, `full_coverage`, `mx_liability`, `usa_liability`), and portal write points (`peticion_gas`, PayPal payments, `notifications_settings`, `verification_codes`). A second dump, `jorgecuadros.sql` (38 MB, 11 tables — `pagos`/`pagosemail`/`PROPANO`/`TRUSTVENCE`/etc.), appears to be an older/partial export, not the portal live DB.
 
+**Step 11 is now three-quarters built.** Receipt capture, the multi-bank chequera and PDF/OCR auto-capture are all done and verified; only customer-number recycling remains unbuilt. `docs/RECEIPT_CAPTURE_SPEC.md` carries a BUILT note per section recording what shipped and, for §2, the four things real scanned statements proved the spec had wrong or unknown.
+
+**Step 12 spec written, not built.** `docs/INSURANCE_FEATURES_SPEC.md` covers the insurance half of the same meeting (renewal emails, liquidación batch, certificate + portal delivery, carrier APIs) — see Build sequencing step 12 above. Verified the same way, plus a live query of the dev DB for the counts it quotes (email coverage, pending liquidación, installment fill rates) and of the staged Parquet for the legacy settlement-slot usage. Two of the four features are much smaller than they sound: the renewal-notice table, its idempotency key and the letter body already exist, and the per-policy liquidación fields are already wired end to end.
+
 ## Decisions (locked)
 
 - **Stack:** Next.js + NestJS + Prisma + **MySQL** (locked earlier — see engine rationale above).
@@ -155,6 +180,30 @@ Repo scaffolded at `jorgecuadros-platform/`: npm workspaces, NestJS API with a r
 - **VPS provisioning:** provider (Hetzner vs DigitalOcean), size, and Tailscale + MySQL replica setup on it — an ops task, still pending. Design is settled; only the box is missing.
 - **Old external-DB credential** (hardcoded plaintext MySQL password in the old repo's `dbConnection.php`, in git history) — rotate it regardless, since it's already exposed.
 
+## Open design questions (steps 11 & 12 — need Jorge before/while building)
+
+Unlike the ops items above, these block design decisions, not just infrastructure. Full detail in each section of `docs/RECEIPT_CAPTURE_SPEC.md` (step 11) and `docs/INSURANCE_FEATURES_SPEC.md` (step 12):
+
+**Step 11 — utilities/ops side:**
+
+- ~~OCR provider/budget~~ — **CLOSED**: self-hosted Tesseract, chosen on measured accuracy against real scans, so there is no per-page cost to approve.
+- ~~Whether `PROPERTY_TAX.accountNumber` (from `DATMEX.PREDIAL`) is the same number as "Clave Catastral" (`DATMEX.CLAVE`)~~ — **CLOSED**: they are different numbers. Answered from real CESPT bills plus the staged data; the clave is now migrated separately and predial was left alone.
+- Whether the CFE figure to charge is the rounded headline/barcode amount (`$268` — what is actually paid at the window) or the exact breakdown `Total` (`$268.88`). The parser takes the barcode amount; one confirmation from Jorge would settle it.
+- The actual bank name/currency/details for the Seguros USD account, and whether any historical Seguros bank register exists to migrate. (Multi-bank support itself is **built** — this is now only the missing content: staff can open the account in `/banco/cuentas` the moment the answer arrives, and it starts empty unless a historical register turns up.)
+- The exact "1 year inactivity" / "cancelled" triggers for customer-number recycling eligibility.
+- Whether customer-number recycling should ever include true PII purge (matching the office's paper-world habit) or archive-and-reuse-the-number is sufficient — recommended default is archive-only, consistent with this project's existing never-hard-delete convention.
+
+**Step 12 — insurance side:**
+
+- Which SES region + verified sending identity/configuration set the renewal mail goes out under, and whether it reuses the existing IAM credentials or gets its own scoped `ses:SendEmail` user. (Provider and budget are *not* open — SES is settled.)
+- What to do with the 78 policyholders who have no email on file: skip silently, or produce a print worklist? Recommended: the worklist, since `aviso-renovacion` already renders exactly those letters.
+- Whether renewal notices go out in Spanish or English — `Customer` carries no language preference.
+- What "garantías" refers to — it has zero referent in the legacy data, and it blocks the liquidación batch's exclusion filter.
+- Whether policy settlement should move onto `PolicyPaymentInstallment` (recommended) or gain a second slot on `Policy`, and whether to backfill the ≤41 MULT second settlements lost in migration.
+- Whether batch liquidación warrants a new MANAGER-level `policy:liquidate` ability (recommended) or should reuse the existing STAFF-level `policy:update`.
+- **What "Solicitud Atlas" actually is** — an application form or a certificate. These are different artifacts with different data and timing; this blocks the whole certificate feature.
+- **Carrier integration direction** — outbound quote/issue (which ANA's SOAP service supports today) or inbound sync of the office's existing book (which nothing found suggests either carrier offers)? This decides whether the feature is buildable at all. Bundle with the other three carrier questions into one call to Grupo Valore ((55) 5480-4000): WSDL + credentials for the ANA service, whether a cartera/portfolio download exists for an agent's own book, whether GMX daños has any machine interface, and whether one credential spans both carriers. ("GDMX" is resolved — it was a typo for `GMX`.)
+
 ## Verification
 
 - Migration: automated row-count/sum reconciliation between `staging` and final schema per table group (see step 5 above), run as part of the migration script, not a manual spot-check.

RESUME.md

@@ -127,8 +127,14 @@ To rerun (from `migration/`, venv at `migration/.venv`):
 ```bash
 ./.venv/bin/python load_staging.py --output-dir ./output   # re-extract from Access (needs mdbtools + the source files)
 ./.venv/bin/python run_all.py --env dev                    # full transform+load; add --stage to re-extract first
+./.venv/bin/python run_all.py --env dev --sync             # additive sync: upsert legacy by provenance, keep manual rows, prune legacy empties
 ```
 
+`--sync` mode (Phase B) upserts legacy-owned rows by their provenance keys and preserves
+manual rows (`legacyId IS NULL`); every transform reuses each row's existing PK, rebuilds
+legacy-owned children by scoped delete + reinsert, and drops legacy rows gone from source.
+Verified end-to-end against dev 2026-07-24 — see §6 item 6.
+
 ## 5. Infrastructure & sync architecture (designed, not yet built)
 
 - **Internal server** — on-prem, private IP `192.168.1.xx`, no inbound internet exposure. Runs the platform + canonical MySQL (source of truth).
@@ -162,17 +168,30 @@ the reconciliation pass (done, then corrected) are all closed. See §3 and §8.
 5. **`TRASPASOS PAYPAL` is a clearing account, not a customer** — carries -7.03M MXN over
    309 movements and therefore tops the adeudo worklist. Deliberately not special-cased in
    code; needs a business decision on how to model it.
-6. **DB Operations — Phase B (additive sync) — IMPLEMENTED, verification pending.** Phase A provides
-   the admin-only `/operaciones` page + `ops` API module (ability `db:manage`, ADMIN), ingest
-   folder, backup, restore, and destructive re-import. Phase B now enables `SYNC`: `OpsService`
-   creates a safety backup and runs `run_all.py --sync`; transforms upsert legacy-owned rows by
-   provenance keys while preserving existing PKs and rows whose `legacyId IS NULL` (manual).
-   Prisma now enforces provenance uniqueness for properties, policies, transactions, vehicles,
-   and bank transactions. Sync intentionally skips prune/blob steps so manual customers and
-   document pointers are not removed. Python compilation plus API/web production builds pass;
-   still required before production use: push updated Prisma schema and run an end-to-end sync
-   against a disposable/dev DB proving stable PKs, manual-row preservation, changed-row updates,
-   and legacy-delete handling.
+6. **DB Operations — Phase B (additive sync) — VERIFIED END-TO-END against dev DB 2026-07-24.**
+   Phase A provides the admin-only `/operaciones` page + `ops` API module (ability `db:manage`,
+   ADMIN), ingest folder, backup, restore, and destructive re-import. Phase B enables `SYNC`:
+   `OpsService` creates a safety backup and runs `run_all.py --sync`; transforms upsert
+   legacy-owned rows by provenance keys while preserving existing PKs and rows whose
+   `legacyId IS NULL` (manual). Prisma enforces provenance uniqueness for properties, policies,
+   transactions, and bank transactions (the vehicle unique was **removed** — one legacy policy
+   row carries up to 3 vehicles that share a `legacyId`, so provenance is not unique per
+   vehicle; vehicles are rebuilt by scoped delete + reinsert). Sync skips blob extraction, and
+   runs a **manual-safe prune** (`prune_empty_customers.py --sync` — only prunes empties that
+   carry a legacy ref, never manually-added customers) because the customer upsert otherwise
+   re-creates every previously-pruned empty from Parquet.
+
+   **The as-written sync was broken and had never been run; a batch of bugs were fixed on
+   2026-07-24 before it passed** (fresh-uuid child FKs in policies/properties, unconditional
+   child inserts, a `zip(customers, refs)` mispairing in transform_customers, invalid vehicle
+   unique, lookup tables built with fresh uuids but never upserted, a `updatedAt=NOW()` on a
+   table with no such column, and report crashes on NULL `legacySourceTable` for manual rows).
+   Verified with `migration/` `verify_sync.py`-style harness: two consecutive `run_all.py --sync`
+   runs both exit 0 and pass 32/32 assertions (stable PKs, manual-row preservation, changed-row
+   updates, legacy-delete, no child duplication, zero FK orphans), idempotent (customers stable
+   at 1537). Schema pushed to dev, Prisma client regenerated, API build clean. Migration/web
+   changes uncommitted as of this update. Still open before production: run the same sync from
+   the `/operaciones` UI (OpsService path) and against a prod-shaped DB.
 
 ## 7. Environment notes (current macOS machine)
 
@@ -181,9 +200,12 @@ the reconciliation pass (done, then corrected) are all closed. See §3 and §8.
 - **`npm` is pnpm-aliased**, and pnpm ignores the `workspaces` field. Consequences:
   - there is **no root `node_modules/.bin`**. Binaries live per-app: `apps/api/node_modules/.bin/nest`, `apps/web/node_modules/.bin/next`.
   - Prisma CLI is run as `npx prisma@5`.
-- **Dev servers** (both must be up to use the UI):
-  - API `cd apps/api && ./node_modules/.bin/nest start --watch` → `:3001`
-  - Web `cd apps/web && ./node_modules/.bin/next dev` → `:3000`
+- **Dev servers** (both must be up to use the UI). ⚠️ **Ports come from the env files, not the
+  framework defaults** — `apps/api/.env` sets `PORT=4501` and `WEB_ORIGIN=http://localhost:4500`,
+  and `apps/web/.env.local` points at `NEXT_PUBLIC_API_ORIGIN=http://localhost:4501`. This doc
+  said `:3001`/`:3000` until 2026-07-27; that was wrong and cost a debugging detour.
+  - API `cd apps/api && ./node_modules/.bin/nest start --watch` → **`:4501`**
+  - Web `cd apps/web && ./node_modules/.bin/next dev -p 4500` → **`:4500`**
   - Dev login: `admin@jorgecuadros.local`, password from `apps/api/scripts/seed-user.mjs` (`SEED_PASSWORD` env overrides the default).
 - **Dev DB**: `192.168.4.212:3307` (cubex Swarm stack `jorgecuadros-dev-db`). Credentials in gitignored `deploy/.env.dev`. **MinIO** for documents: `192.168.4.212:9100`, bucket `jorgecuadros-documents`.
 
@@ -359,9 +381,18 @@ for what's actually next.
      insurance/servicios/fideicomiso split the migration comment implied. A
      classifier would invent data, so `categoryId` stays null and the module does
      not filter on it. Register is browsable by date/payee/amount/cheque instead.
-     (c) **Single currency (MXN).** `bank_transactions` has no currency column and
-     every `amountInWords` is spelled out in PESOS — so, unlike the customer
-     ledger, everything here is one currency and not split per-currency.
+     (c) ~~**Single currency (MXN).**~~ **SUPERSEDED 2026-07-27 by the multi-bank
+     chequera** (step 11, `docs/RECEIPT_CAPTURE_SPEC.md` §3). The office keeps
+     more than one register, so `bank_transactions` now carries a **required**
+     `bankAccountId` and every read in the module is scoped to exactly one
+     `BankAccount`, whose `currency` the movements inherit — there is still no
+     currency column on the movement itself, because a real bank account doesn't
+     mix currencies. All 22,669 migrated rows are the Utilities/Scotiabank MXN
+     account (backfilled by `migration/backfill_bank_accounts.py`, which
+     `run_all.py` runs before `transform_bank.py`), which is why every
+     `amountInWords` is still spelled out in PESOS. There is deliberately no
+     "all accounts" option: summing an MXN and a USD register would repeat the
+     currency-collapsing mistake the billing module warns against.
      (d) **The "acumulado" is net movement since the register opened, not a bank
      balance** — SCOTHIA carries no opening balance (its `ban` table holds only the
      bank's name), so the running total starts at 0 in 2013. Labelled as such in
@@ -369,9 +400,18 @@ for what's actually next.
      (e) Sign convention (from `transform_bank.py`): positive = ingreso,
      negative = egreso, exactly zero = a cancelled/void cheque (787 of 791 say
      CANCELADO/VOID) — voids are excluded from both the income and expense sides.
+     (f) **Multi-account since 2026-07-27.** `/banco` opens on an account picker
+     (the last account is remembered per browser) and reads every figure in that
+     account's currency; `/banco/cuentas` manages banks and accounts under a new
+     MANAGER `bank:manage-accounts` ability. Accounts are never deleted — the
+     `bankAccountId` FK is required, so a used account can only be *closed*
+     (`active: false`), which hides it from new captures but keeps its history
+     readable. An account's currency is immutable after creation, since its
+     booked movements are denominated in it.
    - Full pipeline reproducible in one command: `run_all.py --env <env>` runs customers →
-     properties → policies → transactions → prune → bank → blobs in order (all idempotent);
-     add `--stage` to re-extract from the Access files first. Verified end-to-end against dev.
+     properties → policies → transactions → prune → bank accounts → bank → blobs in order
+     (all idempotent); add `--stage` to re-extract from the Access files first. Verified
+     end-to-end against dev.
 
 5. **Infra** — **DONE.** Dev MySQL deployed to the cubex Swarm via the Portainer API as stack
    `jorgecuadros-dev-db` (MySQL 8.4, `192.168.4.212:3307`, node `cubex` labeled
@@ -385,15 +425,104 @@ for what's actually next.
 
 ---
 
-- **Sync implementation — DONE, validation pending.** `run_all.py --sync` performs the
-  non-destructive legacy upsert path for customers, properties, policies, transactions, and
-  bank rows. It preserves manual rows and stable legacy-owned primary keys; the admin SYNC job
-  automatically creates a pre-sync backup. Next validation: apply schema changes, then exercise
-  sync against a disposable DB with added, changed, removed, and manually-created rows.
+- **Sync implementation — DONE + VALIDATED end-to-end against dev 2026-07-24.** `run_all.py
+  --sync` performs the non-destructive legacy upsert path for customers, properties, policies,
+  transactions, and bank rows, plus a manual-safe empty-customer prune. It preserves manual rows
+  and stable legacy-owned primary keys; the admin SYNC job auto-creates a pre-sync backup. The
+  as-written code was broken and had never been run — a batch of bugs was fixed before it passed
+  (see §6 item 6). Two consecutive syncs both exit 0 and pass 32/32 assertions (added, changed,
+  removed, and manually-created rows), idempotent. Remaining: exercise the same path from the
+  `/operaciones` admin UI and against a prod-shaped DB.
 - **Plan step 9: portal sync worker** remains separate and blocked on VPS provisioning. This
   Phase B feature synchronizes Access source files into the internal platform; it does not yet
   poll `utility_dbo` inbox tables or replicate portal-facing data to a VPS.
 - **Small / open:** (a) `TRASPASOS PAYPAL` clearing account still tops the adeudo worklist
   (§6.4d) — a business modelling call, not code. (b) Credential rotation on the old repo's
-  exposed MySQL password. (c) The `/estado-cuenta` browser visual pass — `/banco` was verified
-  in-browser this session; `/estado-cuenta` still worth a look.
+  exposed MySQL password. (c) ~~The `/estado-cuenta` browser visual pass.~~ **DONE 2026-07-24** —
+  verified vs dev: Anular buttons admin-gated, voided rows struck + excluded from totals,
+  clicking Anular voids end-to-end (note: it uses a blocking `window.confirm`). Customer-detail
+  mini tx list now also strikes voided rows ("(anulado)" tag) — was the last void-UI gap.
+
+---
+
+## Statement OCR intake (`/recibos`) — DONE 2026-08-01
+
+Plan step 11 §2 (`docs/RECEIPT_CAPTURE_SPEC.md` §2). The last big utilities
+feature: staff scan the month's utility bills and the machine proposes customer
++ amount per page, instead of keying 300+ statements per company by hand. Built
+in `apps/api/src/statements/` and `apps/web/src/app/recibos/`, posting through
+step 11 §1.2's `BillingService.createBatch` seam (`source: "OCR"`, per-document
+`captureRef`) so machine and hand capture share one write path and one audit
+trail. Abilities `statement:ingest` / `statement:review`, both STAFF.
+
+**Verified end to end against the live dev API + MinIO**, not just built: real
+CFE and Telnor scans uploaded over HTTP, OCR'd, matched, confirmed against a
+check, and the resulting rows checked in MySQL — negative (charge) amounts,
+`captureSource = OCR`, concept auto-derived from the batch's service kind,
+`captureRef` linking each transaction back to its page. Re-confirming a posted
+batch is refused. All test data was removed afterwards.
+
+**Everything here was decided from 10 real scanned statements (46 pages), not
+from the sample-free spec.** Shipped-parser results on them: provider 46/46,
+account reference 43/46, amount 42/46, due date 44/46; matched against the dev
+database, **39/46 (85%) exact auto-match, 40/46 (87%) identified**. The rest are
+real review cases (one shared account number, three phones not on file, one
+clave not in the book, one page too poor to read).
+
+Findings that corrected the spec, each of which changed the build:
+
+- **The scans have no text layer at all** — they are camera images of paper, so
+  OCR is mandatory rather than a convenience, and they arrive **bundled, one
+  customer per page**.
+- **Clave catastral is not predial.** `DATMEX.clave` (934 rows, `KA903009`) is
+  what CESPT and predial bills print; `DATMEX.predial` — which
+  `PROPERTY_TAX.accountNumber` holds — has only 663 distinct values across 1135
+  rows and appears on no statement. The clave now lives on
+  `Property.cadastralKey` as the matcher's secondary key; predial was left
+  untouched. This is the question that had been blocking predial matching.
+- **Gas was recoverable after all.** The spec said no legacy gas number existed;
+  in fact 160 of 334 `DATMEX.gas` values are real account numbers (the rest are
+  `ESTACIONARIO`/`CILINDRO` descriptors). Recovered into `GAS.meterNumber`.
+- **Phone is one billed line per property** (534 / 18 / 1 across phone1/2/3), so
+  `TELEPHONE` — a new `ServiceKind` — backfills from `phone1` only.
+- **Never match on the printed name.** A CESPT receipt for account `5365218`
+  reads `ARNAIZ ROSAS ELSA AURORA`; the office's book, corroborated by the
+  clave, has `CATT, RANDY`. The name on a utility bill is the registrant, not
+  the current owner.
+
+`migration/backfill_statement_match_fields.py` closes those three data gaps on
+an existing database (idempotent, wired into `run_all.py` after
+`transform_properties.py`, which now produces them directly on a full rebuild).
+Applied to dev: 934 claves, 160 gas numbers, 534 TELEPHONE rows.
+
+Implementation notes worth keeping:
+
+- OCR is self-hosted **Tesseract** behind an `OcrProvider` interface — the
+  provider question is closed on measured accuracy, and a managed API stays a
+  one-line swap in `statements.module.ts`. `tesseract-ocr`,
+  `tesseract-ocr-data-spa` and `poppler-utils` were added to the API image; if
+  they are missing the module reports itself unavailable and only this feature
+  is disabled.
+- **Payment barcodes beat printed labels.** One CFE label OCR'd a digit too
+  many while its barcode was correct, so the barcode is the source and the label
+  the cross-check; disagreement forces review.
+- **Detect the provider by brand first, layout only as a fallback** — and never
+  interleave the two passes. A scanned CESPT header came back as `E BAJA ES
+  PAGO / EALIFORNIA`, which is why the layout fallback exists; a Telnor page
+  contains words a CFE layout rule would otherwise claim, which is why ordering
+  matters.
+- **Parse amounts by separator position.** A real Telnor bill OCR'd as
+  `$ 649,00`; stripping commas as thousands separators turns that into $64,900.
+- Two of the three layouts are line-oriented, but the CESPT "RECIBO" is a
+  **table** whose values sit under column headers — that one needs the word
+  boxes, which is why `OcrPage` carries geometry and not just text.
+- Confirming a document whose matched service had no reference **writes the
+  reference back** (only into an empty field, and only when exactly one blank
+  service of that kind is a candidate), so gas and any other cold start is a
+  one-time cost rather than a permanent queue.
+- Handwritten folder numbers on the bills (`9`, `405`) are **not** used for
+  matching — Tesseract read `405` as `205`.
+
+**Open:** whether the CFE charge should be the rounded barcode/headline figure
+(`$268`, what is paid at the window — what the parser uses today) or the exact
+breakdown total (`$268.88`). One question for Jorge.

apps/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jorgecuadros/api",
-  "version": "0.1.0",
+  "version": "1.0.2",
   "private": true,
   "scripts": {
     "build": "nest build",
@@ -11,6 +11,7 @@
     "test": "jest"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.665.0",
     "@jorgecuadros/database": "workspace:*",
     "@nestjs/common": "^10.4.4",
     "@nestjs/config": "^3.3.0",
@@ -20,7 +21,9 @@
     "argon2": "^0.41.1",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.1",
+    "exceljs": "^4.4.0",
     "express-session": "^1.18.0",
+    "pdfkit": "^0.15.1",
     "passport": "^0.7.0",
     "passport-local": "^1.0.0",
     "reflect-metadata": "^0.2.2",
@@ -31,6 +34,7 @@
     "@nestjs/testing": "^10.4.4",
     "@types/express": "^4.17.21",
     "@types/express-session": "^1.18.0",
+    "@types/pdfkit": "^0.13.5",
     "@types/jest": "^29.5.13",
     "@types/node": "^20.16.11",
     "@types/passport": "^1.0.17",

apps/api/src/app.controller.ts

@@ -6,4 +6,25 @@ export class AppController {
   health() {
     return { status: "ok" };
   }
+
+  /**
+   * What is actually running. The three values are baked into the image at
+   * build time by .gitea/workflows/build.yml (see docker/api.Dockerfile) and
+   * are the only way to confirm a deploy — or a rollback — landed: the tag you
+   * dispatched and the code inside the container can disagree if a stack was
+   * applied without pulling, or if the app stack still names an older tag.
+   *
+   * Deliberately unauthenticated, same as /health: the deploy workflow has to
+   * read it with no session, and it exposes nothing an attacker could not
+   * already infer from the repo.
+   */
+  @Get("version")
+  version() {
+    return {
+      service: "api",
+      version: process.env.APP_VERSION ?? "dev",
+      gitSha: process.env.GIT_SHA ?? "unknown",
+      buildDate: process.env.BUILD_DATE ?? "unknown",
+    };
+  }
 }

apps/api/src/app.module.ts

@@ -1,6 +1,7 @@
 import { Module } from "@nestjs/common";
 import { ConfigModule } from "@nestjs/config";
 import { PrismaModule } from "./prisma/prisma.module";
+import { StorageModule } from "./storage/storage.module";
 import { CommonModule } from "./common/common.module";
 import { UsersModule } from "./users/users.module";
 import { AuthModule } from "./auth/auth.module";
@@ -8,14 +9,17 @@ import { CustomersModule } from "./customers/customers.module";
 import { PoliciesModule } from "./policies/policies.module";
 import { PropertiesModule } from "./properties/properties.module";
 import { BillingModule } from "./billing/billing.module";
+import { StatementsModule } from "./statements/statements.module";
 import { BankModule } from "./bank/bank.module";
 import { OpsModule } from "./ops/ops.module";
+import { ReportsModule } from "./reports/reports.module";
 import { AppController } from "./app.controller";
 
 @Module({
   imports: [
     ConfigModule.forRoot({ isGlobal: true }),
     PrismaModule,
+    StorageModule,
     CommonModule,
     UsersModule,
     AuthModule,
@@ -23,8 +27,10 @@ import { AppController } from "./app.controller";
     PoliciesModule,
     PropertiesModule,
     BillingModule,
+    StatementsModule,
     BankModule,
     OpsModule,
+    ReportsModule,
   ],
   controllers: [AppController],
 })

apps/api/src/auth/abilities.ts

@@ -31,6 +31,9 @@ export type Ability =
   | "ledger:void"
   | "bank:create"
   | "bank:void"
+  | "bank:manage-accounts"
+  | "statement:ingest"
+  | "statement:review"
   | "lookup:manage"
   | "user:manage"
   | "db:manage";
@@ -50,6 +53,15 @@ export const ABILITY_MIN: Record<Ability, Role> = {
   "ledger:void": "MANAGER",
   "bank:create": "STAFF",
   "bank:void": "MANAGER",
+  // Opening or renaming a chequera is rarer and higher-stakes than posting a
+  // movement into one — a wrong account silently mixes two sets of books.
+  "bank:manage-accounts": "MANAGER",
+  // Uploading a stack of scans and reviewing what the OCR read are both
+  // "capturing a receipt" — the same trust tier as ledger:create, since
+  // confirming a statement *is* capturing it. The review step is what makes
+  // this safe at STAFF level: nothing reaches the ledger unconfirmed.
+  "statement:ingest": "STAFF",
+  "statement:review": "STAFF",
   "lookup:manage": "MANAGER",
   "user:manage": "ADMIN",
   "db:manage": "ADMIN",

apps/api/src/auth/auth.controller.ts

@@ -1,9 +1,21 @@
-import { Controller, Get, HttpCode, Post, Req, Res, UseGuards } from "@nestjs/common";
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Patch,
+  Post,
+  Req,
+  Res,
+  UseGuards,
+} from "@nestjs/common";
 import { Request, Response } from "express";
 import { LocalAuthGuard } from "./local-auth.guard";
 import { AuthenticatedGuard } from "./authenticated.guard";
 import { LoginDto } from "./login.dto";
+import { UpdatePreferencesDto } from "./update-preferences.dto";
 import { abilitiesFor, Role } from "./abilities";
+import { UsersService } from "../users/users.service";
 
 /** Attach the resolved ability map so the web can gate its UI off one payload. */
 function withAbilities(user: unknown) {
@@ -14,6 +26,8 @@ function withAbilities(user: unknown) {
 
 @Controller("auth")
 export class AuthController {
+  constructor(private readonly users: UsersService) {}
+
   // LoginDto is only used for request-shape documentation/validation here —
   // the actual credential check happens inside LocalStrategy via Passport,
   // which populates req.user before this handler runs.
@@ -30,6 +44,19 @@ export class AuthController {
     return withAbilities(req.user);
   }
 
+  /**
+   * Update the caller's own UI preferences. Deliberately not on /users/:id —
+   * that controller is ADMIN-only, and this has to work for every role. The
+   * target is always the session's own user id, never a body parameter.
+   */
+  @UseGuards(AuthenticatedGuard)
+  @Patch("preferences")
+  async updatePreferences(@Req() req: Request, @Body() dto: UpdatePreferencesDto) {
+    const id = (req.user as { id: string }).id;
+    const user = await this.users.updatePreferences(id, dto.uiScale);
+    return withAbilities(user);
+  }
+
   @Post("logout")
   @HttpCode(200)
   logout(@Req() req: Request) {

apps/api/src/auth/update-preferences.dto.ts

@@ -0,0 +1,17 @@
+import { IsNumber, Max, Min } from "class-validator";
+
+/**
+ * Self-service UI preferences — any authenticated user may set these on their
+ * own account, including VIEWER. No ability gate: it changes nothing but how
+ * the app looks to that one person.
+ *
+ * The bounds mirror MIN_UI_SCALE/MAX_UI_SCALE in apps/web/src/lib/ui-scale.ts;
+ * keep them in sync. The API clamps rather than trusting the client because
+ * this endpoint is reachable outside the UI.
+ */
+export class UpdatePreferencesDto {
+  @IsNumber()
+  @Min(0.9)
+  @Max(1.5)
+  uiScale!: number;
+}

apps/api/src/bank/bank-account.dto.ts

@@ -0,0 +1,47 @@
+import {
+  IsBoolean,
+  IsIn,
+  IsOptional,
+  IsString,
+  MinLength,
+} from "class-validator";
+
+/** Mirrors the Prisma `Currency` enum; a chequera's is fixed at creation. */
+export const BANK_CURRENCIES = ["MXN", "USD"] as const;
+export type BankAccountCurrency = (typeof BANK_CURRENCIES)[number];
+
+/** Mirrors `TransactionDomain`. A soft hint on the account, never enforced. */
+export const BANK_BUSINESS_LINES = ["UTILITY", "INSURANCE", "TRUST"] as const;
+export type BankBusinessLine = (typeof BANK_BUSINESS_LINES)[number];
+
+export class CreateBankDto {
+  @IsString() @MinLength(1) name!: string;
+  /** "MX" | "US" — free text, informational only. */
+  @IsOptional() @IsString() country?: string;
+}
+
+export class UpdateBankDto {
+  @IsOptional() @IsString() @MinLength(1) name?: string;
+  @IsOptional() @IsString() country?: string;
+}
+
+export class CreateBankAccountDto {
+  @IsString() @MinLength(1) bankId!: string;
+  @IsString() @MinLength(1) label!: string;
+  /**
+   * Immutable after creation (no field for it on the update DTO): every
+   * movement already booked into the account is denominated in it, so
+   * changing it would silently re-denominate history.
+   */
+  @IsIn(BANK_CURRENCIES) currency!: BankAccountCurrency;
+  @IsOptional() @IsIn(BANK_BUSINESS_LINES) businessLine?: BankBusinessLine;
+  @IsOptional() @IsBoolean() active?: boolean;
+}
+
+export class UpdateBankAccountDto {
+  @IsOptional() @IsString() @MinLength(1) bankId?: string;
+  @IsOptional() @IsString() @MinLength(1) label?: string;
+  @IsOptional() @IsIn(BANK_BUSINESS_LINES) businessLine?: BankBusinessLine;
+  /** Closing an account hides it from the picker; its movements stay readable. */
+  @IsOptional() @IsBoolean() active?: boolean;
+}

apps/api/src/bank/bank-movement.dto.ts

@@ -2,10 +2,14 @@ import { IsBoolean, IsNumber, IsOptional, IsString, MinLength } from "class-vali
 
 /**
  * A new bank-register movement. `amount` is signed: positive = ingreso,
- * negative = egreso (the module's sign convention). Single currency (MXN).
+ * negative = egreso (the module's sign convention). The currency is the
+ * account's, not the movement's — `bankAccountId` decides it.
  * Booked rows are never edited — a mistake is corrected by voiding + re-capture.
  */
 export class CreateBankMovementDto {
+  /** Which chequera this lands in. Required — see BankAccount in the schema. */
+  @IsString() @MinLength(1) bankAccountId!: string;
+
   @IsNumber() amount!: number;
   @IsString() @MinLength(1) transactionDate!: string;
 

apps/api/src/bank/bank.controller.ts

@@ -3,6 +3,7 @@ import {
   Controller,
   Get,
   Param,
+  Patch,
   Post,
   Query,
   Req,
@@ -20,6 +21,12 @@ import {
   BankSort,
 } from "./bank.service";
 import { CreateBankMovementDto } from "./bank-movement.dto";
+import {
+  CreateBankAccountDto,
+  CreateBankDto,
+  UpdateBankAccountDto,
+  UpdateBankDto,
+} from "./bank-account.dto";
 
 const DIRECTIONS: BankDirection[] = ["income", "expense", "void"];
 const CLEARED: BankCleared[] = ["cleared", "pending"];
@@ -54,28 +61,108 @@ export class BankController {
     return (req.user as { id: string }).id;
   }
 
+  // --- accounts -------------------------------------------------------------
+  // Declared before the parameterised routes below so `/bank/accounts` can
+  // never be swallowed by a `:id`-shaped path.
+
+  /**
+   * The account picker. Readable by any authenticated user, VIEWER included —
+   * nothing else on this page can render until an account is chosen.
+   */
+  @Get("accounts")
+  accounts() {
+    return this.bank.listAccounts();
+  }
+
+  @Get("banks")
+  banks() {
+    return this.bank.listBanks();
+  }
+
+  @Post("banks")
+  @RequireAbility("bank:manage-accounts")
+  async createBank(@Body() dto: CreateBankDto, @Req() req: Request) {
+    const row = await this.bank.createBank(dto);
+    void this.audit.log(this.actingId(req), "bank.bank.create", {
+      bankId: row.id,
+      name: row.name,
+    });
+    return row;
+  }
+
+  @Patch("banks/:id")
+  @RequireAbility("bank:manage-accounts")
+  async updateBank(
+    @Param("id") id: string,
+    @Body() dto: UpdateBankDto,
+    @Req() req: Request,
+  ) {
+    const row = await this.bank.updateBank(id, dto);
+    void this.audit.log(this.actingId(req), "bank.bank.update", { bankId: id });
+    return row;
+  }
+
+  @Post("accounts")
+  @RequireAbility("bank:manage-accounts")
+  async createAccount(
+    @Body() dto: CreateBankAccountDto,
+    @Req() req: Request,
+  ) {
+    const row = await this.bank.createAccount(dto);
+    void this.audit.log(this.actingId(req), "bank.account.create", {
+      bankAccountId: row.id,
+      label: row.label,
+      currency: row.currency,
+    });
+    return row;
+  }
+
+  @Patch("accounts/:id")
+  @RequireAbility("bank:manage-accounts")
+  async updateAccount(
+    @Param("id") id: string,
+    @Body() dto: UpdateBankAccountDto,
+    @Req() req: Request,
+  ) {
+    const row = await this.bank.updateAccount(id, dto);
+    void this.audit.log(this.actingId(req), "bank.account.update", {
+      bankAccountId: id,
+    });
+    return row;
+  }
+
+  // --- register reads (all scoped to one account) ---------------------------
+
   @Get("stats")
-  stats() {
-    return this.bank.stats();
+  async stats(@Query("bankAccountId") bankAccountId?: string) {
+    const account = await this.bank.requireAccount(bankAccountId);
+    return this.bank.stats(account.id);
   }
 
   @Get("facets")
-  facets() {
-    return this.bank.facets();
+  async facets(@Query("bankAccountId") bankAccountId?: string) {
+    const account = await this.bank.requireAccount(bankAccountId);
+    return this.bank.facets(account.id);
   }
 
   /** Year and month rollups with a running net-movement figure. */
   @Get("summary")
-  summary(@Query("year") year?: string) {
+  async summary(
+    @Query("bankAccountId") bankAccountId?: string,
+    @Query("year") year?: string,
+  ) {
+    const account = await this.bank.requireAccount(bankAccountId);
     const y = Number(year);
     return this.bank.summary(
+      account.id,
       Number.isInteger(y) && y >= 1900 && y <= 2999 ? y : undefined,
     );
   }
 
   /** The register browser. */
   @Get()
-  list(
+  async list(
+    @Query("bankAccountId") bankAccountId?: string,
     @Query("query") query?: string,
     @Query("page") page?: string,
     @Query("pageSize") pageSize?: string,
@@ -85,7 +172,9 @@ export class BankController {
     @Query("to") to?: string,
     @Query("sort") sort?: string,
   ) {
+    const account = await this.bank.requireAccount(bankAccountId);
     return this.bank.list({
+      bankAccountId: account.id,
       query,
       page: Math.max(1, Number(page) || 1),
       pageSize: Math.min(100, Math.max(1, Number(pageSize) || 25)),
@@ -105,6 +194,7 @@ export class BankController {
     const row = await this.bank.createMovement(dto);
     void this.audit.log(this.actingId(req), "bank.create", {
       bankTransactionId: row.id,
+      bankAccountId: row.bankAccountId,
       amount: dto.amount,
     });
     return row;

apps/api/src/bank/bank.service.ts

@@ -2,6 +2,12 @@ import { BadRequestException, Injectable, NotFoundException } from "@nestjs/comm
 import { Prisma } from "@jorgecuadros/database";
 import { PrismaService } from "../prisma/prisma.service";
 import { CreateBankMovementDto } from "./bank-movement.dto";
+import {
+  CreateBankAccountDto,
+  CreateBankDto,
+  UpdateBankAccountDto,
+  UpdateBankDto,
+} from "./bank-account.dto";
 
 /**
  * App-voided rows (voidedAt set) are reversed and must leave every
@@ -28,9 +34,18 @@ const NOT_VOIDED: Prisma.BankTransactionWhereInput = { voidedAt: null };
  *     expense and are excluded from both sides, the way the ~193 zero rows are
  *     in the customer ledger.
  *
- * SINGLE CURRENCY. Unlike the customer ledger there is no currency column here:
- * `bank_transactions` has none, and every `amountInWords` on the egreso side is
- * spelled out in PESOS. All figures in this module are MXN.
+ * ONE ACCOUNT AT A TIME, CURRENCY FROM THE ACCOUNT. The office now keeps more
+ * than one chequera (Utilities banks in MXN, Seguros in USD), so every read
+ * path here is scoped to exactly one `bankAccountId` — never "all accounts".
+ * There is deliberately no currency column on `bank_transactions`: a movement
+ * inherits its account's, the way a real bank account doesn't mix currencies.
+ * Callers must therefore pass an account id; an unscoped total would sum MXN
+ * and USD into a figure that never existed, the same mistake the billing
+ * module's per-currency rule exists to prevent.
+ *
+ * The 22,669 migrated rows are all SCOTHIA = the Utilities MXN account
+ * (backfilled by `migration/backfill_bank_accounts.py`), and their
+ * `amountInWords` on the egreso side is spelled out in PESOS accordingly.
  *
  * NO CATEGORY DIMENSION. `bank_transactions.categoryId` is NULL on all 22,354
  * rows and this module does not filter or group by it, because the data cannot
@@ -64,6 +79,8 @@ export type BankSort =
   | "reference";
 
 export interface BankListParams {
+  /** Which chequera to read. Required — see the module header. */
+  bankAccountId: string;
   query?: string;
   page: number;
   pageSize: number;
@@ -98,7 +115,9 @@ export class BankService {
   constructor(private readonly prisma: PrismaService) {}
 
   private where(p: BankListParams): Prisma.BankTransactionWhereInput {
-    const and: Prisma.BankTransactionWhereInput[] = [];
+    const and: Prisma.BankTransactionWhereInput[] = [
+      { bankAccountId: p.bankAccountId },
+    ];
 
     if (p.query && p.query.trim()) {
       const q = p.query.trim();
@@ -124,7 +143,9 @@ export class BankService {
       });
     }
 
-    return and.length ? { AND: and } : {};
+    // Never empty: the account clause above is always present, so no read can
+    // accidentally span every chequera.
+    return { AND: and };
   }
 
   private orderBy(
@@ -233,22 +254,25 @@ export class BankService {
     };
   }
 
-  /** Top-line figures for the bank page header. */
-  async stats() {
+  /** Top-line figures for the bank page header, for one chequera. */
+  async stats(bankAccountId: string) {
+    const account = { bankAccountId };
     const [count, bounds, pending, transferred, totals] = await Promise.all([
-      this.prisma.bankTransaction.count({ where: NOT_VOIDED }),
+      this.prisma.bankTransaction.count({
+        where: { AND: [account, NOT_VOIDED] },
+      }),
       this.prisma.bankTransaction.aggregate({
-        where: NOT_VOIDED,
+        where: { AND: [account, NOT_VOIDED] },
         _min: { transactionDate: true },
         _max: { transactionDate: true },
       }),
       this.prisma.bankTransaction.count({
-        where: { AND: [{ cleared: false }, NOT_VOIDED] },
+        where: { AND: [account, { cleared: false }, NOT_VOIDED] },
       }),
       this.prisma.bankTransaction.count({
-        where: { AND: [{ transferred: true }, NOT_VOIDED] },
+        where: { AND: [account, { transferred: true }, NOT_VOIDED] },
       }),
-      this.totalsFor({}),
+      this.totalsFor(account),
     ]);
 
     return {
@@ -261,14 +285,16 @@ export class BankService {
     };
   }
 
-  /** Year list for the period filter, newest first. */
-  async facets() {
+  /** Year list for the period filter, newest first, for one chequera. */
+  async facets(bankAccountId: string) {
+    // Tagged-template `$queryRaw`: the interpolation below is a bound
+    // parameter, not string concatenation.
     const years = await this.prisma.$queryRaw<
       { year: number; count: bigint | number | string }[]
     >`
       SELECT YEAR(transactionDate) AS year, COUNT(*) AS count
       FROM bank_transactions
-      WHERE voidedAt IS NULL
+      WHERE voidedAt IS NULL AND bankAccountId = ${bankAccountId}
       GROUP BY year
       ORDER BY year DESC
     `;
@@ -287,8 +313,12 @@ export class BankService {
    * `BAN` table holds only the bank's name), so the register starts at zero on
    * its first row in 2013 and the running figure is the net movement since
    * then. Labelled as such in the UI so it is never read as a statement balance.
+   *
+   * Both rollups take the SAME `bankAccountId`. Scoping only one of them would
+   * leave the year list and its month drill-down describing different books —
+   * wrong in a way that still looks right.
    */
-  async summary(year?: number) {
+  async summary(bankAccountId: string, year?: number) {
     const years = await this.prisma.$queryRaw<PeriodRow[]>`
       SELECT
         YEAR(transactionDate)                                AS period,
@@ -297,7 +327,7 @@ export class BankService {
         SUM(CASE WHEN amount < 0 THEN amount ELSE 0 END)     AS expense,
         SUM(amount)                                          AS net
       FROM bank_transactions
-      WHERE voidedAt IS NULL
+      WHERE voidedAt IS NULL AND bankAccountId = ${bankAccountId}
       GROUP BY period
       ORDER BY period ASC
     `;
@@ -311,7 +341,9 @@ export class BankService {
             SUM(CASE WHEN amount < 0 THEN amount ELSE 0 END)   AS expense,
             SUM(amount)                                        AS net
           FROM bank_transactions
-          WHERE YEAR(transactionDate) = ${year} AND voidedAt IS NULL
+          WHERE YEAR(transactionDate) = ${year}
+            AND voidedAt IS NULL
+            AND bankAccountId = ${bankAccountId}
           GROUP BY period
           ORDER BY period ASC
         `
@@ -365,13 +397,135 @@ export class BankService {
     };
   }
 
+  // --- accounts -------------------------------------------------------------
+
+  /**
+   * Every chequera, closed ones included — a closed account still has to be
+   * selectable to read its history, it just isn't offered for new captures.
+   */
+  async listAccounts() {
+    const rows = await this.prisma.bankAccount.findMany({
+      orderBy: [{ active: "desc" }, { label: "asc" }],
+      select: {
+        id: true,
+        label: true,
+        currency: true,
+        businessLine: true,
+        active: true,
+        bank: { select: { id: true, name: true, country: true } },
+      },
+    });
+    return rows.map((a) => ({
+      id: a.id,
+      label: a.label,
+      currency: a.currency,
+      businessLine: a.businessLine,
+      active: a.active,
+      bankId: a.bank.id,
+      bankName: a.bank.name,
+      bankCountry: a.bank.country,
+    }));
+  }
+
+  async listBanks() {
+    return this.prisma.bank.findMany({
+      orderBy: { name: "asc" },
+      select: { id: true, name: true, country: true },
+    });
+  }
+
+  /**
+   * Resolve an account id from a request, or reject. Every read route funnels
+   * through this so a bad/missing id is a 400 rather than a silently empty
+   * register that reads as "this account has no movements".
+   */
+  async requireAccount(bankAccountId: string | undefined) {
+    if (!bankAccountId || !bankAccountId.trim())
+      throw new BadRequestException("Falta la cuenta bancaria (bankAccountId)");
+    const account = await this.prisma.bankAccount.findUnique({
+      where: { id: bankAccountId },
+      select: { id: true, label: true, currency: true, active: true },
+    });
+    if (!account)
+      throw new NotFoundException(`Cuenta bancaria ${bankAccountId} no existe`);
+    return account;
+  }
+
+  async createBank(dto: CreateBankDto) {
+    return this.prisma.bank.create({
+      data: { name: dto.name.trim(), country: dto.country?.trim() || null },
+    });
+  }
+
+  async updateBank(id: string, dto: UpdateBankDto) {
+    await this.getBankOr404(id);
+    return this.prisma.bank.update({
+      where: { id },
+      data: {
+        ...(dto.name !== undefined ? { name: dto.name.trim() } : {}),
+        ...(dto.country !== undefined
+          ? { country: dto.country.trim() || null }
+          : {}),
+      },
+    });
+  }
+
+  private async getBankOr404(id: string) {
+    const bank = await this.prisma.bank.findUnique({
+      where: { id },
+      select: { id: true },
+    });
+    if (!bank) throw new NotFoundException(`Banco ${id} no existe`);
+    return bank;
+  }
+
+  async createAccount(dto: CreateBankAccountDto) {
+    await this.getBankOr404(dto.bankId);
+    return this.prisma.bankAccount.create({
+      data: {
+        bankId: dto.bankId,
+        label: dto.label.trim(),
+        currency: dto.currency,
+        businessLine: dto.businessLine ?? null,
+        active: dto.active ?? true,
+      },
+    });
+  }
+
+  /**
+   * `currency` is intentionally absent from the update DTO: the movements
+   * already booked in this account are denominated in it, so changing it would
+   * silently re-denominate history rather than convert it.
+   */
+  async updateAccount(id: string, dto: UpdateBankAccountDto) {
+    await this.requireAccount(id);
+    if (dto.bankId !== undefined) await this.getBankOr404(dto.bankId);
+    return this.prisma.bankAccount.update({
+      where: { id },
+      data: {
+        ...(dto.bankId !== undefined ? { bankId: dto.bankId } : {}),
+        ...(dto.label !== undefined ? { label: dto.label.trim() } : {}),
+        ...(dto.businessLine !== undefined
+          ? { businessLine: dto.businessLine }
+          : {}),
+        ...(dto.active !== undefined ? { active: dto.active } : {}),
+      },
+    });
+  }
+
   // --- writes (append + void) -----------------------------------------------
 
   async createMovement(dto: CreateBankMovementDto) {
     const date = new Date(dto.transactionDate);
     if (isNaN(date.getTime())) throw new BadRequestException("Fecha inválida");
+    const account = await this.requireAccount(dto.bankAccountId);
+    if (!account.active)
+      throw new BadRequestException(
+        `La cuenta "${account.label}" está cerrada; no admite movimientos nuevos.`,
+      );
     return this.prisma.bankTransaction.create({
       data: {
+        bankAccountId: account.id,
         amount: dto.amount,
         transactionDate: date,
         concept: dto.concept,

apps/api/src/billing/billing.controller.ts

@@ -1,4 +1,5 @@
 import {
+  BadRequestException,
   Body,
   Controller,
   Get,
@@ -22,7 +23,11 @@ import {
   LedgerDirection,
   MovementSort,
 } from "./billing.service";
-import { CreateMovementDto } from "./movement.dto";
+import {
+  BatchCreateDto,
+  CreateMovementDto,
+  ResolveOutstandingDto,
+} from "./movement.dto";
 
 const DOMAINS: TransactionDomain[] = ["UTILITY", "INSURANCE", "TRUST"];
 const CURRENCIES: LedgerCurrency[] = ["MXN", "USD"];
@@ -46,6 +51,11 @@ function one<T>(allowed: T[], value: string | undefined): T | undefined {
   return allowed.includes(value as T) ? (value as T) : undefined;
 }
 
+/** Tri-state query flag: "true"/"false" filter, anything else means no filter. */
+function flag(v: string | undefined): boolean | undefined {
+  return v === "true" ? true : v === "false" ? false : undefined;
+}
+
 /** A `YYYY-MM-DD` bound; anything unparseable is treated as absent. */
 function parseDate(v: string | undefined, endOfDay = false): Date | undefined {
   if (!v) return undefined;
@@ -97,6 +107,18 @@ export class BillingController {
     });
   }
 
+  /**
+   * Every movement cut against one check, with its total — the reconciliation
+   * view replacing the legacy REPORTE CHEQUE COUNT. Declared before the
+   * `customers/:id` and `:id`-shaped routes so the literal path wins.
+   */
+  @Get("by-check")
+  byCheck(@Query("checkNumber") checkNumber?: string) {
+    const n = checkNumber?.trim();
+    if (!n) throw new BadRequestException("checkNumber es obligatorio");
+    return this.billing.byCheck(n);
+  }
+
   /** One customer's full statement across both business lines. */
   @Get("customers/:id")
   statement(@Param("id") id: string) {
@@ -115,6 +137,8 @@ export class BillingController {
     @Query("typeId") typeId?: string,
     @Query("source") source?: string,
     @Query("customerId") customerId?: string,
+    @Query("outstanding") outstanding?: string,
+    @Query("checkNumber") checkNumber?: string,
     @Query("from") from?: string,
     @Query("to") to?: string,
     @Query("sort") sort?: string,
@@ -129,6 +153,8 @@ export class BillingController {
       typeId: typeId || undefined,
       source: source || undefined,
       customerId: customerId || undefined,
+      outstanding: flag(outstanding),
+      checkNumber: checkNumber?.trim() || undefined,
       from: parseDate(from),
       to: parseDate(to, true),
       sort: one(MOVEMENT_SORTS, sort) ?? "date_desc",
@@ -150,6 +176,42 @@ export class BillingController {
     return tx;
   }
 
+  /**
+   * Batch capture: many customers' receipts against one physical check.
+   * Same ability as single capture — batching is still capturing.
+   */
+  @Post("batch")
+  @RequireAbility("ledger:create")
+  async createBatch(@Body() dto: BatchCreateDto, @Req() req: Request) {
+    const result = await this.billing.createBatch(dto);
+    void this.audit.log(this.actingId(req), "ledger.batch", {
+      checkNumber: dto.checkNumber,
+      count: result.count,
+      total: result.total,
+      currency: result.currency,
+    });
+    return result;
+  }
+
+  /**
+   * Resolve an outstanding (NOPAGO) row — `ledger:create`, not `ledger:void`:
+   * resolving completes a capture, it doesn't reverse one.
+   */
+  @Post(":id/resolve-outstanding")
+  @RequireAbility("ledger:create")
+  async resolveOutstanding(
+    @Param("id") id: string,
+    @Body() dto: ResolveOutstandingDto,
+    @Req() req: Request,
+  ) {
+    const tx = await this.billing.resolveOutstanding(id, dto);
+    void this.audit.log(this.actingId(req), "ledger.resolve-outstanding", {
+      transactionId: id,
+      checkNumber: dto.checkNumber,
+    });
+    return tx;
+  }
+
   @Post(":id/void")
   @RequireAbility("ledger:void")
   async void(@Param("id") id: string, @Req() req: Request) {

apps/api/src/billing/billing.module.ts

@@ -5,5 +5,8 @@ import { BillingService } from "./billing.service";
 @Module({
   controllers: [BillingController],
   providers: [BillingService],
+  // The statements module posts confirmed OCR captures through
+  // BillingService.createBatch rather than writing Transaction rows itself.
+  exports: [BillingService],
 })
 export class BillingModule {}

apps/api/src/billing/billing.service.ts

@@ -1,7 +1,15 @@
 import { BadRequestException, Injectable, NotFoundException } from "@nestjs/common";
-import { Prisma, TransactionDomain } from "@jorgecuadros/database";
+import {
+  Prisma,
+  TransactionCaptureSource,
+  TransactionDomain,
+} from "@jorgecuadros/database";
 import { PrismaService } from "../prisma/prisma.service";
-import { CreateMovementDto } from "./movement.dto";
+import {
+  BatchCreateDto,
+  CreateMovementDto,
+  ResolveOutstandingDto,
+} from "./movement.dto";
 
 /**
  * Shared billing / statements module — plan step 6.
@@ -54,12 +62,29 @@ export interface MovementParams {
   typeId?: string;
   source?: string;
   customerId?: string;
+  /** Restrict to captured-but-unpaid rows (the legacy NOPAGO worklist). */
+  outstanding?: boolean;
+  /** Groups a capture batch: every row cut against one physical check. */
+  checkNumber?: string;
   /** Inclusive ISO date bounds on `transactionDate`. */
   from?: Date;
   to?: Date;
   sort: MovementSort;
 }
 
+/**
+ * Non-client-supplied options for a capture. Kept out of the DTO on purpose:
+ * these are set by the calling *module*, never by an HTTP body, so a client
+ * can't label its own rows as machine-captured or forge a capture ref.
+ * See `BillingService.createBatch` for the seam contract.
+ */
+export interface CaptureOptions {
+  /** Defaults to BATCH for the HTTP path; the OCR pipeline passes OCR. */
+  source?: TransactionCaptureSource;
+  /** Per-line artifact ids, positionally parallel to `dto.lines`. */
+  refs?: (string | undefined)[];
+}
+
 export interface BalanceParams {
   query?: string;
   page: number;
@@ -112,6 +137,41 @@ function dec(v: Prisma.Decimal | null | undefined): string {
  */
 const NOT_VOIDED: Prisma.TransactionWhereInput = { voidedAt: null };
 
+/**
+ * Outstanding ("NOPAGO") rows are captured but unpaid — the office recorded the
+ * bill without funds to cover it. They are excluded from every *balance*
+ * aggregate, exactly as the legacy `SALDOS ULTIMO 0` query did with its
+ * `HAVING NOPAGO = 0`: the office hasn't paid the bill, so it isn't yet owed by
+ * the customer. Resolving one (POST /billing/:id/resolve-outstanding) clears the
+ * flag and the amount starts counting.
+ *
+ * This is deliberately narrower than NOT_VOIDED. Voided rows are excluded
+ * everywhere; outstanding rows are excluded only from balances — the movement
+ * browser still totals them, because "how much water did we capture in April"
+ * means every captured row regardless of whether the check cleared.
+ */
+const NOT_OUTSTANDING: Prisma.TransactionWhereInput = { outstanding: false };
+
+/**
+ * Source tables excluded from the customer-facing statement.
+ *
+ * The legacy portal's `datosfreak` table was materialized from DATOS2 only
+ * (`objects.json:1358`), so the customer's "current balance" never saw
+ * EFECTIVO / EFECTIVO FM3 / CHEQUE FM3 / EFECTIVO_BACKUP cash receipts, nor
+ * the IVA 2015 snapshot. The unified `transactions` table has all of them, so
+ * the statement must drop them to match the legacy number the customer has
+ * been quoted for years. The staff-facing balances worklist and movement
+ * browser keep them — they're real money, just tracked separately
+ * (FM3 = visa fee stream, EFECTIVO = cash receipt stream).
+ */
+const STATEMENT_EXCLUDED_SOURCE_TABLES: readonly string[] = [
+  "EFECTIVO",
+  "EFECTIVO_BACKUP",
+  "EFECTIVO FM3",
+  "CHEQUE FM3",
+  "IVA 2015",
+];
+
 @Injectable()
 export class BillingService {
   constructor(private readonly prisma: PrismaService) {}
@@ -140,6 +200,10 @@ export class BillingService {
     if (p.typeId) and.push({ typeId: p.typeId });
     if (p.source) and.push({ legacySourceTable: p.source });
     if (p.customerId) and.push({ customerId: p.customerId });
+    if (p.outstanding !== undefined) and.push({ outstanding: p.outstanding });
+    // Exact match, not `contains`: this is the by-check reconciliation lookup,
+    // where "1234" must not drag in "51234".
+    if (p.checkNumber) and.push({ checkNumber: p.checkNumber });
     if (p.from || p.to) {
       and.push({
         transactionDate: {
@@ -196,6 +260,7 @@ export class BillingService {
           message: true,
           legacySourceTable: true,
           voidedAt: true,
+          outstanding: true,
           type: { select: { nameEn: true, nameEs: true } },
           customer: {
             select: { id: true, name: true, nameSource: true, city: true },
@@ -243,6 +308,7 @@ export class BillingService {
         source: r.legacySourceTable,
         type: r.type,
         voided: r.voidedAt != null,
+        outstanding: r.outstanding,
         customerId: r.customer.id,
         customerName: r.customer.name,
         customerNameSource: r.customer.nameSource,
@@ -336,7 +402,7 @@ export class BillingService {
         MAX(t.transactionDate)                                                     AS lastMovement
       FROM customers c
       JOIN transactions t ON t.customerId = c.id
-      WHERE t.voidedAt IS NULL ${nameFilter} ${txFilter}
+      WHERE t.voidedAt IS NULL AND t.outstanding = 0 ${nameFilter} ${txFilter}
       GROUP BY c.id, c.name, c.nameSource, c.nameMissing, c.city, c.state
       ${having}
       ${orderBy}
@@ -348,7 +414,10 @@ export class BillingService {
         SELECT c.id
         FROM customers c
         JOIN transactions t ON t.customerId = c.id
-        WHERE 1 = 1 ${nameFilter} ${txFilter}
+        -- Must match the page query's filters exactly, or the total disagrees
+        -- with the rows. (The void exclusion was missing here before the
+        -- outstanding work; a voided-only customer inflated the count.)
+        WHERE t.voidedAt IS NULL AND t.outstanding = 0 ${nameFilter} ${txFilter}
         GROUP BY c.id
         ${having}
       ) x
@@ -579,7 +648,23 @@ export class BillingService {
     }
 
     const rows = await this.prisma.transaction.findMany({
-      where: { customerId },
+      where: {
+        customerId,
+        // NULL-safe exclusion. `notIn` alone compiles to SQL `NOT IN`, and
+        // `NULL NOT IN (...)` is NULL, not true — so every app-captured row
+        // (which has no legacySourceTable) silently vanished from the
+        // statement while still showing in the movement browser. Rows the app
+        // books must appear on the customer's statement, so the null case is
+        // spelled out.
+        OR: [
+          { legacySourceTable: null },
+          {
+            legacySourceTable: {
+              notIn: STATEMENT_EXCLUDED_SOURCE_TABLES as string[],
+            },
+          },
+        ],
+      },
       orderBy: [{ transactionDate: "asc" }, { id: "asc" }],
       select: {
         id: true,
@@ -593,6 +678,7 @@ export class BillingService {
         message: true,
         legacySourceTable: true,
         voidedAt: true,
+        outstanding: true,
         type: { select: { nameEn: true, nameEs: true } },
       },
     });
@@ -601,9 +687,10 @@ export class BillingService {
     const movements = rows.map((r) => {
       const voided = r.voidedAt != null;
       const prev = running.get(r.currency) ?? new Prisma.Decimal(0);
-      // A voided row does not move the running balance — it shows struck-through
-      // with the balance unchanged from the previous live movement.
-      const next = voided ? prev : prev.plus(r.amount);
+      // Neither a voided row nor an outstanding (unpaid) one moves the running
+      // balance — both show tagged, with the balance unchanged from the previous
+      // live movement. Outstanding rows start counting once resolved.
+      const next = voided || r.outstanding ? prev : prev.plus(r.amount);
       running.set(r.currency, next);
       return {
         id: r.id,
@@ -619,6 +706,7 @@ export class BillingService {
         source: r.legacySourceTable,
         type: r.type,
         voided,
+        outstanding: r.outstanding,
         /** Balance in this row's currency after applying it. */
         balanceAfter: next.toFixed(2),
       };
@@ -652,7 +740,9 @@ export class BillingService {
     >();
 
     for (const r of rows) {
-      if (r.voidedAt != null) continue; // voided rows never enter a total
+      // Voided rows never enter a total; outstanding rows don't either until
+      // they're resolved (legacy SALDOS ULTIMO 0's `HAVING NOPAGO = 0`).
+      if (r.voidedAt != null || r.outstanding) continue;
       const c =
         perCurrency.get(r.currency) ??
         {
@@ -700,7 +790,7 @@ export class BillingService {
       { name: string; currency: string; total: Prisma.Decimal; count: number }
     >();
     for (const r of rows) {
-      if (r.voidedAt != null) continue;
+      if (r.voidedAt != null || r.outstanding) continue;
       if (!r.amount.lessThan(0)) continue;
       const name = r.type?.nameEs || r.type?.nameEn || "Sin clasificar";
       const key = `${name}|${r.currency}`;
@@ -772,10 +862,220 @@ export class BillingService {
         reference: dto.reference,
         checkNumber: dto.checkNumber,
         message: dto.message,
+        outstanding: dto.outstanding ?? false,
+        captureSource: "MANUAL",
       },
     });
   }
 
+  /**
+   * Batch capture by check — many customers' receipts against one physical
+   * check. One `$transaction`, so a bad line rejects the whole batch rather
+   * than leaving a half-captured check that reconciles against nothing.
+   *
+   * Returns the check-level total alongside the rows so the UI can show it
+   * against the physical check amount, which is the entire point of the legacy
+   * flow this replaces (`CAPTURA *` feeding `EDITA CHEQUE COUNT`).
+   *
+   * ── Integration seam for OCR auto-capture (RECEIPT_CAPTURE_SPEC §2) ────────
+   * This method is the SINGLE write path for multi-row capture, and the OCR
+   * pipeline is required to post through it rather than writing `Transaction`
+   * rows itself — one validation path, one audit trail. Three guarantees exist
+   * for that caller specifically, and must not be broken:
+   *
+   *   1. `items[i]` corresponds to `dto.lines[i]`. Prisma's array
+   *      `$transaction` preserves order, so the caller can zip the result back
+   *      onto its own records — which is how `StatementDocument.postedTransactionId`
+   *      gets set after a confirmed batch posts.
+   *   2. `opts.refs[i]` stamps `captureRef` on row `i` (a `StatementDocument.id`).
+   *      Re-posting a ref that already has a live row is rejected, so a
+   *      double-clicked "confirm" or a retried job cannot double-charge a
+   *      customer. Voided rows don't block a re-post — a corrected statement
+   *      must be re-postable after its bad row is voided.
+   *   3. `opts.source` records the capture path; it is NOT accepted over HTTP,
+   *      so a client cannot label its hand-keyed rows as machine-captured.
+   *
+   * Everything the OCR module adds on top (batches, per-document status, the
+   * review queue) lives in its own module; nothing about it needs to change
+   * this signature.
+   */
+  async createBatch(dto: BatchCreateDto, opts: CaptureOptions = {}) {
+    const date = new Date(dto.transactionDate);
+    if (isNaN(date.getTime())) throw new BadRequestException("Fecha inválida");
+
+    // Validate every customer up front, in one query — a per-line lookup inside
+    // the transaction would be N round-trips and would fail halfway through.
+    const ids = [...new Set(dto.lines.map((l) => l.customerId))];
+    const found = await this.prisma.customer.findMany({
+      where: { id: { in: ids } },
+      select: { id: true },
+    });
+    if (found.length !== ids.length) {
+      const known = new Set(found.map((c) => c.id));
+      const missing = ids.filter((id) => !known.has(id));
+      throw new BadRequestException(
+        `Cliente(s) no encontrado(s): ${missing.join(", ")}`,
+      );
+    }
+
+    // Duplicate-post guard (seam guarantee 2). Only live rows block: a voided
+    // row means the earlier post was reversed, so the corrected statement must
+    // be allowed through.
+    const refs = (opts.refs ?? []).filter((r): r is string => !!r);
+    if (refs.length) {
+      const clash = await this.prisma.transaction.findMany({
+        where: { captureRef: { in: refs }, voidedAt: null },
+        select: { captureRef: true },
+      });
+      if (clash.length) {
+        const dupes = [...new Set(clash.map((c) => c.captureRef))];
+        throw new BadRequestException(
+          `Ya existen movimientos para: ${dupes.join(", ")}`,
+        );
+      }
+    }
+
+    const currency = dto.currency ?? "MXN";
+    const source = opts.source ?? "BATCH";
+    const created = await this.prisma.$transaction(
+      dto.lines.map((line, i) =>
+        this.prisma.transaction.create({
+          data: {
+            customerId: line.customerId,
+            domain: dto.domain,
+            amount: line.amount,
+            transactionDate: date,
+            currency,
+            typeId: dto.typeId,
+            checkNumber: dto.checkNumber,
+            period: line.period,
+            reference: line.reference,
+            message: line.message,
+            outstanding: line.outstanding ?? false,
+            captureSource: source,
+            captureRef: opts.refs?.[i],
+          },
+        }),
+      ),
+    );
+
+    // Outstanding lines are captured but unfunded, so they don't belong in the
+    // figure staff reconcile against the physical check.
+    const total = created.reduce(
+      (sum, t) => (t.outstanding ? sum : sum.plus(t.amount)),
+      new Prisma.Decimal(0),
+    );
+
+    return {
+      /** Parallel to `dto.lines` — see seam guarantee 1. */
+      items: created,
+      checkNumber: dto.checkNumber,
+      currency,
+      source,
+      count: created.length,
+      outstandingCount: created.filter((t) => t.outstanding).length,
+      total: total.toFixed(2),
+    };
+  }
+
+  /**
+   * Resolve an outstanding row: the check was finally cut. Takes the resolution
+   * date and check number and clears the flag, so the amount starts counting
+   * toward the balance. Legacy: "se actualiza registro con fecha del día y el
+   * cheque a pagar y quitas outstanding".
+   */
+  async resolveOutstanding(id: string, dto: ResolveOutstandingDto) {
+    const tx = await this.prisma.transaction.findUnique({
+      where: { id },
+      select: { id: true, voidedAt: true, outstanding: true },
+    });
+    if (!tx) throw new NotFoundException(`Transaction ${id} not found`);
+    if (tx.voidedAt) {
+      throw new BadRequestException("El movimiento está anulado");
+    }
+    if (!tx.outstanding) {
+      throw new BadRequestException("El movimiento no está pendiente de pago");
+    }
+    const date = new Date(dto.resolvedDate);
+    if (isNaN(date.getTime())) throw new BadRequestException("Fecha inválida");
+
+    return this.prisma.transaction.update({
+      where: { id },
+      data: {
+        outstanding: false,
+        checkNumber: dto.checkNumber,
+        transactionDate: date,
+      },
+    });
+  }
+
+  /**
+   * Every live movement cut against one check, plus its total — the
+   * reconciliation view replacing `EDITA CHEQUE ALF/COUNT/NUM` and
+   * `REPORTE POR CHEQUE`. Voided rows are dropped entirely (they reconcile
+   * against nothing); outstanding rows are listed but excluded from the total,
+   * since the check didn't fund them.
+   */
+  async byCheck(checkNumber: string) {
+    const rows = await this.prisma.transaction.findMany({
+      where: { checkNumber, voidedAt: null },
+      orderBy: [{ transactionDate: "asc" }, { id: "asc" }],
+      select: {
+        id: true,
+        transactionDate: true,
+        domain: true,
+        amount: true,
+        currency: true,
+        reference: true,
+        period: true,
+        message: true,
+        outstanding: true,
+        type: { select: { nameEn: true, nameEs: true } },
+        customer: { select: { id: true, name: true, nameSource: true } },
+      },
+    });
+
+    // Per currency: a check is one currency in practice, but the ledger has
+    // both and this module never sums across them.
+    const totals = new Map<string, { currency: string; total: Prisma.Decimal; count: number }>();
+    for (const r of rows) {
+      if (r.outstanding) continue;
+      const e =
+        totals.get(r.currency) ??
+        { currency: r.currency, total: new Prisma.Decimal(0), count: 0 };
+      e.total = e.total.plus(r.amount);
+      e.count += 1;
+      totals.set(r.currency, e);
+    }
+
+    return {
+      checkNumber,
+      items: rows.map((r) => ({
+        id: r.id,
+        transactionDate: r.transactionDate,
+        domain: r.domain,
+        amount: r.amount,
+        currency: r.currency,
+        direction: r.amount.lessThan(0) ? "charge" : "credit",
+        reference: r.reference,
+        period: r.period,
+        message: r.message,
+        outstanding: r.outstanding,
+        type: r.type,
+        customerId: r.customer.id,
+        customerName: r.customer.name,
+        customerNameSource: r.customer.nameSource,
+      })),
+      count: rows.length,
+      outstandingCount: rows.filter((r) => r.outstanding).length,
+      totals: [...totals.values()].map((t) => ({
+        currency: t.currency,
+        total: t.total.toFixed(2),
+        count: t.count,
+      })),
+    };
+  }
+
   /** Reverse a movement by marking it voided; it stops counting toward totals. */
   async voidMovement(id: string, userId: string) {
     const tx = await this.prisma.transaction.findUnique({

apps/api/src/billing/movement.dto.ts

@@ -1,10 +1,16 @@
 import {
+  ArrayMaxSize,
+  ArrayMinSize,
+  IsArray,
+  IsBoolean,
   IsEnum,
   IsNumber,
   IsOptional,
   IsString,
   MinLength,
+  ValidateNested,
 } from "class-validator";
+import { Type } from "class-transformer";
 import { Currency, TransactionDomain } from "@jorgecuadros/database";
 
 /**
@@ -24,4 +30,56 @@ export class CreateMovementDto {
   @IsOptional() @IsString() reference?: string;
   @IsOptional() @IsString() checkNumber?: string;
   @IsOptional() @IsString() message?: string;
+  /**
+   * Legacy "NOPAGO": the bill was captured but not actually paid (no funds).
+   * The row posts normally and stays visible, but is kept out of every balance
+   * aggregate until resolved — see BillingService's NOT_OUTSTANDING.
+   */
+  @IsOptional() @IsBoolean() outstanding?: boolean;
+}
+
+/**
+ * Resolving an outstanding row: the check finally got cut, so the movement
+ * takes the resolution date and check number and starts counting toward the
+ * balance. Legacy behavior: "se actualiza registro con fecha del día y el
+ * cheque a pagar y quitas outstanding".
+ */
+export class ResolveOutstandingDto {
+  @IsString() @MinLength(1) checkNumber!: string;
+  @IsString() @MinLength(1) resolvedDate!: string;
+}
+
+/** One customer's line within a batch; check-level fields live on the parent. */
+export class BatchLineDto {
+  @IsString() @MinLength(1) customerId!: string;
+  @IsNumber() amount!: number;
+
+  @IsOptional() @IsString() reference?: string;
+  @IsOptional() @IsString() period?: string;
+  @IsOptional() @IsString() message?: string;
+  @IsOptional() @IsBoolean() outstanding?: boolean;
+}
+
+/**
+ * Batch capture by check — the legacy "Editor" flow: key many customers'
+ * receipts against one check, then reconcile the captured total against the
+ * physical check. Deliberately NOT a persisted batch entity: `checkNumber` is
+ * already a column, and grouping by it answers every legacy by-check query.
+ */
+export class BatchCreateDto {
+  @IsEnum(TransactionDomain) domain!: TransactionDomain;
+  @IsString() @MinLength(1) transactionDate!: string;
+  @IsString() @MinLength(1) checkNumber!: string;
+
+  @IsOptional() @IsEnum(Currency) currency?: Currency;
+  @IsOptional() @IsString() typeId?: string;
+
+  // Capped so one request can't open a transaction over an unbounded row set;
+  // a physical check batch is tens of lines, not thousands.
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(500)
+  @ValidateNested({ each: true })
+  @Type(() => BatchLineDto)
+  lines!: BatchLineDto[];
 }

apps/api/src/main.ts

@@ -25,6 +25,26 @@ async function bootstrap() {
     throw new Error("SESSION_SECRET must be set (see .env.example)");
   }
 
+  // Whether the session cookie carries the Secure flag. This CANNOT simply
+  // follow NODE_ENV: express-session silently declines to send a Secure cookie
+  // over a plain-HTTP connection, so a production image served over http://ial
+  // issues no cookie at all. Login then returns 200 with a user, no session is
+  // established, every later request 403s, and the UI loops back to /login —
+  // which is exactly what happened on the first galactus deploy.
+  //
+  // Leave it ON wherever the app is reached over TLS. Turn it OFF only for a
+  // deployment that is HTTP but reached over an already-encrypted transport
+  // (the galactus install is Tailscale-only, so WireGuard encrypts the wire).
+  // Behind a TLS-terminating proxy, set trust proxy instead of turning this off.
+  // An EMPTY value counts as unset, not as "false". Compose interpolation turns
+  // an absent `${SESSION_COOKIE_SECURE:-}` into the empty string, so testing
+  // `!== undefined` here would silently drop the Secure flag on any deployment
+  // that merely passes the variable through without setting it.
+  const cookieSecureRaw = process.env.SESSION_COOKIE_SECURE;
+  const cookieSecure = cookieSecureRaw
+    ? cookieSecureRaw === "true"
+    : process.env.NODE_ENV === "production";
+
   app.use(
     session({
       secret: sessionSecret,
@@ -32,7 +52,7 @@ async function bootstrap() {
       saveUninitialized: false,
       cookie: {
         httpOnly: true,
-        secure: process.env.NODE_ENV === "production",
+        secure: cookieSecure,
         maxAge: 1000 * 60 * 60 * 8, // 8-hour session, matches a staff workday
       },
     })

apps/api/src/ops/ops.controller.ts

@@ -44,7 +44,7 @@ export class OpsController {
 
   @Post("ingest/:name")
   @UseInterceptors(
-    FileInterceptor("file", { limits: { fileSize: 500 * 1024 * 1024 } }),
+    FileInterceptor("file", { limits: { fileSize: 2 * 1024 * 1024 * 1024 } }),
   )
   async uploadIngest(
     @Param("name") name: string,

apps/api/src/ops/ops.service.ts

@@ -31,6 +31,14 @@ export const INGEST_FILES = [
 ] as const;
 export type IngestName = (typeof INGEST_FILES)[number];
 
+/**
+ * Prefix for every command containing a pipe. Without it the exit status of
+ * `mysqldump | gzip` is gzip's, so a dump that failed immediately still looks
+ * like a successful job. Both Alpine's busybox ash (the API image) and macOS
+ * `sh` (dev) support it; POSIX does not require it, so `sh -c` is the contract.
+ */
+const PIPEFAIL = "set -o pipefail; ";
+
 interface MysqlConn {
   host: string;
   port: string;
@@ -43,8 +51,11 @@ interface MysqlConn {
 export class OpsService implements OnModuleInit {
   private readonly logger = new Logger(OpsService.name);
 
+  // Resolve from this source file so it works regardless of process.cwd()
+  // (the API runs from apps/api/, but the Python ETL lives at repo-root migration/).
   private readonly migrationDir =
-    process.env.MIGRATION_DIR ?? path.resolve(process.cwd(), "migration");
+    process.env.MIGRATION_DIR ??
+    path.resolve(__dirname, "..", "..", "..", "..", "migration");
   private readonly ingestDir =
     process.env.INGEST_DIR ?? path.join(this.migrationDir, "ingest");
   private readonly backupDir =
@@ -172,7 +183,7 @@ export class OpsService implements OnModuleInit {
       );
     }
 
-    const conn = this.parseDbUrl();
+    const conn = this.opsConn();
     const { cmd, resolvedParams } = await this.buildCommand(kind, params, conn);
 
     const job = await this.prisma.opsJob.create({
@@ -204,6 +215,37 @@ export class OpsService implements OnModuleInit {
     };
   }
 
+  /**
+   * The credentials mysqldump/mysql run as — deliberately NOT the application
+   * user. `--single-transaction` issues FLUSH TABLES, which needs the global
+   * RELOAD privilege, and the app user is granted only `ALL ON jorgecuadros.*`
+   * plus `USAGE ON *.*`; `--skip-lock-tables` does not avoid it. A restore of a
+   * dump taken before --set-gtid-purged=OFF likewise needs SUPER to replay its
+   * SET @@GLOBAL.GTID_PURGED. So an admin credential is supplied out of band
+   * rather than elevating the runtime user for the sake of one admin screen —
+   * the same choice deploy/scripts/pre-migrate-backup.mjs makes.
+   *
+   * Host, port and database always come from DATABASE_URL: the ops user is a
+   * different login on the SAME server, never a way to point at another one.
+   *
+   * With the vars unset this falls back to the DATABASE_URL credentials, which
+   * is what local development wants — a dev MySQL grants the app user far more.
+   */
+  private opsConn(): MysqlConn {
+    const conn = this.parseDbUrl();
+    const user = process.env.OPS_DB_ADMIN_USER;
+    const password = process.env.OPS_DB_ADMIN_PASSWORD;
+    if (!user || !password) {
+      this.logger.warn(
+        "OPS_DB_ADMIN_USER/OPS_DB_ADMIN_PASSWORD no configuradas; " +
+          `usando el usuario de la aplicación (${conn.user}) para mysqldump. ` +
+          "En producción esto falla por falta del privilegio RELOAD.",
+      );
+      return conn;
+    }
+    return { ...conn, user, password };
+  }
+
   /** mysql/mysqldump connection flags. The password goes through MYSQL_PWD in
    *  the child env, never on the command line (which would leak via `ps`). */
   private connFlags(c: MysqlConn): string {
@@ -214,6 +256,37 @@ export class OpsService implements OnModuleInit {
     return new Date().toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
   }
 
+  /**
+   * One hardened mysqldump, shared by BACKUP and by the safety backups SYNC and
+   * REIMPORT take first. Kept byte-for-byte in spirit with the dump in
+   * deploy/scripts/pre-migrate-backup.mjs — the two write into the same volume
+   * and both are listed as restore points by this same screen.
+   *
+   * --set-gtid-purged=OFF: the production server is the replication SOURCE with
+   * GTID on, so without it every dump embeds SET @@GLOBAL.GTID_PURGED and is
+   * unrestorable onto the very server it came from.
+   *
+   * The table-count assertion is not belt-and-braces: `gzip -t` passes on the
+   * ~372-byte output of a mysqldump that died on its first statement, so a
+   * failed dump would otherwise be recorded as a successful backup. (`set -o
+   * pipefail` is set by the caller for the same reason — without it the exit
+   * status of the pipeline is gzip's, and gzip succeeded.)
+   *
+   * A failed attempt deletes its own output, so a truncated file never appears
+   * in the restore list looking like an ordinary restore point.
+   */
+  private dumpCommand(flags: string, db: string, out: string): string {
+    return (
+      `( mysqldump ${flags} --single-transaction --routines --triggers ` +
+      `--no-tablespaces --set-gtid-purged=OFF ${db} | gzip -c > ${out} && ` +
+      `gzip -t ${out} && ` +
+      `TABLAS=$(gunzip -c ${out} | grep -c 'CREATE TABLE') && ` +
+      `echo "tablas capturadas: $TABLAS" && ` +
+      `[ "$TABLAS" -ge 1 ] ) || ` +
+      `{ rm -f ${out}; echo 'respaldo incompleto eliminado'; exit 1; }`
+    );
+  }
+
   private async buildCommand(
     kind: OpsJobKind,
     params: Record<string, unknown>,
@@ -226,7 +299,7 @@ export class OpsService implements OnModuleInit {
       const file = `backup-${this.migrationEnv}-${this.timestamp()}.sql.gz`;
       const out = shq(path.join(this.backupDir, file));
       return {
-        cmd: `mysqldump ${flags} --single-transaction --routines --triggers --no-tablespaces ${db} | gzip -c > ${out}`,
+        cmd: `${PIPEFAIL}${this.dumpCommand(flags, db, out)}`,
         resolvedParams: { file },
       };
     }
@@ -238,7 +311,10 @@ export class OpsService implements OnModuleInit {
         throw new NotFoundException(`Respaldo no encontrado: ${name}`);
       });
       return {
-        cmd: `gunzip -c ${shq(full)} | mysql ${flags} ${db}`,
+        // pipefail matters here too: a corrupt archive makes gunzip fail while
+        // mysql, fed a truncated stream, can still exit 0 — a restore that
+        // reported success having replayed only part of the dump.
+        cmd: `${PIPEFAIL}gunzip -c ${shq(full)} | mysql ${flags} ${db}`,
         resolvedParams: { file: name },
       };
     }
@@ -249,8 +325,8 @@ export class OpsService implements OnModuleInit {
       const py = await this.pythonBin();
       const runAll = shq(path.join(this.migrationDir, "run_all.py"));
       const cmd =
-        `echo '== Respaldo de seguridad previo ==' && ` +
-        `mysqldump ${flags} --single-transaction --routines --triggers --no-tablespaces ${db} | gzip -c > ${out} && ` +
+        `${PIPEFAIL}echo '== Respaldo de seguridad previo ==' && ` +
+        `${this.dumpCommand(flags, db, out)} && ` +
         `echo '== Sincronización aditiva desde carpeta de ingesta ==' && ` +
         `${shq(py)} ${runAll} --env ${shq(this.migrationEnv)} --sync`;
       return { cmd, resolvedParams: { safetyBackup: file } };
@@ -263,8 +339,8 @@ export class OpsService implements OnModuleInit {
       const py = await this.pythonBin();
       const runAll = shq(path.join(this.migrationDir, "run_all.py"));
       const cmd =
-        `echo '== Respaldo de seguridad previo ==' && ` +
-        `mysqldump ${flags} --single-transaction --routines --triggers --no-tablespaces ${db} | gzip -c > ${out} && ` +
+        `${PIPEFAIL}echo '== Respaldo de seguridad previo ==' && ` +
+        `${this.dumpCommand(flags, db, out)} && ` +
         `echo '== Reimportación desde carpeta de ingesta ==' && ` +
         `${shq(py)} ${runAll} --env ${shq(this.migrationEnv)} --stage`;
       return { cmd, resolvedParams: { safetyBackup: file } };
@@ -284,6 +360,15 @@ export class OpsService implements OnModuleInit {
     }
   }
 
+  /**
+   * `password` is the ops credential from opsConn(), exported as MYSQL_PWD so it
+   * never reaches argv (which `ps` exposes to every process on the host).
+   *
+   * It does not leak into the Python ETL that SYNC and REIMPORT go on to run:
+   * migration/dbenv.py connects with pymysql using the credentials inside
+   * DATABASE_URL and never consults MYSQL_PWD. The ETL keeps running as the
+   * application user, which is what it should be doing.
+   */
   private run(jobId: string, cmd: string, password: string): void {
     const child = spawn("sh", ["-c", cmd], {
       cwd: this.migrationDir,

apps/api/src/policies/policies.controller.ts

@@ -8,9 +8,15 @@ import {
   Post,
   Query,
   Req,
+  Res,
+  StreamableFile,
+  UploadedFile,
   UseGuards,
+  UseInterceptors,
 } from "@nestjs/common";
-import { Request } from "express";
+import { FileInterceptor } from "@nestjs/platform-express";
+import { Request, Response } from "express";
+import { downloadName, type UploadedFileLike } from "../storage/upload-file";
 import { AuthenticatedGuard } from "../auth/authenticated.guard";
 import { AbilityGuard } from "../auth/ability.guard";
 import { RequireAbility } from "../auth/require-ability.decorator";
@@ -240,4 +246,40 @@ export class PoliciesController {
   removeClaim(@Param("id") id: string, @Param("childId") childId: string) {
     return this.policies.removeClaim(id, childId);
   }
+
+  // --- documents ------------------------------------------------------------
+
+  @Post(":id/documents")
+  @RequireAbility("policy:update")
+  @UseInterceptors(
+    FileInterceptor("file", { limits: { fileSize: 50 * 1024 * 1024 } }),
+  )
+  addDocument(
+    @Param("id") id: string,
+    @UploadedFile() file: UploadedFileLike | undefined,
+    @Query("type") type: string | undefined,
+  ) {
+    if (!file) throw new Error("No se recibió ningún archivo.");
+    return this.policies.addDocument(id, file, type);
+  }
+
+  @Get(":id/documents/:childId/download")
+  async downloadDocument(
+    @Param("id") id: string,
+    @Param("childId") childId: string,
+    @Res({ passthrough: true }) res: Response,
+  ): Promise<StreamableFile> {
+    const { row, stream, contentType } = await this.policies.getDocument(id, childId);
+    res.set({
+      "Content-Type": contentType ?? "application/octet-stream",
+      "Content-Disposition": `attachment; filename="${downloadName(row.storageKey, row.documentType)}"`,
+    });
+    return new StreamableFile(stream);
+  }
+
+  @Delete(":id/documents/:childId")
+  @RequireAbility("policy:update")
+  removeDocument(@Param("id") id: string, @Param("childId") childId: string) {
+    return this.policies.removeDocument(id, childId);
+  }
 }

apps/api/src/policies/policies.service.ts

@@ -1,6 +1,9 @@
 import { Injectable, NotFoundException } from "@nestjs/common";
+import { randomUUID } from "node:crypto";
 import { Prisma } from "@jorgecuadros/database";
 import { PrismaService } from "../prisma/prisma.service";
+import { StorageService } from "../storage/storage.service";
+import { extForUpload, type UploadedFileLike } from "../storage/upload-file";
 import { toDate } from "../common/coerce";
 import { CreatePolicyDto, UpdatePolicyDto } from "./policy.dto";
 import {
@@ -77,7 +80,10 @@ function daysUntil(policyTo: Date | null, from: Date): number | null {
 
 @Injectable()
 export class PoliciesService {
-  constructor(private readonly prisma: PrismaService) {}
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly storage: StorageService,
+  ) {}
 
   private statusWhere(
     status: PolicyStatus | undefined,
@@ -479,6 +485,47 @@ export class PoliciesService {
     };
   }
 
+  // --- documents ------------------------------------------------------------
+  // Blob in object storage under `policy/<policyId>/…`; row is the pointer.
+
+  async addDocument(
+    policyId: string,
+    file: UploadedFileLike,
+    documentType?: string,
+  ) {
+    await this.ensurePolicy(policyId);
+    const key = `policy/${policyId}/${randomUUID()}${extForUpload(file)}`;
+    await this.storage.put(key, file.buffer, file.mimetype);
+    return this.prisma.policyDocument.create({
+      data: {
+        policyId,
+        documentType: documentType?.trim() || "DOCUMENT",
+        storageKey: key,
+      },
+    });
+  }
+
+  async getDocument(policyId: string, id: string) {
+    const row = await this.prisma.policyDocument.findFirst({
+      where: { id, policyId },
+    });
+    if (!row) throw new NotFoundException(`Document ${id} not found on policy ${policyId}`);
+    const blob = await this.storage.getStream(row.storageKey);
+    return { row, ...blob };
+  }
+
+  async removeDocument(policyId: string, id: string) {
+    await this.ensurePolicy(policyId);
+    const row = await this.prisma.policyDocument.findFirst({
+      where: { id, policyId },
+      select: { id: true, storageKey: true },
+    });
+    if (!row) throw new NotFoundException(`Document ${id} not found on policy ${policyId}`);
+    const deleted = await this.prisma.policyDocument.delete({ where: { id } });
+    await this.storage.delete(row.storageKey);
+    return deleted;
+  }
+
   // --- lookups (providers / policy types / adjusters) -----------------------
 
   listLookups() {

apps/api/src/properties/properties.controller.ts

@@ -9,10 +9,16 @@ import {
   Put,
   Query,
   Req,
+  Res,
+  StreamableFile,
+  UploadedFile,
   UseGuards,
+  UseInterceptors,
 } from "@nestjs/common";
+import { FileInterceptor } from "@nestjs/platform-express";
 import { ServiceKind } from "@jorgecuadros/database";
-import { Request } from "express";
+import { Request, Response } from "express";
+import { downloadName, type UploadedFileLike } from "../storage/upload-file";
 import { AuthenticatedGuard } from "../auth/authenticated.guard";
 import { AbilityGuard } from "../auth/ability.guard";
 import { RequireAbility } from "../auth/require-ability.decorator";
@@ -196,7 +202,35 @@ export class PropertiesController {
     return this.properties.removeTrust(id);
   }
 
-  // --- documents (remove pointer only) --------------------------------------
+  // --- documents ------------------------------------------------------------
+
+  @Post(":id/documents")
+  @RequireAbility("property:update")
+  @UseInterceptors(
+    FileInterceptor("file", { limits: { fileSize: 50 * 1024 * 1024 } }),
+  )
+  addDocument(
+    @Param("id") id: string,
+    @UploadedFile() file: UploadedFileLike | undefined,
+    @Query("type") type: string | undefined,
+  ) {
+    if (!file) throw new Error("No se recibió ningún archivo.");
+    return this.properties.addDocument(id, file, type);
+  }
+
+  @Get(":id/documents/:childId/download")
+  async downloadDocument(
+    @Param("id") id: string,
+    @Param("childId") childId: string,
+    @Res({ passthrough: true }) res: Response,
+  ): Promise<StreamableFile> {
+    const { row, stream, contentType } = await this.properties.getDocument(id, childId);
+    res.set({
+      "Content-Type": contentType ?? "application/octet-stream",
+      "Content-Disposition": `attachment; filename="${downloadName(row.storageKey, row.documentType)}"`,
+    });
+    return new StreamableFile(stream);
+  }
 
   @Delete(":id/documents/:childId")
   @RequireAbility("property:update")

apps/api/src/properties/properties.service.ts

@@ -1,6 +1,9 @@
 import { Injectable, NotFoundException } from "@nestjs/common";
+import { randomUUID } from "node:crypto";
 import { Prisma, ServiceKind } from "@jorgecuadros/database";
 import { PrismaService } from "../prisma/prisma.service";
+import { StorageService } from "../storage/storage.service";
+import { extForUpload } from "../storage/upload-file";
 import { toDate } from "../common/coerce";
 import {
   CreatePropertyDto,
@@ -83,7 +86,10 @@ function daysUntil(dueDate: Date | null | undefined, from: Date): number | null
 
 @Injectable()
 export class PropertiesService {
-  constructor(private readonly prisma: PrismaService) {}
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly storage: StorageService,
+  ) {}
 
   private trustWhere(
     trust: TrustFilter | undefined,
@@ -543,16 +549,45 @@ export class PropertiesService {
   }
 
   // --- documents ------------------------------------------------------------
-  // Removing a pointer row only; uploading files needs the object-storage
-  // client wired into the API (today only the migration writes to MinIO).
+  // The blob lives in object storage (MinIO); the row is just the pointer. Keys
+  // stay under the `service/<propertyId>/…` prefix the migration established.
+
+  async addDocument(
+    propertyId: string,
+    file: { buffer: Buffer; originalname?: string; mimetype?: string },
+    documentType?: string,
+  ) {
+    await this.ensureProperty(propertyId);
+    const ext = extForUpload(file);
+    const key = `service/${propertyId}/${randomUUID()}${ext}`;
+    await this.storage.put(key, file.buffer, file.mimetype);
+    return this.prisma.serviceDocument.create({
+      data: {
+        propertyId,
+        documentType: documentType?.trim() || "DOCUMENT",
+        storageKey: key,
+      },
+    });
+  }
+
+  async getDocument(propertyId: string, id: string) {
+    const row = await this.prisma.serviceDocument.findFirst({
+      where: { id, propertyId },
+    });
+    if (!row) throw new NotFoundException(`Document ${id} not found on property ${propertyId}`);
+    const blob = await this.storage.getStream(row.storageKey);
+    return { row, ...blob };
+  }
 
   async removeDocument(propertyId: string, id: string) {
     await this.ensureProperty(propertyId);
     const row = await this.prisma.serviceDocument.findFirst({
       where: { id, propertyId },
-      select: { id: true },
+      select: { id: true, storageKey: true },
     });
     if (!row) throw new NotFoundException(`Document ${id} not found on property ${propertyId}`);
-    return this.prisma.serviceDocument.delete({ where: { id } });
+    const deleted = await this.prisma.serviceDocument.delete({ where: { id } });
+    await this.storage.delete(row.storageKey);
+    return deleted;
   }
 }

apps/api/src/reports/company.ts

@@ -0,0 +1,103 @@
+/**
+ * Company info used on every report header (PDF + print). Read from
+ * the environment so the office can edit it without a code change —
+ * the .env.example file lists the keys; defaults below are placeholders
+ * the office should override for production.
+ *
+ * Single source of truth: the API renders the header. The web header
+ * (login + AppShell) still reads the static "Jorge Cuadros & Asociados"
+ * strings for now — those are visual brand, the API's COMPANY_INFO
+ * block is the legal/locator block on printed documents.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface CompanyInfo {
+  name: string;
+  /** Street address — line 1. */
+  addressLine1: string;
+  /** Street address — line 2 (suite, floor, etc.). Optional. */
+  addressLine2: string;
+  /** "City, State, ZIP, Country" — single line. */
+  cityState: string;
+  phone: string;
+  email: string;
+  /** Mexican tax ID ("RFC"). Optional. */
+  taxId: string;
+  website: string;
+  /** Absolute path to the logo PNG. Null when missing — renderers fall
+   *  back to a text mark. */
+  logoPath: string | null;
+  /** Logo buffer + intrinsic size, eagerly loaded so the PDF renderer
+   *  doesn't do a sync read on every report. Null when no logo. */
+  logo: { buffer: Buffer; width: number; height: number } | null;
+}
+
+function envOr(key: string, fallback: string): string {
+  const v = process.env[key];
+  return v && v.trim() ? v : fallback;
+}
+
+function resolveLogoPath(): string | null {
+  const explicit = process.env.COMPANY_LOGO_PATH;
+  if (explicit) {
+    return fs.existsSync(explicit) ? explicit : null;
+  }
+  // Default: look in apps/api/assets/company_logo.png (copied from
+  // apps/web/public/images/company_logo.png — single canonical image
+  // kept in lock-step; see .env.example for the override path).
+  const candidates = [
+    path.resolve(__dirname, "..", "..", "assets", "company_logo.png"),
+    path.resolve(__dirname, "..", "..", "..", "web", "public", "images", "company_logo.png"),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+let cached: CompanyInfo | null = null;
+
+export function getCompanyInfo(): CompanyInfo {
+  if (cached) return cached;
+  const logoPath = resolveLogoPath();
+  let logo: CompanyInfo["logo"] = null;
+  if (logoPath) {
+    try {
+      const buf = fs.readFileSync(logoPath);
+      // Intrinsic PNG size: read IHDR (bytes 16-23 of the file).
+      // Width = BE uint32 at offset 16, height = BE uint32 at offset 20.
+      const w =
+        logoPath.endsWith(".png") && buf.length >= 24
+          ? buf.readUInt32BE(16)
+          : 0;
+      const h =
+        logoPath.endsWith(".png") && buf.length >= 24
+          ? buf.readUInt32BE(20)
+          : 0;
+      logo = { buffer: buf, width: w, height: h };
+    } catch {
+      logo = null;
+    }
+  }
+  cached = {
+    name: envOr("COMPANY_NAME", "Jorge Cuadros & Asociados"),
+    addressLine1: envOr(
+      "COMPANY_ADDRESS_LINE1",
+      "Av. Revolución 1234, Int. 5",
+    ),
+    addressLine2: envOr("COMPANY_ADDRESS_LINE2", ""),
+    cityState: envOr(
+      "COMPANY_CITY_STATE",
+      "Tijuana, Baja California 22000, México",
+    ),
+    phone: envOr("COMPANY_PHONE", "(664) 000-0000"),
+    email: envOr("COMPANY_EMAIL", "contacto@jorgecuadros.local"),
+    taxId: envOr("COMPANY_TAX_ID", ""),
+    website: envOr("COMPANY_WEBSITE", "jorgecuadros.local"),
+    logoPath,
+    logo,
+  };
+  return cached;
+}

apps/api/src/reports/outputs.ts

@@ -0,0 +1,433 @@
+/**
+ * Output renderers for the reports module.
+ *
+ * Every report's `run` returns `{ columns, rows, totals?, subtitle? }`.
+ * CSV/XLSX/PDF all derive from the same shape so adding a report = one
+ * registry entry, no per-format template.
+ *
+ * PDF uses pdfkit. The statement format (edo-cuenta-datos) uses a
+ * different layout than the tabular one — handled inline.
+ */
+
+// pdfkit exports its constructor via `module.exports = PDFDocument`, so a
+// namespace import gets the type, and `import = require()` gets the value.
+import PDFDocument = require("pdfkit");
+import * as ExcelJS from "exceljs";
+import type { ColumnDef, ReportResult } from "./reports.types";
+import { getCompanyInfo } from "./company";
+
+type Doc = PDFKit.PDFDocument;
+
+/* ----------------------------------------------------------------- CSV */
+
+function csvCell(v: unknown): string {
+  if (v === null || v === undefined) return "";
+  const s = String(v);
+  if (s.includes(",") || s.includes('"') || s.includes("\n") || s.includes("\r")) {
+    return `"${s.replace(/"/g, '""')}"`;
+  }
+  return s;
+}
+
+export function renderCsv(columns: ColumnDef[], result: ReportResult): string {
+  const headers = columns.map((c) => csvCell(c.label)).join(",");
+  const lines = result.rows.map((r) =>
+    columns
+      .map((c) => {
+        const v = r[c.key];
+        if (typeof v === "number") return v;
+        return csvCell(v);
+      })
+      .join(","),
+  );
+  const totals: string[] = [];
+  if (result.totals) {
+    for (const [k, v] of Object.entries(result.totals)) {
+      totals.push(csvCell(k), csvCell(v));
+    }
+  }
+  return [headers, ...lines, ...(totals.length ? [totals.join(",")] : [])].join(
+    "\n",
+  );
+}
+
+/* ----------------------------------------------------------------- XLSX */
+
+export async function renderXlsx(
+  columns: ColumnDef[],
+  result: ReportResult,
+): Promise<Buffer> {
+  const wb = new ExcelJS.Workbook();
+  wb.creator = "Jorge Cuadros & Asociados";
+  const ws = wb.addWorksheet("Reporte", {
+    views: [{ state: "frozen", ySplit: 1 }],
+  });
+  ws.columns = columns.map((c) => ({
+    header: c.label,
+    key: c.key,
+    width: Math.max(10, Math.min(40, (c.label.length + 2) * 1.2)),
+  }));
+  ws.getRow(1).font = { bold: true };
+  ws.getRow(1).fill = {
+    type: "pattern",
+    pattern: "solid",
+    fgColor: { argb: "FFE2EDE9" }, // brand-tint
+  };
+  for (const row of result.rows) {
+    ws.addRow(row);
+  }
+  // Number formatting for money columns.
+  for (const col of columns) {
+    if (col.type === "money" || col.type === "number") {
+      ws.getColumn(col.key).numFmt =
+        col.type === "money" ? "#,##0.00" : "#,##0";
+      ws.getColumn(col.key).alignment = { horizontal: "right" };
+    }
+  }
+  if (result.totals) {
+    const last = ws.addRow({});
+    let i = 1;
+    for (const [k, v] of Object.entries(result.totals)) {
+      const cell = ws.getCell(last.number, i);
+      cell.value = `${k}: ${v}`;
+      cell.font = { bold: true };
+      i++;
+    }
+  }
+  const buf = await wb.xlsx.writeBuffer();
+  return Buffer.from(buf);
+}
+
+/* ----------------------------------------------------------------- PDF */
+
+const BRAND = "#0c322d";
+const ACCENT = "#bf5a34";
+const MUTED = "#756c5c";
+const LINE = "#e4dccb";
+
+function fmtMoney(v: unknown): string {
+  if (v === null || v === undefined || v === "") return "";
+  const n = Number(v);
+  if (!Number.isFinite(n)) return String(v);
+  return n.toLocaleString("es-MX", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}
+
+function pdfRow(
+  doc: Doc,
+  y: number,
+  cols: Array<{ label: string; width: number; align?: "left" | "right" }>,
+  values: Array<{ text: string; align?: "left" | "right" }>,
+  x: number,
+): number {
+  let cx = x;
+  for (let i = 0; i < cols.length; i++) {
+    const c = cols[i];
+    const v = values[i] ?? { text: "" };
+    const align = v.align ?? c.align ?? "left";
+    const w = c.width;
+    doc
+      .font("Helvetica")
+      .fontSize(9)
+      .fillColor("#211d17")
+      .text(v.text, cx, y, {
+        width: w - 4,
+        align,
+        ellipsis: true,
+        lineBreak: false,
+        height: 16,
+      });
+    cx += w;
+  }
+  return y + 18;
+}
+
+export function renderPdf(
+  columns: ColumnDef[],
+  result: ReportResult,
+  title: string,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const doc = new PDFDocument({
+      size: "LETTER",
+      layout: "landscape",
+      margins: { top: 96, bottom: 56, left: 48, right: 48 },
+      bufferPages: true,
+      info: {
+        Title: title,
+        Author: "Jorge Cuadros & Asociados",
+        Subject: "Reporte",
+        Creator: "Jorge Cuadros Platform — Reports module",
+      },
+    });
+    const chunks: Buffer[] = [];
+    doc.on("data", (c: Buffer) => chunks.push(c));
+    doc.on("end", () => resolve(Buffer.concat(chunks)));
+    doc.on("error", reject);
+
+    const company = getCompanyInfo();
+    const pageW = doc.page.width - 96;
+
+    /** The header is repeated on every page (via addPage + manual draw). */
+    const drawHeader = () => {
+      // Background bar (brand pine) for the masthead.
+      doc.rect(0, 0, doc.page.width, 60).fill(BRAND);
+
+      // Logo, fitted to a 40px box, with 8px padding.
+      let textX = 48;
+      if (company.logo) {
+        const targetH = 40;
+        const scale = targetH / company.logo.height;
+        const w = company.logo.width * scale;
+        doc.image(company.logo.buffer, 48, 10, { height: targetH });
+        textX = 48 + w + 14;
+      }
+
+      // Company name (large) + "Reporte" tag below it.
+      doc
+        .fillColor("#f5f1e8")
+        .font("Helvetica-Bold")
+        .fontSize(15)
+        .text(company.name, textX, 14, { width: pageW - (textX - 48), lineBreak: false });
+      doc
+        .font("Helvetica")
+        .fontSize(8)
+        .fillColor("#cde0db")
+        .text("Reporte", textX, 36, { lineBreak: false });
+
+      // Right-aligned company locator (address + phone + email).
+      const rightLines = [
+        company.addressLine1,
+        company.addressLine2,
+        [company.cityState].filter(Boolean).join(" · "),
+        [company.phone, company.email].filter(Boolean).join(" · "),
+        company.taxId ? `RFC: ${company.taxId}` : "",
+      ].filter(Boolean);
+      doc.font("Helvetica").fontSize(8).fillColor("#cde0db");
+      let ry = 12;
+      for (const line of rightLines) {
+        doc.text(line, 48, ry, {
+          width: pageW,
+          align: "right",
+          lineBreak: false,
+          ellipsis: true,
+        });
+        ry += 10;
+      }
+
+      // Thin accent line under the masthead.
+      doc.rect(0, 60, doc.page.width, 2).fill(ACCENT);
+
+      // Title + subtitle + printed-at.
+      doc
+        .font("Helvetica-Bold")
+        .fontSize(15)
+        .fillColor(BRAND)
+        .text(title, 48, 72, { lineBreak: false });
+      let metaY = 92;
+      if (result.subtitle) {
+        doc
+          .font("Helvetica")
+          .fontSize(9)
+          .fillColor(MUTED)
+          .text(result.subtitle, 48, metaY, { lineBreak: false });
+        metaY += 12;
+      }
+      const printedAt = new Date().toLocaleString("es-MX");
+      doc
+        .font("Helvetica")
+        .fontSize(8)
+        .fillColor(MUTED)
+        .text(`Impreso: ${printedAt}`, 48, metaY, { lineBreak: false });
+    };
+
+    drawHeader();
+
+    // Column widths: distribute page width minus margins, weighted.
+    const totalW = columns.reduce((s, c) => s + (c.width ?? 12), 0);
+    const cols = columns.map((c) => ({
+      label: c.label,
+      width: ((c.width ?? 12) / totalW) * pageW,
+      align: c.align,
+    }));
+
+    let y = 130;
+    const drawTableHeader = () => {
+      doc.rect(48, y, pageW, 18).fill("#faf6ee");
+      y = pdfRow(
+        doc,
+        y + 4,
+        cols,
+        cols.map((c) => ({ text: c.label, align: c.align })),
+        48,
+      );
+      doc
+        .moveTo(48, y)
+        .lineTo(48 + pageW, y)
+        .strokeColor(LINE)
+        .lineWidth(0.5)
+        .stroke();
+    };
+    drawTableHeader();
+
+    // Body rows.
+    for (const r of result.rows) {
+      if (y > doc.page.height - 64) {
+        doc.addPage({ layout: "landscape", margins: { top: 96, bottom: 56, left: 48, right: 48 } });
+        drawHeader();
+        y = 130;
+        drawTableHeader();
+      }
+      const vals = columns.map((c) => {
+        const v = r[c.key];
+        const text = c.type === "money" ? fmtMoney(v) : v == null ? "" : String(v);
+        return { text, align: c.align };
+      });
+      y = pdfRow(doc, y + 4, cols, vals, 48);
+      doc
+        .moveTo(48, y)
+        .lineTo(48 + pageW, y)
+        .strokeColor("#e4dccb")
+        .lineWidth(0.4)
+        .stroke();
+    }
+
+    // Totals.
+    if (result.totals) {
+      y += 6;
+      doc.rect(48, y, pageW, 18).fill(ACCENT);
+      doc
+        .font("Helvetica-Bold")
+        .fontSize(9)
+        .fillColor("#f5f1e8")
+        .text(
+          Object.entries(result.totals)
+            .map(([k, v]) => `${k}: ${v}`)
+            .join("   ·   "),
+          52,
+          y + 5,
+          { width: pageW - 8, align: "left" },
+        );
+    }
+
+    doc.end();
+  });
+}
+
+/* ----------------------------------------------------------------- print (HTML) */
+
+/**
+ * Print-stylesheet-friendly HTML. The web app's print stylesheet hides
+ * nav, but otherwise this is a plain table the browser paginates itself.
+ *
+ * The header carries the company info (logo + name + locator) so printed
+ * pages stand alone — staff can hand one to a customer and the office
+ * identification is on every sheet, not buried in the cover page.
+ */
+export function renderPrintHtml(
+  columns: ColumnDef[],
+  result: ReportResult,
+  title: string,
+): string {
+  const company = getCompanyInfo();
+  const head = (label: string, align?: "left" | "right") =>
+    `<th style="text-align:${align ?? "left"};padding:6px 8px;border-bottom:2px solid #0c322d;background:#faf6ee;font-size:11px">${escapeHtml(label)}</th>`;
+  const cell = (v: unknown, c: ColumnDef) => {
+    const text = c.type === "money" ? fmtMoney(v) : v == null ? "" : String(v);
+    const align = c.align ?? "left";
+    return `<td style="text-align:${align};padding:4px 8px;border-bottom:1px solid #e4dccb;font-size:11px;${c.type === "money" ? "font-variant-numeric:tabular-nums" : ""}">${escapeHtml(text)}</td>`;
+  };
+  const rows = result.rows
+    .map(
+      (r) =>
+        `<tr>${columns
+          .map((c) => cell(r[c.key], c))
+          .join("")}</tr>`,
+    )
+    .join("");
+  const totals = result.totals
+    ? `<tr><td colspan="${columns.length}" style="padding:8px;background:#bf5a34;color:#f5f1e8;font-weight:600;font-size:11px">${Object.entries(
+        result.totals,
+      )
+        .map(([k, v]) => `${escapeHtml(k)}: ${escapeHtml(String(v))}`)
+        .join(" &nbsp;·&nbsp; ")}</td></tr>`
+    : "";
+
+  // Logo embedded as base64 data URL — the print page is opened as a
+  // new tab and printed standalone, so a relative path to the web app
+  // wouldn't resolve when launched outside the web's origin.
+  const logoDataUrl = company.logo
+    ? `data:image/png;base64,${company.logo.buffer.toString("base64")}`
+    : null;
+
+  const locatorLines = [
+    company.addressLine1,
+    company.addressLine2,
+    company.cityState,
+    [company.phone, company.email].filter(Boolean).join(" · "),
+    company.taxId ? `RFC: ${company.taxId}` : "",
+  ].filter(Boolean);
+
+  return `<!doctype html>
+<html lang="es"><head>
+<meta charset="utf-8" />
+<title>${escapeHtml(title)} — ${escapeHtml(company.name)}</title>
+<style>
+  @page { size: letter landscape; margin: 0.5in; }
+  body { font-family: -apple-system, "Helvetica Neue", Helvetica, Arial, sans-serif; color: #211d17; margin: 0; }
+  .masthead { display: flex; align-items: flex-start; gap: 16px; padding: 12px 16px; background: #0c322d; color: #f5f1e8; border-radius: 6px 6px 0 0; }
+  .masthead-logo { flex: 0 0 auto; }
+  .masthead-logo img { display: block; height: 56px; width: auto; }
+  .masthead-text { flex: 1; min-width: 0; }
+  .masthead-name { font-family: Georgia, "Times New Roman", serif; font-size: 20px; font-weight: 600; line-height: 1.1; }
+  .masthead-tag { font-size: 11px; color: #cde0db; margin-top: 2px; text-transform: uppercase; letter-spacing: 0.06em; }
+  .masthead-locator { font-size: 10px; color: #cde0db; text-align: right; line-height: 1.35; white-space: nowrap; }
+  .accent { height: 3px; background: #bf5a34; }
+  .head { padding: 12px 4px 8px; }
+  .head h1 { font-family: Georgia, "Times New Roman", serif; font-size: 18px; margin: 0; color: #0c322d; }
+  .head p  { font-size: 11px; color: #756c5c; margin: 2px 0 0; }
+  table { width: 100%; border-collapse: collapse; }
+  @media print {
+    .noprint { display: none; }
+    .masthead { border-radius: 0; }
+  }
+  .noprint { padding: 8px 0; }
+  .noprint button { padding: 6px 12px; background: #0c322d; color: #f5f1e8; border: 0; border-radius: 4px; cursor: pointer; font-size: 12px; }
+  .footer { margin-top: 16px; font-size: 9px; color: #756c5c; border-top: 1px solid #e4dccb; padding-top: 6px; display: flex; justify-content: space-between; }
+</style>
+</head><body>
+<div class="noprint"><button onclick="window.print()">Imprimir / Guardar PDF</button></div>
+<div class="masthead">
+  ${logoDataUrl ? `<div class="masthead-logo"><img src="${logoDataUrl}" alt="" /></div>` : ""}
+  <div class="masthead-text">
+    <div class="masthead-name">${escapeHtml(company.name)}</div>
+    <div class="masthead-tag">Reporte</div>
+  </div>
+  <div class="masthead-locator">
+    ${locatorLines.map((l) => escapeHtml(l)).join("<br/>")}
+    ${company.website ? `<br/>${escapeHtml(company.website)}` : ""}
+  </div>
+</div>
+<div class="accent"></div>
+<div class="head">
+  <h1>${escapeHtml(title)}</h1>
+  ${result.subtitle ? `<p>${escapeHtml(result.subtitle)}</p>` : ""}
+  <p>Impreso: ${new Date().toLocaleString("es-MX")}</p>
+</div>
+<table>
+  <thead><tr>${columns.map((c) => head(c.label, c.align)).join("")}</tr></thead>
+  <tbody>${rows}${totals}</tbody>
+</table>
+<div class="footer">
+  <span>${escapeHtml(company.name)} · ${escapeHtml(company.phone)} · ${escapeHtml(company.email)}</span>
+  <span>${escapeHtml(title)}</span>
+</div>
+</body></html>`;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

apps/api/src/reports/reports.controller.ts

@@ -0,0 +1,130 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Header,
+  Param,
+  Post,
+  Query,
+  Res,
+  UseGuards,
+} from "@nestjs/common";
+import type { Response } from "express";
+import { AuthenticatedGuard } from "../auth/authenticated.guard";
+import { ReportsService } from "./reports.service";
+import {
+  renderCsv,
+  renderPdf,
+  renderPrintHtml,
+  renderXlsx,
+} from "./outputs";
+import { findReport } from "./reports.registry";
+
+/**
+ * Reports routes. Every report is dispatched by slug; outputs are
+ * differentiated by `?format=...` (default `json`). Reads only — gated
+ * by AuthenticatedGuard alone, like every other read in the app.
+ */
+@UseGuards(AuthenticatedGuard)
+@Controller("reports")
+export class ReportsController {
+  constructor(private readonly reports: ReportsService) {}
+
+  /** Catalog of all registered reports (the /reportes index). */
+  @Get()
+  catalog() {
+    return { items: this.reports.catalog() };
+  }
+
+  /** Run a report and return the JSON result (rows + totals + the def's columns). */
+  @Get(":slug")
+  async runJson(
+    @Param("slug") slug: string,
+    @Query() query: Record<string, string | undefined>,
+  ) {
+    const def = findReport(slug);
+    const result = await this.reports.run(slug, query);
+    return { ...result, columns: def?.columns ?? [] };
+  }
+
+  /** CSV download. */
+  @Get(":slug/csv")
+  @Header("Content-Type", "text/csv; charset=utf-8")
+  async runCsv(
+    @Param("slug") slug: string,
+    @Query() query: Record<string, string | undefined>,
+    @Res() res: Response,
+  ) {
+    const def = findReport(slug);
+    const result = await this.reports.run(slug, query);
+    const filename = `${def?.title ?? slug}-${new Date().toISOString().slice(0, 10)}.csv`;
+    res.setHeader(
+      "Content-Disposition",
+      `attachment; filename="${filename.replace(/[^\wÀ-ſ .-]/g, "_")}"`,
+    );
+    res.send(renderCsv(def?.columns ?? [], result));
+  }
+
+  /** XLSX download. */
+  @Get(":slug/xlsx")
+  async runXlsx(
+    @Param("slug") slug: string,
+    @Query() query: Record<string, string | undefined>,
+    @Res() res: Response,
+  ) {
+    const def = findReport(slug);
+    const result = await this.reports.run(slug, query);
+    const filename = `${def?.title ?? slug}-${new Date().toISOString().slice(0, 10)}.xlsx`;
+    const buf = await renderXlsx(def?.columns ?? [], result);
+    res.setHeader(
+      "Content-Type",
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    );
+    res.setHeader(
+      "Content-Disposition",
+      `attachment; filename="${filename.replace(/[^\wÀ-ſ .-]/g, "_")}"`,
+    );
+    res.send(buf);
+  }
+
+  /** PDF download. */
+  @Get(":slug/pdf")
+  async runPdf(
+    @Param("slug") slug: string,
+    @Query() query: Record<string, string | undefined>,
+    @Res() res: Response,
+  ) {
+    const def = findReport(slug);
+    const result = await this.reports.run(slug, query);
+    const buf = await renderPdf(def?.columns ?? [], result, def?.title ?? slug);
+    const filename = `${def?.title ?? slug}-${new Date().toISOString().slice(0, 10)}.pdf`;
+    res.setHeader("Content-Type", "application/pdf");
+    res.setHeader(
+      "Content-Disposition",
+      `attachment; filename="${filename.replace(/[^\wÀ-ſ .-]/g, "_")}"`,
+    );
+    res.send(buf);
+  }
+
+  /** Browser-printable HTML view (the user hits Print → Save as PDF). */
+  @Get(":slug/print")
+  @Header("Content-Type", "text/html; charset=utf-8")
+  async runPrint(
+    @Param("slug") slug: string,
+    @Query() query: Record<string, string | undefined>,
+  ) {
+    const def = findReport(slug);
+    const result = await this.reports.run(slug, query);
+    return renderPrintHtml(def?.columns ?? [], result, def?.title ?? slug);
+  }
+
+  /** POST a customer-picker-driven report (statement). Mirrors GET to keep
+   *  the param contract simple: same body shape, same response. */
+  @Post(":slug")
+  async runPost(
+    @Param("slug") slug: string,
+    @Body() body: Record<string, string | undefined>,
+  ) {
+    return this.reports.run(slug, body);
+  }
+}

apps/api/src/reports/reports.module.ts

@@ -0,0 +1,9 @@
+import { Module } from "@nestjs/common";
+import { ReportsController } from "./reports.controller";
+import { ReportsService } from "./reports.service";
+
+@Module({
+  controllers: [ReportsController],
+  providers: [ReportsService],
+})
+export class ReportsModule {}

apps/api/src/reports/reports.service.ts

@@ -0,0 +1,45 @@
+import { Injectable, NotFoundException } from "@nestjs/common";
+import { PrismaService } from "../prisma/prisma.service";
+import { findReport, REPORTS } from "./reports.registry";
+import type { ReportDef } from "./reports.types";
+
+/**
+ * The reports service. Two responsibilities:
+ *  1. Run a report by slug with the given params — just dispatch.
+ *  2. Return the catalog for the /reportes index page.
+ *
+ * Output rendering (CSV/XLSX/PDF/HTML print) lives in `outputs.ts`; this
+ * service is data only. The controller maps URLs to (slug, format) and
+ * hands the result to outputs.
+ */
+@Injectable()
+export class ReportsService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  /** List every registered report, in display order. */
+  catalog(): Array<{
+    slug: string;
+    title: string;
+    description: string;
+    domain: string;
+    legacyName: string | null;
+    format: string;
+    params: ReportDef["params"];
+  }> {
+    return REPORTS.map((r) => ({
+      slug: r.slug,
+      title: r.title,
+      description: r.description,
+      domain: r.domain,
+      legacyName: r.legacyName,
+      format: r.format,
+      params: r.params,
+    }));
+  }
+
+  async run(slug: string, params: Record<string, string | undefined>) {
+    const def = findReport(slug);
+    if (!def) throw new NotFoundException(`Reporte "${slug}" no encontrado`);
+    return def.run(this.prisma, params);
+  }
+}

apps/api/src/reports/reports.types.ts

@@ -0,0 +1,142 @@
+/**
+ * The reports module — plan step 10.
+ *
+ * Each "report" is one entry in `reports.registry.ts`. The entry declares
+ * its slug (URL id), title, what filters it accepts, what columns it
+ * returns, and a `run` function that produces the data from Prisma. The
+ * service dispatches on slug; the controller exposes JSON + CSV + XLSX +
+ * PDF + HTML print; the catalog endpoint exposes the registry itself so
+ * the `/reportes` page can render the same data.
+ *
+ * Output philosophy: a report returns a uniform shape — `columns` (typed
+ * schema) + `rows` (any[] of values matching the column types) + `totals`
+ * (record of column key → summary value). All three output formats
+ * (CSV/XLSX/PDF/print) derive from this same shape so adding a new
+ * report is one entry, never a per-format template.
+ */
+
+import { Prisma } from "@jorgecuadros/database";
+import { PrismaService } from "../prisma/prisma.service";
+
+/** Top-level grouping for the catalog page; matches the existing nav. */
+export type ReportDomain =
+  | "clientes"
+  | "polizas"
+  | "servicios"
+  | "estado-cuenta"
+  | "chequera";
+
+/** How the runner should render rows: a grid, a per-customer statement, or
+ *  one printable letter per row (e.g. renewal notices — see `format:
+ *  "letter"` reports for the `__kind: "letter"` row shape they emit). */
+export type ReportFormat = "tabular" | "statement" | "letter";
+
+/** Filter controls the report's UI should render. */
+export type ParamDef =
+  | {
+      key: string;
+      label: string;
+      kind: "text" | "number";
+      placeholder?: string;
+      defaultValue?: string;
+    }
+  | {
+      key: string;
+      label: string;
+      kind: "date";
+      /** Inclusive bound, true for `to`, false for `from`. */
+      endOfDay?: boolean;
+      defaultValue?: string;
+    }
+  | {
+      key: string;
+      label: string;
+      kind: "select";
+      options: { value: string; label: string }[];
+      defaultValue?: string;
+    }
+  | {
+      key: string;
+      label: string;
+      kind: "customer-picker";
+    };
+
+/** One column of the output table. */
+export interface ColumnDef {
+  key: string;
+  label: string;
+  /** Render hint for the on-screen + print table. */
+  type: "text" | "number" | "money" | "date";
+  /** Right-align numbers/money; default false (left). */
+  align?: "left" | "right";
+  /** Used for column-width hints in the print/PDF layout. */
+  width?: number;
+}
+
+/** Shape every report's `run` resolves to. Columns come from the def. */
+export interface ReportResult {
+  rows: Array<Record<string, unknown>>;
+  totals?: Record<string, string | number>;
+  /** Optional free-form subtitle for print/PDF (e.g. date range, scope). */
+  subtitle?: string;
+}
+
+/** A report's static declaration. */
+export interface ReportDef {
+  slug: string;
+  title: string;
+  description: string;
+  domain: ReportDomain;
+  /** The original Access report name (per docs/LEGACY_DATABASES_OBJECTS.md)
+   *  for traceability. Null when this is a new report with no legacy equiv. */
+  legacyName: string | null;
+  format: ReportFormat;
+  params: ParamDef[];
+  columns: ColumnDef[];
+  /**
+   * Run the report. Receives the Prisma client and the validated params
+   * record (keys are the `key` from ParamDef, values are the strings the
+   * runner collected; numeric/date params arrive as strings — the report
+   * parses them). Must apply the same NOT_VOIDED filter on transactions as
+   * the billing module so totals match.
+   */
+  run: (
+    prisma: PrismaService,
+    params: Record<string, string | undefined>,
+  ) => Promise<ReportResult>;
+}
+
+/** A typed bag of helpers for the report functions. */
+export interface ReportCtx {
+  prisma: PrismaService;
+  params: Record<string, string | undefined>;
+}
+
+/** Helper: a `YYYY-MM-DD` bound; unparseable is undefined. */
+export function parseDate(
+  v: string | undefined,
+  endOfDay = false,
+): Date | undefined {
+  if (!v) return undefined;
+  const d = new Date(endOfDay ? `${v}T23:59:59.999Z` : `${v}T00:00:00.000Z`);
+  return Number.isNaN(d.getTime()) ? undefined : d;
+}
+
+/** Helper: integer param with default. */
+export function intParam(
+  p: Record<string, string | undefined>,
+  key: string,
+  def: number,
+  min = 1,
+  max = 1000,
+): number {
+  const n = Number(p[key]);
+  if (!Number.isFinite(n)) return def;
+  return Math.min(max, Math.max(min, Math.round(n)));
+}
+
+/** Helper: not-voided filter, shared with billing.service. */
+export const NOT_VOIDED: Prisma.TransactionWhereInput = { voidedAt: null };
+export const NOT_VOIDED_BANK: Prisma.BankTransactionWhereInput = {
+  voidedAt: null,
+};

apps/api/src/statements/ocr/ocr.provider.ts

@@ -0,0 +1,53 @@
+/**
+ * The OCR seam. Everything above this interface works in terms of page text and
+ * word boxes, so the concrete engine is swappable without touching the parsers,
+ * the matcher, or the schema.
+ *
+ * The shipped implementation is self-hosted Tesseract (see tesseract.provider).
+ * That choice is evidence-based rather than assumed: run against 46 pages of
+ * real scanned CFE, CESPT and Telnor statements, it identified the provider on
+ * 46/46 and extracted a usable account reference on 43/46, which is well past
+ * the bar for a queue whose whole point is that a human confirms every row. A
+ * managed document-extraction API (Textract, Document Intelligence, Document
+ * AI) fits behind this same interface if per-page accuracy ever proves
+ * insufficient, with no schema change — but at 300+ pages/month/company it
+ * would carry a real recurring cost for accuracy that is not currently the
+ * bottleneck.
+ */
+
+/** One OCR'd word, with where it sits on the page. */
+export interface OcrWord {
+  text: string;
+  /** Pixel box in the rendered page image. */
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  /** Engine confidence for this word, 0..1. */
+  confidence: number;
+}
+
+export interface OcrPage {
+  /** Full page text, reading order, newline-separated. */
+  text: string;
+  /**
+   * Word boxes. Needed because two of the three real layouts are *tables* —
+   * the CESPT "RECIBO" prints `No. DE CUENTA` as a column header with the
+   * value in the row beneath it, which line-oriented text cannot associate.
+   * Parsers fall back to geometry for exactly those fields.
+   */
+  words: OcrWord[];
+  /** Mean word confidence across the page, 0..1. */
+  confidence: number;
+}
+
+export interface OcrProvider {
+  /** True when the engine is actually usable in this deployment. */
+  available(): Promise<boolean>;
+  /** Split a PDF into one rendered page image per page. */
+  renderPages(pdf: Buffer): Promise<Buffer[]>;
+  /** OCR a single rendered page image. */
+  recognize(pageImage: Buffer): Promise<OcrPage>;
+}
+
+export const OCR_PROVIDER = Symbol("OCR_PROVIDER");

apps/api/src/statements/ocr/tesseract.provider.ts

@@ -0,0 +1,195 @@
+import { Injectable, Logger, ServiceUnavailableException } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import type { OcrPage, OcrProvider, OcrWord } from "./ocr.provider";
+
+const run = promisify(execFile);
+
+/**
+ * Self-hosted OCR: `pdftoppm` (poppler) to rasterise, `tesseract` to read.
+ *
+ * Both are external binaries rather than a native npm addon, which keeps the
+ * pnpm workspace free of a compiled dependency and makes the alpine runtime
+ * image a two-package change (see docker/api.Dockerfile). Like StorageService,
+ * a missing binary degrades rather than crashes the API: the module reports
+ * itself unavailable and statement ingest returns 503, while every other
+ * feature keeps working.
+ *
+ * The settings below are not arbitrary — they were measured against the real
+ * scanned samples:
+ *   - 300 DPI grayscale. The source scans are phone photos of paper at ~5MB a
+ *     page; below 300 the small print (RMU, clave catastral) stops resolving,
+ *     above it costs time for no additional fields.
+ *   - `--psm 6` ("assume a single uniform block of text"). The default page
+ *     segmentation splits these dense forms into columns and interleaves them,
+ *     which destroys the label-then-value adjacency every parser depends on.
+ *   - Spanish traineddata, with a graceful fall back to English if the language
+ *     pack is absent — an accented label reads worse but the digits, which are
+ *     what actually gets matched, are unaffected.
+ */
+@Injectable()
+export class TesseractOcrProvider implements OcrProvider {
+  private readonly logger = new Logger(TesseractOcrProvider.name);
+  private readonly dpi: number;
+  private readonly lang: string;
+  private probe: Promise<boolean> | null = null;
+
+  constructor(config: ConfigService) {
+    this.dpi = Number(config.get("OCR_DPI") ?? 300);
+    this.lang = config.get<string>("OCR_LANG") ?? "spa";
+  }
+
+  /** Cached — the binaries do not appear or vanish while the process runs. */
+  available(): Promise<boolean> {
+    if (!this.probe) {
+      this.probe = (async () => {
+        try {
+          await Promise.all([
+            run("tesseract", ["--version"]),
+            run("pdftoppm", ["-v"]),
+          ]);
+          return true;
+        } catch {
+          this.logger.warn(
+            "OCR unavailable: `tesseract` and/or `pdftoppm` not found on PATH. " +
+              "Statement ingest is disabled; every other feature is unaffected.",
+          );
+          return false;
+        }
+      })();
+    }
+    return this.probe;
+  }
+
+  private async require(): Promise<void> {
+    if (!(await this.available())) {
+      throw new ServiceUnavailableException(
+        "El servicio de OCR no está disponible en este servidor.",
+      );
+    }
+  }
+
+  private async scratch<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+    const dir = await mkdtemp(join(tmpdir(), "stmt-ocr-"));
+    try {
+      return await fn(dir);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+
+  async renderPages(pdf: Buffer): Promise<Buffer[]> {
+    await this.require();
+    return this.scratch(async (dir) => {
+      const src = join(dir, "in.pdf");
+      await writeFile(src, pdf);
+      // -gray: these are grayscale scans already; colour triples the bytes
+      // handed to tesseract for no gain in character recognition.
+      await run("pdftoppm", [
+        "-r",
+        String(this.dpi),
+        "-gray",
+        "-png",
+        src,
+        join(dir, "page"),
+      ]);
+      const files = (await readdir(dir))
+        .filter((f) => f.startsWith("page") && f.endsWith(".png"))
+        // pdftoppm zero-pads its page numbers, so lexical order is page order.
+        .sort();
+      return Promise.all(files.map((f) => readFile(join(dir, f))));
+    });
+  }
+
+  async recognize(pageImage: Buffer): Promise<OcrPage> {
+    await this.require();
+    return this.scratch(async (dir) => {
+      const img = join(dir, "page.png");
+      await writeFile(img, pageImage);
+
+      // One tesseract invocation produces both outputs; TSV carries the word
+      // boxes and per-word confidence, and its text can be reassembled into
+      // reading order, so there is no need to run the engine twice.
+      const out = join(dir, "out");
+      try {
+        await run("tesseract", [img, out, "-l", this.lang, "--psm", "6", "tsv"]);
+      } catch (err) {
+        if (this.lang !== "eng") {
+          this.logger.warn(
+            `Tesseract failed with lang "${this.lang}", retrying with "eng": ${
+              (err as Error).message
+            }`,
+          );
+          await run("tesseract", [img, out, "-l", "eng", "--psm", "6", "tsv"]);
+        } else {
+          throw err;
+        }
+      }
+
+      const tsv = await readFile(`${out}.tsv`, "utf8");
+      return parseTsv(tsv);
+    });
+  }
+}
+
+/**
+ * Turn tesseract's TSV into words plus reassembled text.
+ *
+ * Columns are: level, page_num, block_num, par_num, line_num, word_num, left,
+ * top, width, height, conf, text. Rows with level < 5 are structural (page,
+ * block, paragraph, line) and carry no text; only level 5 is a word. A conf of
+ * -1 marks a structural row, so those are dropped rather than averaged in —
+ * including them would drag every page's confidence toward zero.
+ */
+export function parseTsv(tsv: string): OcrPage {
+  const lines = tsv.split("\n");
+  const header = lines[0]?.split("\t") ?? [];
+  const col = (name: string) => header.indexOf(name);
+  const iLeft = col("left");
+  const iTop = col("top");
+  const iWidth = col("width");
+  const iHeight = col("height");
+  const iConf = col("conf");
+  const iText = col("text");
+  const iLine = col("line_num");
+  const iBlock = col("block_num");
+
+  const words: OcrWord[] = [];
+  // Keyed by block+line so the reassembled text preserves the engine's own
+  // reading order instead of sorting words by raw y, which interleaves columns.
+  const byLine = new Map<string, string[]>();
+
+  for (let i = 1; i < lines.length; i++) {
+    const f = lines[i].split("\t");
+    if (f.length <= iText) continue;
+    const text = f[iText]?.trim();
+    if (!text) continue;
+    const confidence = Number(f[iConf]);
+    if (!Number.isFinite(confidence) || confidence < 0) continue;
+
+    words.push({
+      text,
+      left: Number(f[iLeft]) || 0,
+      top: Number(f[iTop]) || 0,
+      width: Number(f[iWidth]) || 0,
+      height: Number(f[iHeight]) || 0,
+      confidence: confidence / 100,
+    });
+
+    const key = `${f[iBlock]}:${f[iLine]}`;
+    const bucket = byLine.get(key);
+    if (bucket) bucket.push(text);
+    else byLine.set(key, [text]);
+  }
+
+  const text = [...byLine.values()].map((w) => w.join(" ")).join("\n");
+  const confidence = words.length
+    ? words.reduce((sum, w) => sum + w.confidence, 0) / words.length
+    : 0;
+
+  return { text, words, confidence };
+}

apps/api/src/statements/parsers/statement-parser.ts

@@ -0,0 +1,390 @@
+import type { ServiceKind } from "@jorgecuadros/database";
+import type { OcrPage, OcrWord } from "../ocr/ocr.provider";
+
+/**
+ * What one parsed statement page yields. `accountRef` is already normalised to
+ * the form the migrated `PropertyService` columns hold, so the matcher compares
+ * like with like and never has to know about provider-specific formatting.
+ */
+export interface ParsedStatement {
+  /** "CFE" | "CESPT" | "TELNOR", or null when no parser claimed the page. */
+  provider: string | null;
+  serviceKind: ServiceKind | null;
+  accountRef: string | null;
+  /** Clave catastral, when printed — a second key to match on. */
+  cadastralKey: string | null;
+  amount: number | null;
+  dueDate: Date | null;
+  period: string | null;
+  /**
+   * Independent corroboration of `accountRef`. CFE and Telnor both print a
+   * payment barcode that repeats the account number (and the amount), so when
+   * the barcode and the label agree the extraction is near-certainly right;
+   * when they disagree, or only one is present, the page is worth a human
+   * glance. Null when the layout has no second source.
+   */
+  crossChecked: boolean | null;
+  /** Human-readable trail of what was read, surfaced in the review queue. */
+  notes: string[];
+}
+
+// --- shared helpers ---------------------------------------------------------
+
+/**
+ * Tesseract confuses these glyphs inside numeric runs with some regularity —
+ * a real clave catastral `KB078025` came back as `KBO78025`. Applied ONLY to
+ * fields known to be digits, never to free text, where it would corrupt words.
+ */
+const DIGIT_CONFUSIONS: Record<string, string> = {
+  O: "0",
+  o: "0",
+  D: "0",
+  I: "1",
+  l: "1",
+  "|": "1",
+  S: "5",
+  B: "8",
+};
+
+export function toDigits(s: string | null | undefined): string {
+  if (!s) return "";
+  return s
+    .split("")
+    .map((c) => DIGIT_CONFUSIONS[c] ?? c)
+    .join("")
+    .replace(/\D/g, "");
+}
+
+/**
+ * Parse a printed amount, treating `,` and `.` by position rather than by
+ * assumption. A real Telnor bill OCR'd as "$ 649,00" — blindly stripping commas
+ * as thousands separators turned $649.00 into $64,900, a hundredfold error that
+ * would post silently. Two trailing digits after a single separator are always
+ * cents here; a separator followed by three digits is a thousands group.
+ */
+function money(s: string | null | undefined): number | null {
+  if (!s) return null;
+  const cleaned = s.replace(/[\s$]/g, "");
+
+  // 1.234,56 or 1,234.56 — grouped thousands plus optional cents.
+  let m = cleaned.match(/^(\d{1,3}(?:[.,]\d{3})+)([.,]\d{1,2})?$/);
+  if (m) {
+    const whole = m[1].replace(/[.,]/g, "");
+    const cents = m[2] ? m[2].slice(1) : "";
+    return Number(cents ? `${whole}.${cents.padEnd(2, "0")}` : whole);
+  }
+
+  // 649,00 / 649.00 — a single separator with exactly two digits after it.
+  m = cleaned.match(/^(\d+)[.,](\d{2})$/);
+  if (m) return Number(`${m[1]}.${m[2]}`);
+
+  const n = Number(cleaned.replace(/[,.]/g, ""));
+  return Number.isFinite(n) ? n : null;
+}
+
+function firstMatch(text: string, patterns: RegExp[]): string | null {
+  for (const p of patterns) {
+    const m = text.match(p);
+    if (m?.[1]) return m[1].trim();
+  }
+  return null;
+}
+
+const MONTHS: Record<string, number> = {
+  ENE: 0, FEB: 1, MAR: 2, ABR: 3, MAY: 4, JUN: 5,
+  JUL: 6, AGO: 7, SEP: 8, OCT: 9, NOV: 10, DIC: 11,
+};
+
+/** Parses the three date shapes these statements actually print. */
+export function parseDate(raw: string | null | undefined): Date | null {
+  if (!raw) return null;
+  const s = raw.trim().toUpperCase();
+
+  // 16/07/2026
+  let m = s.match(/^(\d{1,2})\/(\d{1,2})\/(\d{4})$/);
+  if (m) return utc(+m[3], +m[2] - 1, +m[1]);
+
+  // 22-JUL-2026  /  22 JUN 26
+  m = s.match(/^(\d{1,2})[-\s]([A-Z]{3})[A-Z]*[-\s](\d{2,4})$/);
+  if (m && MONTHS[m[2]] !== undefined) {
+    const y = m[3].length === 2 ? 2000 + +m[3] : +m[3];
+    return utc(y, MONTHS[m[2]], +m[1]);
+  }
+
+  // 2026-07-22 (already normalised, e.g. decoded from a barcode)
+  m = s.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (m) return utc(+m[1], +m[2] - 1, +m[3]);
+
+  return null;
+}
+
+function utc(y: number, mo: number, d: number): Date | null {
+  const dt = new Date(Date.UTC(y, mo, d));
+  return Number.isNaN(dt.getTime()) ? null : dt;
+}
+
+/**
+ * Read the value printed *underneath* a column header.
+ *
+ * The CESPT "RECIBO" is a table: `No. DE CUENTA` is a header cell and its value
+ * sits in the row below it, so no amount of label-adjacent regex on line text
+ * can associate the two. This walks the word boxes instead — find the header
+ * word, then take the nearest word below it whose horizontal centre falls
+ * within the column.
+ */
+export function valueUnder(
+  page: OcrPage,
+  header: RegExp,
+  opts: { maxDy?: number; tolerance?: number; match?: RegExp } = {},
+): string | null {
+  const { maxDy = 300, tolerance = 200, match } = opts;
+  const centre = (w: OcrWord) => ({
+    x: w.left + w.width / 2,
+    y: w.top + w.height / 2,
+  });
+
+  for (const h of page.words.filter((w) => header.test(w.text))) {
+    const hc = centre(h);
+    const below = page.words
+      .filter((w) => {
+        const c = centre(w);
+        return c.y > hc.y && c.y <= hc.y + maxDy && Math.abs(c.x - hc.x) <= tolerance;
+      })
+      .sort((a, b) => centre(a).y - centre(b).y);
+
+    for (const w of below) {
+      if (!match || match.test(w.text)) return w.text;
+    }
+  }
+  return null;
+}
+
+// --- provider detection -----------------------------------------------------
+
+/**
+ * Brand wordmarks first, page structure only as a fallback — and the two passes
+ * must not be interleaved. Scanned logos OCR badly (one CESPT header came back
+ * as "E BAJA ES PAGO / EALIFORNIA", with neither "CESPT" nor "COMISIÓN ESTATAL"
+ * readable), so the structural pass is what rescues those pages. But a Telnor
+ * bill contains the words "Pagar antes de", which a CFE structural rule
+ * evaluated first will happily claim — running all brand checks before any
+ * structural check is what keeps that from happening.
+ */
+const BRAND: [string, RegExp][] = [
+  ["CFE", /comisi[oó]n federal de electricidad|CFE.?contigo|Suministrador de Servicios/i],
+  ["CESPT", /CESPT|COMISI[OÓ]N ESTATAL DE SERVICIOS/i],
+  ["TELNOR", /TELNOR|TELEFONOS DEL NOROESTE/i],
+];
+
+const LAYOUT: [string, RegExp][] = [
+  ["CFE", /NO\.?\s*DE\s*SERVICIO|L[IÍ]MITE\s*DE\s*PAGO|PERIODO\s*FACTURADO/i],
+  ["CESPT", /SALDO\s+CORRIENTE|CLAVE\s*CATASTRAL|No\.?\s*DE\s*CUENTA/i],
+  ["TELNOR", /Mes\s*de\s*Facturaci[oó]n|Pagar\s*antes\s*de/i],
+];
+
+export function detectProvider(text: string): string | null {
+  for (const group of [BRAND, LAYOUT]) {
+    for (const [name, pattern] of group) {
+      if (pattern.test(text)) return name;
+    }
+  }
+  return null;
+}
+
+// --- CFE (electric) ---------------------------------------------------------
+
+function parseCfe(page: OcrPage): ParsedStatement {
+  const text = page.text;
+  const notes: string[] = [];
+
+  // The payment barcode line repeats the service number, the due date (YYMMDD)
+  // and the amount in one fixed-width run, and reads far more reliably than the
+  // label: on one sample the label came back as "0059603001917" (a digit too
+  // many) while its barcode gave the correct "005960300191". So the barcode
+  // wins, and the label becomes the cross-check rather than the source.
+  const barcode = text.match(/\b01\s+([0-9OIlSBD]{12})\s+([0-9OIlSBD]{6})\s+([0-9OIlSBD]{9})\b/);
+  const label = firstMatch(text, [/NO\.?\s*DE\s*SERVICIO\s*[:;.]?\s*([0-9OIlSBD]{10,14})/i]);
+
+  let accountRef: string | null = null;
+  let amount: number | null = null;
+  let dueDate: Date | null = null;
+  let crossChecked: boolean | null = null;
+
+  if (barcode) {
+    // Leading zeros are print padding: DATMEX.rpu holds the bare 10 digits.
+    accountRef = toDigits(barcode[1]).replace(/^0+/, "");
+    amount = Number(toDigits(barcode[3]));
+    const d = toDigits(barcode[2]);
+    dueDate = parseDate(`20${d.slice(0, 2)}-${d.slice(2, 4)}-${d.slice(4, 6)}`);
+    notes.push("importe y vencimiento leídos del código de barras");
+    if (label) {
+      crossChecked = toDigits(label).replace(/^0+/, "") === accountRef;
+      if (!crossChecked) {
+        notes.push(
+          `el número impreso (${toDigits(label).replace(/^0+/, "")}) no coincide con el código de barras`,
+        );
+      }
+    }
+  } else if (label) {
+    accountRef = toDigits(label).replace(/^0+/, "");
+    notes.push("sin código de barras legible; número tomado de la etiqueta");
+  }
+
+  if (amount == null) {
+    amount = money(firstMatch(text, [/TOTAL\s*A\s*PAGAR\s*[:;.]?\s*\$?\s*([\d,]+\.?\d*)/i]));
+  }
+  if (!dueDate) {
+    dueDate = parseDate(
+      firstMatch(text, [/L[IÍ]MITE\s*DE\s*PAGO\s*[:;.]?\s*(\d{1,2}\s+\w{3}\s+\d{2,4})/i]),
+    );
+  }
+
+  return {
+    provider: "CFE",
+    serviceKind: "ELECTRIC",
+    accountRef: accountRef || null,
+    cadastralKey: null,
+    amount,
+    dueDate,
+    period: firstMatch(text, [
+      /PERIODO\s*FACTURADO\s*[:;.]?\s*(\d{1,2}\s+\w{3}\s+\d{2}\s*-\s*\d{1,2}\s+\w{3}\s+\d{2})/i,
+    ]),
+    crossChecked,
+    notes,
+  };
+}
+
+// --- CESPT (water) ----------------------------------------------------------
+
+/**
+ * Two different layouts arrive under the same brand:
+ *   - the line-oriented "COMPROBANTE DE PAGO" (`Cuenta : 7604192`), and
+ *   - the tabular "RECIBO", where `No. DE CUENTA` is a column header.
+ * Line patterns are tried first; anything they miss falls through to the
+ * geometric read, which is what the tabular layout needs.
+ */
+function parseCespt(page: OcrPage): ParsedStatement {
+  const text = page.text;
+  const notes: string[] = [];
+
+  let account = firstMatch(text, [/Cuenta\s*[:;.]?\s*([0-9OIlSBD]{5,9})/i]);
+  if (!account) {
+    account = valueUnder(page, /^CUENTA$/i, { match: /^[0-9OIlSBD]{5,9}$/ });
+    if (account) notes.push("número de cuenta leído de la columna del recibo");
+  }
+
+  let clave = firstMatch(text, [/Cve\.?\s*Cat\.?\s*[:;.]?\s*([A-Z]{2}\s?[0-9OIlSBD]{6})/i]);
+  if (!clave) {
+    clave = valueUnder(page, /^CATASTRAL$/i, { match: /^[A-Z]{2}[0-9OIlSBD]{6}$/i });
+    if (clave) notes.push("clave catastral leída de la columna del recibo");
+  }
+
+  let due = firstMatch(text, [/Fecha\s*Venc\s*[:;.]?\s*(\d{2}\/\d{2}\/\d{4})/i]);
+  if (!due) due = valueUnder(page, /^VENCIMIENTO$/i, { match: /^\d{2}\/\d{2}\/\d{4}$/ });
+
+  const amount = money(
+    firstMatch(text, [
+      /TOTAL\s*[:;.]?\s*\$?\s*([\d,]+\.\d{2})/i,
+      /SALDO\s+CORRIENTE[^\n]*?([\d,]+\.\d{2})/i,
+    ]),
+  );
+
+  // Leading zeros are print padding here too: the RECIBO prints `0457341` for
+  // what DATMEX.agua holds as `457341`.
+  const accountRef = account ? toDigits(account).replace(/^0+/, "") : null;
+  const cadastralKey = clave
+    ? clave.replace(/\s/g, "").slice(0, 2).toUpperCase() +
+      toDigits(clave.replace(/\s/g, "").slice(2))
+    : null;
+
+  return {
+    provider: "CESPT",
+    serviceKind: "WATER",
+    accountRef: accountRef || null,
+    cadastralKey: cadastralKey || null,
+    amount,
+    dueDate: parseDate(due),
+    period: null,
+    crossChecked: null,
+    notes,
+  };
+}
+
+// --- TELNOR (telephone) -----------------------------------------------------
+
+function parseTelnor(page: OcrPage): ParsedStatement {
+  const text = page.text;
+  const notes: string[] = [];
+
+  const label = firstMatch(text, [
+    /Tel[eé]fono\s*[:;.]?\s*([0-9OIlSBD]{3}\s?[0-9OIlSBD]{3}\s?[0-9OIlSBD]{4})/i,
+  ]);
+  // The payment stub prints phone (10 digits) + amount in cents (9) + a check
+  // digit: `6646093444 000099900 7` for a $999.00 bill. Reading the amount as
+  // 10 digits swallows the check digit and inflates the figure 100-fold.
+  const barcode = text.match(/\b(\d{10})(\d{9})\d\b/);
+
+  let accountRef: string | null = null;
+  let crossChecked: boolean | null = null;
+
+  // The bill prints the number with its 664 Tijuana LADA; DATMEX stores the
+  // bare local 7 digits, so the LADA is dropped rather than the stored value
+  // being padded — padding would guess at an area code for the 500+ existing
+  // rows that never recorded one.
+  if (label) accountRef = toDigits(label).slice(-7);
+  if (barcode) {
+    const fromBarcode = barcode[1].slice(-7);
+    if (accountRef) {
+      crossChecked = fromBarcode === accountRef;
+      if (!crossChecked) notes.push("el teléfono impreso no coincide con el código de barras");
+    } else {
+      accountRef = fromBarcode;
+      notes.push("teléfono leído del código de barras");
+    }
+  }
+
+  let amount = money(firstMatch(text, [/Total\s*a\s*Pagar\s*[:;.]?\s*\$?\s*([\d,]+\.?\d{0,2})/i]));
+  if (amount == null && barcode) {
+    amount = Number(barcode[2]) / 100;
+    notes.push("importe leído del código de barras");
+  }
+
+  return {
+    provider: "TELNOR",
+    serviceKind: "TELEPHONE",
+    accountRef: accountRef || null,
+    cadastralKey: null,
+    amount,
+    dueDate: parseDate(
+      firstMatch(text, [/Pagar\s*antes\s*de\s*[:;.]?\s*(\d{2}-\w{3}-\d{4})/i]),
+    ),
+    period: firstMatch(text, [/Mes\s*de\s*Facturaci[oó]n\s*[:;.]?\s*(\w+)/i]),
+    crossChecked,
+    notes,
+  };
+}
+
+const PARSERS: Record<string, (page: OcrPage) => ParsedStatement> = {
+  CFE: parseCfe,
+  CESPT: parseCespt,
+  TELNOR: parseTelnor,
+};
+
+const EMPTY: ParsedStatement = {
+  provider: null,
+  serviceKind: null,
+  accountRef: null,
+  cadastralKey: null,
+  amount: null,
+  dueDate: null,
+  period: null,
+  crossChecked: null,
+  notes: [],
+};
+
+/** Detect the provider and run its parser. */
+export function parseStatement(page: OcrPage): ParsedStatement {
+  const provider = detectProvider(page.text);
+  if (!provider) return { ...EMPTY, notes: ["no se reconoció el proveedor"] };
+  return PARSERS[provider](page);
+}

apps/api/src/statements/statement-matcher.service.ts

@@ -0,0 +1,199 @@
+import { Injectable } from "@nestjs/common";
+import type { ServiceKind } from "@jorgecuadros/database";
+import { PrismaService } from "../prisma/prisma.service";
+import type { ParsedStatement } from "./parsers/statement-parser";
+
+export interface MatchResult {
+  propertyServiceId: string | null;
+  customerId: string | null;
+  /** Why it landed here — shown in the review queue verbatim. */
+  note: string;
+  /** True only for an unambiguous hit on the scoped field. */
+  confident: boolean;
+  /** Populated when more than one service claims the same number. */
+  candidates: { propertyServiceId: string; customerId: string; customerName: string }[];
+}
+
+/**
+ * Resolves a parsed statement to the customer who should be billed for it.
+ *
+ * Two rules govern everything here.
+ *
+ * **Match on one scoped field, never fuzzily across all identifiers.** Each
+ * service kind has exactly one column its statements print, and only that
+ * column is consulted. A blanket search over accountNumber/meterNumber/route
+ * would let a water account number collide with an unrelated phone number, and
+ * the resulting mis-post would look perfectly ordinary in the ledger.
+ *
+ * **Never match on the customer name.** The name on a utility bill is the
+ * account's registrant, which drifts from the current owner and is often years
+ * stale — one sample CESPT receipt is printed to "ARNAIZ ROSAS ELSA AURORA"
+ * for an account this office holds under "CATT, RANDY", who is not the same
+ * person. Names are displayed for the reviewer to sanity-check, and are never
+ * an input to matching.
+ */
+@Injectable()
+export class StatementMatcherService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  /** Which PropertyService column a given kind's statements actually print. */
+  private fieldFor(kind: ServiceKind): "accountNumber" | "meterNumber" | null {
+    switch (kind) {
+      case "ELECTRIC": // CFE "NO. DE SERVICIO" -> DATMEX.rpu
+      case "WATER": // CESPT "Cuenta" / "No. DE CUENTA" -> DATMEX.agua
+      case "TELEPHONE": // Telnor "Teléfono" (LADA stripped) -> DATMEX.telefono
+      case "FEDERAL_ZONE":
+      case "CABLE":
+        return "accountNumber";
+      case "GAS": // no account column in DATMEX; the number lived in notes
+        return "meterNumber";
+      // PROPERTY_TAX deliberately has no scoped column: what its
+      // accountNumber holds is DATMEX.predial, which is neither unique nor
+      // printed on any statement. Predial bills match on the clave catastral
+      // alone — see matchByCadastralKey.
+      default:
+        return null;
+    }
+  }
+
+  async match(parsed: ParsedStatement, expectedKind: ServiceKind): Promise<MatchResult> {
+    const kind = parsed.serviceKind ?? expectedKind;
+
+    // The uploader labels a batch with one service kind. If the parser reads a
+    // page as a different provider, that is a mis-sorted page, not a match —
+    // posting it would book a phone bill as a water charge.
+    if (parsed.serviceKind && parsed.serviceKind !== expectedKind) {
+      return this.unmatched(
+        `la página parece de ${parsed.provider} (${parsed.serviceKind}) pero el lote es de ${expectedKind}`,
+      );
+    }
+
+    const field = this.fieldFor(kind);
+
+    if (field && parsed.accountRef) {
+      const hit = await this.byServiceField(kind, field, parsed.accountRef);
+      if (hit) return hit;
+    }
+
+    // Secondary key. The clave catastral is printed on CESPT bills as well as
+    // predial ones, so it rescues a page whose account number did not OCR —
+    // which happened on real samples, where the clave read cleanly and the
+    // account number did not.
+    if (parsed.cadastralKey) {
+      const hit = await this.byCadastralKey(kind, parsed.cadastralKey);
+      if (hit) return hit;
+    }
+
+    if (!field && !parsed.cadastralKey) {
+      return this.unmatched(
+        kind === "PROPERTY_TAX"
+          ? "el predial sólo se puede identificar por clave catastral y no se leyó ninguna"
+          : `no hay campo de búsqueda definido para ${kind}`,
+      );
+    }
+    return this.unmatched(
+      parsed.accountRef
+        ? `no se encontró ningún servicio de ${kind} con la referencia ${parsed.accountRef}`
+        : "no se pudo leer la referencia de la cuenta",
+    );
+  }
+
+  private async byServiceField(
+    kind: ServiceKind,
+    field: "accountNumber" | "meterNumber",
+    ref: string,
+  ): Promise<MatchResult | null> {
+    const rows = await this.prisma.propertyService.findMany({
+      where: { kind, [field]: ref },
+      select: {
+        id: true,
+        property: {
+          select: { customerId: true, customer: { select: { name: true } } },
+        },
+      },
+    });
+    if (rows.length === 0) return null;
+
+    const candidates = rows.map((r) => ({
+      propertyServiceId: r.id,
+      customerId: r.property.customerId,
+      customerName: r.property.customer.name,
+    }));
+
+    // Duplicate account numbers do occur in the legacy data (the office's own
+    // DUPLICADOS report existed for a reason), so every candidate is surfaced
+    // for the reviewer to choose rather than one being picked arbitrarily.
+    if (rows.length > 1) {
+      return {
+        propertyServiceId: null,
+        customerId: null,
+        note: `${rows.length} servicios comparten la referencia ${ref}`,
+        confident: false,
+        candidates,
+      };
+    }
+
+    return {
+      propertyServiceId: candidates[0].propertyServiceId,
+      customerId: candidates[0].customerId,
+      note: `coincidencia exacta por ${field === "accountNumber" ? "número de cuenta" : "medidor"} ${ref}`,
+      confident: true,
+      candidates,
+    };
+  }
+
+  private async byCadastralKey(
+    kind: ServiceKind,
+    key: string,
+  ): Promise<MatchResult | null> {
+    const props = await this.prisma.property.findMany({
+      where: { cadastralKey: key },
+      select: {
+        customerId: true,
+        customer: { select: { name: true } },
+        services: { where: { kind }, select: { id: true } },
+      },
+    });
+    if (props.length === 0) return null;
+
+    const candidates = props.flatMap((p) =>
+      (p.services.length ? p.services.map((s) => s.id) : [null]).map((sid) => ({
+        propertyServiceId: sid as string,
+        customerId: p.customerId,
+        customerName: p.customer.name,
+      })),
+    );
+
+    if (candidates.length > 1) {
+      return {
+        propertyServiceId: null,
+        customerId: null,
+        note: `${candidates.length} propiedades comparten la clave catastral ${key}`,
+        confident: false,
+        candidates,
+      };
+    }
+
+    // The clave identifies the property with certainty, but it is a *secondary*
+    // key: it was not the number the statement was issued against. Left for
+    // review so the confirm also teaches the matcher the account number, rather
+    // than the same page needing the fallback again next month.
+    return {
+      propertyServiceId: candidates[0].propertyServiceId ?? null,
+      customerId: candidates[0].customerId,
+      note: `identificado por clave catastral ${key}; confirme para registrar también el número de cuenta`,
+      confident: false,
+      candidates,
+    };
+  }
+
+  private unmatched(note: string): MatchResult {
+    return {
+      propertyServiceId: null,
+      customerId: null,
+      note,
+      confident: false,
+      candidates: [],
+    };
+  }
+}

apps/api/src/statements/statement.dto.ts

@@ -0,0 +1,52 @@
+import {
+  IsBoolean,
+  IsEnum,
+  IsInt,
+  IsNumber,
+  IsOptional,
+  IsString,
+  MinLength,
+} from "class-validator";
+import { Currency, ServiceKind, StatementDocumentStatus } from "@jorgecuadros/database";
+
+export class CreateStatementBatchDto {
+  @IsEnum(ServiceKind) serviceKind!: ServiceKind;
+  @IsOptional() @IsString() label?: string;
+}
+
+/** Staff correction of one document's extracted fields or its match. */
+export class ReviewDocumentDto {
+  @IsOptional() @IsString() accountRef?: string;
+  @IsOptional() @IsNumber() amount?: number;
+  @IsOptional() @IsString() period?: string;
+  @IsOptional() @IsString() dueDate?: string;
+  @IsOptional() @IsString() matchedPropertyServiceId?: string;
+  @IsOptional() @IsString() matchedCustomerId?: string;
+  // Restricted to the review-reachable states: a client cannot declare a
+  // document POSTED, because only a successful ledger write may do that.
+  @IsOptional()
+  @IsEnum(StatementDocumentStatus)
+  status?: Extract<StatementDocumentStatus, "MATCHED" | "NEEDS_REVIEW" | "CONFIRMED">;
+}
+
+/**
+ * Post a batch's confirmed documents. The check-level fields are shared by
+ * every line, exactly as on the manual batch-capture screen — an OCR batch is
+ * still "these receipts, paid by this check".
+ */
+export class ConfirmBatchDto {
+  @IsString() @MinLength(1) checkNumber!: string;
+  @IsString() @MinLength(1) transactionDate!: string;
+  @IsOptional() @IsEnum(Currency) currency?: Currency;
+  /** Overrides the concept derived from the batch's service kind. */
+  @IsOptional() @IsString() typeId?: string;
+  /** Post as outstanding (sin fondos) — captured but not yet funded. */
+  @IsOptional() @IsBoolean() outstanding?: boolean;
+  /** Also post documents a reviewer explicitly marked CONFIRMED. */
+  @IsOptional() @IsBoolean() includeReviewed?: boolean;
+}
+
+export class ListBatchesQuery {
+  @IsOptional() @IsInt() page?: number;
+  @IsOptional() @IsInt() pageSize?: number;
+}

apps/api/src/statements/statements.controller.ts

@@ -0,0 +1,162 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  Patch,
+  Post,
+  Query,
+  Req,
+  Res,
+  StreamableFile,
+  UploadedFiles,
+  UseGuards,
+  UseInterceptors,
+} from "@nestjs/common";
+import { FilesInterceptor } from "@nestjs/platform-express";
+import type { ServiceKind, StatementDocumentStatus } from "@jorgecuadros/database";
+import type { Request, Response } from "express";
+import { AuthenticatedGuard } from "../auth/authenticated.guard";
+import { AbilityGuard } from "../auth/ability.guard";
+import { RequireAbility } from "../auth/require-ability.decorator";
+import { AuditService } from "../common/audit.service";
+import type { UploadedFileLike } from "../storage/upload-file";
+import { StatementsService } from "./statements.service";
+import { ConfirmBatchDto, ReviewDocumentDto } from "./statement.dto";
+
+/**
+ * Statement OCR intake (RECEIPT_CAPTURE_SPEC §2).
+ *
+ * Nothing here writes to the ledger directly — confirming a batch delegates to
+ * BillingService, so an OCR-captured charge is indistinguishable from a
+ * hand-keyed one except for its `captureSource`.
+ */
+@Controller("statements")
+@UseGuards(AuthenticatedGuard, AbilityGuard)
+export class StatementsController {
+  constructor(
+    private readonly statements: StatementsService,
+    private readonly audit: AuditService,
+  ) {}
+
+  private actingId(req: Request): string {
+    return (req.user as { id: string } | undefined)?.id ?? "";
+  }
+
+  /**
+   * Whether this deployment can ingest scans at all — the UI hides automatic
+   * capture without it. Both halves are needed: OCR to read the page, object
+   * storage to keep it.
+   */
+  @Get("status")
+  async status() {
+    return {
+      ocrAvailable: await this.statements.ocrAvailable(),
+      storageAvailable: this.statements.storageAvailable(),
+    };
+  }
+
+  @Get("batches")
+  listBatches(@Query("page") page?: string, @Query("pageSize") pageSize?: string) {
+    return this.statements.listBatches(
+      Math.max(1, Number(page) || 1),
+      Math.min(100, Math.max(1, Number(pageSize) || 25)),
+    );
+  }
+
+  @Get("batches/:id")
+  getBatch(@Param("id") id: string) {
+    return this.statements.getBatch(id);
+  }
+
+  @Get("batches/:id/documents")
+  listDocuments(@Param("id") id: string, @Query("status") status?: string) {
+    return this.statements.listDocuments(
+      id,
+      (status || undefined) as StatementDocumentStatus | undefined,
+    );
+  }
+
+  /** The rendered page, so a reviewer can compare it against what was read. */
+  @Get("documents/:id/page")
+  async pageImage(@Param("id") id: string, @Res({ passthrough: true }) res: Response) {
+    const { stream, contentType, contentLength } = await this.statements.pageImage(id);
+    res.set({
+      "Content-Type": contentType ?? "image/png",
+      ...(contentLength ? { "Content-Length": String(contentLength) } : {}),
+    });
+    return new StreamableFile(stream);
+  }
+
+  // --- writes ---------------------------------------------------------------
+
+  @Post("batches")
+  @RequireAbility("statement:ingest")
+  @UseInterceptors(
+    // A month of one company's statements is a handful of multi-page scans;
+    // 25 files at 50MB covers that with room to spare.
+    FilesInterceptor("files", 25, { limits: { fileSize: 50 * 1024 * 1024 } }),
+  )
+  async createBatch(
+    @UploadedFiles() files: UploadedFileLike[] | undefined,
+    @Query("serviceKind") serviceKind: ServiceKind,
+    @Query("label") label: string | undefined,
+    @Req() req: Request,
+  ) {
+    const batch = await this.statements.createBatch(
+      files ?? [],
+      serviceKind,
+      this.actingId(req),
+      label,
+    );
+    void this.audit.log(this.actingId(req), "statement.batch.create", {
+      batchId: batch.id,
+      serviceKind,
+      fileCount: batch.fileCount,
+    });
+    return batch;
+  }
+
+  @Patch("documents/:id")
+  @RequireAbility("statement:review")
+  async review(
+    @Param("id") id: string,
+    @Body() dto: ReviewDocumentDto,
+    @Req() req: Request,
+  ) {
+    const doc = await this.statements.review(id, dto, this.actingId(req));
+    void this.audit.log(this.actingId(req), "statement.document.review", {
+      documentId: id,
+      status: doc.status,
+    });
+    return doc;
+  }
+
+  @Post("documents/:id/reject")
+  @RequireAbility("statement:review")
+  async reject(@Param("id") id: string, @Req() req: Request) {
+    const doc = await this.statements.reject(id, this.actingId(req));
+    void this.audit.log(this.actingId(req), "statement.document.reject", {
+      documentId: id,
+    });
+    return doc;
+  }
+
+  /** Post every matched document in the batch, against one check. */
+  @Post("batches/:id/confirm")
+  @RequireAbility("statement:review")
+  async confirm(
+    @Param("id") id: string,
+    @Body() dto: ConfirmBatchDto,
+    @Req() req: Request,
+  ) {
+    const result = await this.statements.confirmBatch(id, dto, this.actingId(req));
+    void this.audit.log(this.actingId(req), "statement.batch.confirm", {
+      batchId: id,
+      posted: result.posted,
+      total: result.total,
+      checkNumber: dto.checkNumber,
+    });
+    return result;
+  }
+}

apps/api/src/statements/statements.module.ts

@@ -0,0 +1,23 @@
+import { Module } from "@nestjs/common";
+import { BillingModule } from "../billing/billing.module";
+import { StatementsController } from "./statements.controller";
+import { StatementsService } from "./statements.service";
+import { StatementMatcherService } from "./statement-matcher.service";
+import { OCR_PROVIDER } from "./ocr/ocr.provider";
+import { TesseractOcrProvider } from "./ocr/tesseract.provider";
+
+/**
+ * The concrete OCR engine is bound here and nowhere else — everything
+ * downstream depends on the OcrProvider interface, so swapping Tesseract for a
+ * managed extraction API is a one-line change in this file.
+ */
+@Module({
+  imports: [BillingModule],
+  controllers: [StatementsController],
+  providers: [
+    StatementsService,
+    StatementMatcherService,
+    { provide: OCR_PROVIDER, useClass: TesseractOcrProvider },
+  ],
+})
+export class StatementsModule {}

apps/api/src/statements/statements.service.ts

@@ -0,0 +1,470 @@
+import {
+  BadRequestException,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from "@nestjs/common";
+import {
+  Prisma,
+  type ServiceKind,
+  type StatementDocumentStatus,
+} from "@jorgecuadros/database";
+import { PrismaService } from "../prisma/prisma.service";
+import { StorageService } from "../storage/storage.service";
+import { BillingService } from "../billing/billing.service";
+import type { UploadedFileLike } from "../storage/upload-file";
+import { OCR_PROVIDER, type OcrProvider } from "./ocr/ocr.provider";
+import { parseStatement } from "./parsers/statement-parser";
+import { StatementMatcherService } from "./statement-matcher.service";
+import type { ConfirmBatchDto, ReviewDocumentDto } from "./statement.dto";
+
+/**
+ * Default ledger concept per service kind. The names are the legacy
+ * `TYPE OF TRX` values already in `type_transactions`, resolved by name once
+ * per confirm rather than hard-coded as ids, which differ per environment.
+ */
+const CONCEPT_BY_KIND: Partial<Record<ServiceKind, string>> = {
+  ELECTRIC: "ELECTRIC",
+  WATER: "WATER",
+  TELEPHONE: "TELEPHONE",
+  GAS: "GAS BUTANO",
+  PROPERTY_TAX: "PROPERTY TAXES",
+  FEDERAL_ZONE: "FEDERAL ZONE",
+  CABLE: "CABLE",
+};
+
+/** Statuses a document can still be worked on from. */
+const OPEN: StatementDocumentStatus[] = ["NEEDS_REVIEW", "MATCHED", "CONFIRMED"];
+
+@Injectable()
+export class StatementsService {
+  private readonly logger = new Logger(StatementsService.name);
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly storage: StorageService,
+    private readonly billing: BillingService,
+    private readonly matcher: StatementMatcherService,
+    @Inject(OCR_PROVIDER) private readonly ocr: OcrProvider,
+  ) {}
+
+  ocrAvailable(): Promise<boolean> {
+    return this.ocr.available();
+  }
+
+  /** Scans are stored as blobs, so no object storage means no intake. */
+  storageAvailable(): boolean {
+    return this.storage.available;
+  }
+
+  // --- ingest ---------------------------------------------------------------
+
+  /**
+   * Accept a batch of scanned PDFs and start processing.
+   *
+   * Processing is kicked off but deliberately not awaited: 300 pages of OCR is
+   * minutes of CPU, far past any sane HTTP timeout. The caller gets the batch
+   * id immediately and polls its status, which is also what lets the review
+   * queue show partial progress.
+   */
+  async createBatch(
+    files: UploadedFileLike[],
+    serviceKind: ServiceKind,
+    uploadedById: string,
+    label?: string,
+  ) {
+    if (!files?.length) throw new BadRequestException("No se recibió ningún archivo.");
+    if (!(await this.ocr.available())) {
+      throw new BadRequestException(
+        "El servidor no tiene OCR instalado; no se pueden procesar recibos.",
+      );
+    }
+    // Checked here rather than at the first `put`, which would only surface as
+    // a FAILED batch minutes later.
+    if (!this.storage.available) {
+      throw new BadRequestException(
+        "El almacenamiento de documentos no está configurado; no se pueden " +
+          "guardar los recibos escaneados.",
+      );
+    }
+
+    const batch = await this.prisma.statementBatch.create({
+      data: { serviceKind, uploadedById, label, fileCount: files.length },
+    });
+
+    // Buffers are held for the background pass; the request's own copies would
+    // otherwise be garbage once the response is sent.
+    const copies = files.map((f) => ({ buffer: f.buffer, name: f.originalname }));
+    void this.process(batch.id, copies, serviceKind).catch(async (err) => {
+      this.logger.error(`Batch ${batch.id} failed: ${(err as Error).message}`);
+      await this.prisma.statementBatch.update({
+        where: { id: batch.id },
+        data: { status: "FAILED", error: (err as Error).message },
+      });
+    });
+
+    return batch;
+  }
+
+  /** Render → OCR → parse → match, one document row per page. */
+  private async process(
+    batchId: string,
+    files: { buffer: Buffer; name?: string }[],
+    serviceKind: ServiceKind,
+  ) {
+    await this.prisma.statementBatch.update({
+      where: { id: batchId },
+      data: { status: "PROCESSING" },
+    });
+
+    let pageNumber = 0;
+    for (const file of files) {
+      // The source PDF is kept as well as the page images: it is the artifact
+      // the office actually received, and the only way to re-run a corrected
+      // parser over the original later.
+      const sourceKey = `statement/${batchId}/source-${pageNumber + 1}.pdf`;
+      await this.storage.put(sourceKey, file.buffer, "application/pdf");
+
+      const pages = await this.ocr.renderPages(file.buffer);
+      for (const image of pages) {
+        pageNumber += 1;
+        const storageKey = `statement/${batchId}/page-${pageNumber}.png`;
+        await this.storage.put(storageKey, image, "image/png");
+
+        try {
+          const ocr = await this.ocr.recognize(image);
+          const parsed = parseStatement(ocr);
+          const match = await this.matcher.match(parsed, serviceKind);
+
+          const notes = [...parsed.notes, match.note].filter(Boolean);
+          // A confident field match is only trusted when nothing contradicts
+          // it: a barcode that disagrees with the printed number means one of
+          // the two was misread, and which one is a judgement call.
+          const trusted = match.confident && parsed.crossChecked !== false;
+
+          await this.prisma.statementDocument.create({
+            data: {
+              batchId,
+              pageNumber,
+              storageKey,
+              status: trusted ? "MATCHED" : "NEEDS_REVIEW",
+              ocrRawText: ocr.text,
+              ocrConfidence: new Prisma.Decimal(ocr.confidence.toFixed(3)),
+              provider: parsed.provider,
+              extractedAccountRef: parsed.accountRef,
+              extractedAmount:
+                parsed.amount != null ? new Prisma.Decimal(parsed.amount) : null,
+              extractedPeriod: parsed.period,
+              extractedDueDate: parsed.dueDate,
+              extractedCadastralKey: parsed.cadastralKey,
+              matchedPropertyServiceId: match.propertyServiceId,
+              matchedCustomerId: match.customerId,
+              matchNote: notes.join("; ").slice(0, 190),
+            },
+          });
+        } catch (err) {
+          // One unreadable page must not abandon the other 299.
+          await this.prisma.statementDocument.create({
+            data: {
+              batchId,
+              pageNumber,
+              storageKey,
+              status: "OCR_FAILED",
+              matchNote: (err as Error).message.slice(0, 190),
+            },
+          });
+        }
+      }
+    }
+
+    await this.prisma.statementBatch.update({
+      where: { id: batchId },
+      data: { status: "READY_FOR_REVIEW" },
+    });
+  }
+
+  // --- reads ----------------------------------------------------------------
+
+  async listBatches(page: number, pageSize: number) {
+    const [total, items] = await this.prisma.$transaction([
+      this.prisma.statementBatch.count(),
+      this.prisma.statementBatch.findMany({
+        orderBy: { createdAt: "desc" },
+        skip: (page - 1) * pageSize,
+        take: pageSize,
+        include: {
+          uploadedBy: { select: { name: true } },
+          _count: { select: { documents: true } },
+        },
+      }),
+    ]);
+    return { items, total, page, pageSize, pageCount: Math.ceil(total / pageSize) };
+  }
+
+  async getBatch(id: string) {
+    const batch = await this.prisma.statementBatch.findUnique({
+      where: { id },
+      include: { uploadedBy: { select: { name: true } } },
+    });
+    if (!batch) throw new NotFoundException("Lote no encontrado.");
+
+    const counts = await this.prisma.statementDocument.groupBy({
+      by: ["status"],
+      where: { batchId: id },
+      _count: { _all: true },
+    });
+    const totals = await this.prisma.statementDocument.aggregate({
+      where: { batchId: id, status: { in: OPEN } },
+      _sum: { extractedAmount: true },
+    });
+
+    return {
+      ...batch,
+      byStatus: Object.fromEntries(counts.map((c) => [c.status, c._count._all])),
+      pendingTotal: totals._sum.extractedAmount?.toFixed(2) ?? "0.00",
+    };
+  }
+
+  async listDocuments(batchId: string, status?: StatementDocumentStatus) {
+    return this.prisma.statementDocument.findMany({
+      where: { batchId, ...(status ? { status } : {}) },
+      orderBy: { pageNumber: "asc" },
+      include: {
+        matchedCustomer: { select: { id: true, name: true } },
+        matchedPropertyService: {
+          select: {
+            id: true,
+            kind: true,
+            accountNumber: true,
+            meterNumber: true,
+            property: { select: { id: true, addressLine1: true } },
+          },
+        },
+      },
+    });
+  }
+
+  /** The rendered page image, so a reviewer can read what the parser read. */
+  async pageImage(documentId: string) {
+    const doc = await this.prisma.statementDocument.findUnique({
+      where: { id: documentId },
+      select: { storageKey: true },
+    });
+    if (!doc) throw new NotFoundException("Documento no encontrado.");
+    return this.storage.getStream(doc.storageKey);
+  }
+
+  // --- review ---------------------------------------------------------------
+
+  /** Staff correction of an extracted field or of the match itself. */
+  async review(id: string, dto: ReviewDocumentDto, reviewedById: string) {
+    const doc = await this.prisma.statementDocument.findUnique({ where: { id } });
+    if (!doc) throw new NotFoundException("Documento no encontrado.");
+    if (doc.status === "POSTED") {
+      throw new BadRequestException("Este documento ya fue registrado.");
+    }
+
+    // Changing the service implies its owner; deriving the customer here rather
+    // than trusting a client-supplied pair is what stops a page being posted to
+    // one customer's ledger against another customer's service.
+    let matchedCustomerId = doc.matchedCustomerId;
+    let matchedPropertyServiceId = dto.matchedPropertyServiceId ?? undefined;
+
+    if (dto.matchedPropertyServiceId) {
+      const svc = await this.prisma.propertyService.findUnique({
+        where: { id: dto.matchedPropertyServiceId },
+        select: { property: { select: { customerId: true } } },
+      });
+      if (!svc) throw new BadRequestException("Servicio no encontrado.");
+      matchedCustomerId = svc.property.customerId;
+    } else if (dto.matchedCustomerId) {
+      matchedCustomerId = dto.matchedCustomerId;
+
+      // A reviewer picks a *customer*, not one of their service rows. Without
+      // a service the posting still works, but the confirmed reference has
+      // nowhere to be written back, so the same account would land in review
+      // again next month — which is exactly the behaviour that is supposed to
+      // make gas (whose numbers the migration never populated) a one-time cost.
+      // So: if the batch's service kind resolves to exactly one of that
+      // customer's services that has no reference yet, attach it. Exactly one
+      // — with two candidates there is no way to tell which meter or line the
+      // bill belongs to, and guessing would write a real number onto the wrong
+      // service.
+      const batch = await this.prisma.statementBatch.findUnique({
+        where: { id: doc.batchId },
+        select: { serviceKind: true },
+      });
+      if (batch) {
+        const field = batch.serviceKind === "GAS" ? "meterNumber" : "accountNumber";
+        const blank = await this.prisma.propertyService.findMany({
+          where: {
+            kind: batch.serviceKind,
+            [field]: null,
+            property: { customerId: matchedCustomerId },
+          },
+          select: { id: true },
+          take: 2,
+        });
+        if (blank.length === 1) matchedPropertyServiceId = blank[0].id;
+      }
+    }
+
+    return this.prisma.statementDocument.update({
+      where: { id },
+      data: {
+        extractedAccountRef: dto.accountRef ?? undefined,
+        extractedAmount:
+          dto.amount != null ? new Prisma.Decimal(dto.amount) : undefined,
+        extractedPeriod: dto.period ?? undefined,
+        extractedDueDate: dto.dueDate ? new Date(dto.dueDate) : undefined,
+        matchedPropertyServiceId,
+        matchedCustomerId,
+        status: dto.status ?? "MATCHED",
+        reviewedById,
+        reviewedAt: new Date(),
+      },
+    });
+  }
+
+  async reject(id: string, reviewedById: string) {
+    const doc = await this.prisma.statementDocument.findUnique({ where: { id } });
+    if (!doc) throw new NotFoundException("Documento no encontrado.");
+    if (doc.status === "POSTED") {
+      throw new BadRequestException("Este documento ya fue registrado.");
+    }
+    return this.prisma.statementDocument.update({
+      where: { id },
+      data: { status: "REJECTED", reviewedById, reviewedAt: new Date() },
+    });
+  }
+
+  // --- posting --------------------------------------------------------------
+
+  /**
+   * Post every confirmable document in a batch to the ledger.
+   *
+   * This goes through `BillingService.createBatch` — the same method the manual
+   * "Editor" screen uses — rather than writing `Transaction` rows directly, so
+   * OCR-sourced and hand-keyed receipts share one write path, one validation
+   * path and one audit trail. `source: "OCR"` and a per-line `captureRef` of
+   * the document id give the duplicate-post guard something to key on, so a
+   * batch confirmed twice cannot double-charge anyone.
+   */
+  async confirmBatch(batchId: string, dto: ConfirmBatchDto, reviewedById: string) {
+    const batch = await this.prisma.statementBatch.findUnique({
+      where: { id: batchId },
+    });
+    if (!batch) throw new NotFoundException("Lote no encontrado.");
+
+    const docs = await this.prisma.statementDocument.findMany({
+      where: {
+        batchId,
+        status: { in: dto.includeReviewed ? ["MATCHED", "CONFIRMED"] : ["MATCHED"] },
+        matchedCustomerId: { not: null },
+      },
+      orderBy: { pageNumber: "asc" },
+    });
+    if (!docs.length) {
+      throw new BadRequestException("No hay documentos listos para registrar.");
+    }
+
+    const missing = docs.filter((d) => d.extractedAmount == null);
+    if (missing.length) {
+      throw new BadRequestException(
+        `Falta el importe en ${missing.length} documento(s): página(s) ` +
+          missing.map((d) => d.pageNumber).join(", "),
+      );
+    }
+
+    const typeId = dto.typeId ?? (await this.conceptFor(batch.serviceKind));
+
+    const result = await this.billing.createBatch(
+      {
+        domain: "UTILITY",
+        transactionDate: dto.transactionDate,
+        checkNumber: dto.checkNumber,
+        currency: dto.currency ?? "MXN",
+        typeId,
+        lines: docs.map((d) => ({
+          customerId: d.matchedCustomerId!,
+          // Charges are negative in this ledger: a negative amount is what the
+          // customer owes. The parser reads the printed (positive) figure, so
+          // the sign is applied here, at the single point where a statement
+          // becomes a ledger row.
+          amount: -Math.abs(Number(d.extractedAmount)),
+          reference: d.extractedAccountRef ?? undefined,
+          period: d.extractedPeriod ?? undefined,
+          outstanding: dto.outstanding ?? false,
+        })),
+      },
+      { source: "OCR", refs: docs.map((d) => d.id) },
+    );
+
+    // `items[i]` is positionally parallel to `lines[i]` (seam guarantee 1), so
+    // the created rows zip straight back onto the documents that produced them.
+    await this.prisma.$transaction(
+      docs.map((d, i) =>
+        this.prisma.statementDocument.update({
+          where: { id: d.id },
+          data: {
+            status: "POSTED",
+            postedTransactionId: result.items[i].id,
+            reviewedById,
+            reviewedAt: new Date(),
+          },
+        }),
+      ),
+    );
+
+    // Teach the matcher. When a document was matched by clave catastral or by
+    // hand because the scoped field was blank, writing the reference back means
+    // next month's statement for the same account matches on its own — this is
+    // what turns gas (whose numbers the migration never populated) from a
+    // permanent review queue into a one-time cost.
+    await this.learnAccountRefs(docs, batch.serviceKind);
+
+    await this.closeIfDone(batchId);
+
+    return { posted: result.count, total: result.total, checkNumber: dto.checkNumber };
+  }
+
+  /** Write a confirmed reference onto a service that had none. */
+  private async learnAccountRefs(
+    docs: { matchedPropertyServiceId: string | null; extractedAccountRef: string | null }[],
+    kind: ServiceKind,
+  ) {
+    const field = kind === "GAS" ? "meterNumber" : "accountNumber";
+    for (const d of docs) {
+      if (!d.matchedPropertyServiceId || !d.extractedAccountRef) continue;
+      await this.prisma.propertyService.updateMany({
+        // Only fills a hole — never overwrites a number already on file, which
+        // would let one misread page rewrite good reference data.
+        where: { id: d.matchedPropertyServiceId, [field]: null },
+        data: { [field]: d.extractedAccountRef },
+      });
+    }
+  }
+
+  private async closeIfDone(batchId: string) {
+    const open = await this.prisma.statementDocument.count({
+      where: { batchId, status: { in: OPEN } },
+    });
+    if (open === 0) {
+      await this.prisma.statementBatch.update({
+        where: { id: batchId },
+        data: { status: "COMPLETED", completedAt: new Date() },
+      });
+    }
+  }
+
+  private async conceptFor(kind: ServiceKind): Promise<string | undefined> {
+    const name = CONCEPT_BY_KIND[kind];
+    if (!name) return undefined;
+    const row = await this.prisma.typeTransaction.findFirst({
+      where: { nameEn: name },
+      select: { id: true },
+    });
+    return row?.id;
+  }
+}

apps/api/src/storage/storage.module.ts

@@ -0,0 +1,10 @@
+import { Global, Module } from "@nestjs/common";
+import { StorageService } from "./storage.service";
+
+/** Global so any feature module can inject StorageService without re-importing. */
+@Global()
+@Module({
+  providers: [StorageService],
+  exports: [StorageService],
+})
+export class StorageModule {}

apps/api/src/storage/storage.service.ts

@@ -0,0 +1,132 @@
+import {
+  Injectable,
+  Logger,
+  OnModuleInit,
+  ServiceUnavailableException,
+} from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import {
+  CreateBucketCommand,
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadBucketCommand,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import type { Readable } from "node:stream";
+
+/**
+ * S3 / MinIO object storage for document blobs. MySQL keeps only the pointer
+ * (`storageKey`) + metadata; the bytes live here. Same bucket the migration's
+ * `blob_extract.py` writes to, so keys stay under the `service/…` and
+ * `policy/…` prefixes it established.
+ *
+ * Env (see deploy/.env.dev): S3_ENDPOINT, S3_BUCKET, and creds — S3_ACCESS_KEY
+ * / S3_SECRET_KEY, falling back to MINIO_ROOT_USER / MINIO_ROOT_PASSWORD so a
+ * single MinIO credential set drives both the migration and the API.
+ */
+@Injectable()
+export class StorageService implements OnModuleInit {
+  private readonly logger = new Logger(StorageService.name);
+  private readonly client: S3Client | null;
+  readonly bucket: string;
+
+  constructor(config: ConfigService) {
+    const endpoint = config.get<string>("S3_ENDPOINT");
+    this.bucket = config.get<string>("S3_BUCKET") ?? "jorgecuadros-documents";
+    const accessKeyId =
+      config.get<string>("S3_ACCESS_KEY") ?? config.get<string>("MINIO_ROOT_USER");
+    const secretAccessKey =
+      config.get<string>("S3_SECRET_KEY") ?? config.get<string>("MINIO_ROOT_PASSWORD");
+
+    if (!endpoint || !accessKeyId || !secretAccessKey) {
+      this.logger.warn(
+        "Object storage not configured (missing S3_ENDPOINT / credentials); " +
+          "document upload & download are disabled.",
+      );
+      this.client = null;
+      return;
+    }
+
+    this.client = new S3Client({
+      endpoint,
+      region: config.get<string>("S3_REGION") ?? "us-east-1",
+      credentials: { accessKeyId, secretAccessKey },
+      forcePathStyle: true, // MinIO needs path-style addressing
+    });
+  }
+
+  /** Best-effort bucket check on boot; never blocks API startup. */
+  async onModuleInit() {
+    if (!this.client) return;
+    try {
+      await this.client.send(new HeadBucketCommand({ Bucket: this.bucket }));
+    } catch {
+      try {
+        await this.client.send(new CreateBucketCommand({ Bucket: this.bucket }));
+        this.logger.log(`Created bucket "${this.bucket}".`);
+      } catch (err) {
+        this.logger.warn(
+          `Could not verify/create bucket "${this.bucket}": ${(err as Error).message}`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Whether the deployment has object storage at all. Callers use this to
+   * refuse work up front instead of failing halfway through — a recibo batch
+   * that dies on its first `put` leaves a FAILED batch and no explanation the
+   * office can act on.
+   */
+  get available(): boolean {
+    return this.client !== null;
+  }
+
+  private require(): S3Client {
+    if (!this.client) {
+      throw new ServiceUnavailableException(
+        "El almacenamiento de documentos no está configurado.",
+      );
+    }
+    return this.client;
+  }
+
+  async put(key: string, body: Buffer, contentType?: string): Promise<void> {
+    await this.require().send(
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        Body: body,
+        ContentType: contentType,
+      }),
+    );
+  }
+
+  async getStream(key: string): Promise<{
+    stream: Readable;
+    contentType?: string;
+    contentLength?: number;
+  }> {
+    const out = await this.require().send(
+      new GetObjectCommand({ Bucket: this.bucket, Key: key }),
+    );
+    return {
+      stream: out.Body as Readable,
+      contentType: out.ContentType,
+      contentLength: out.ContentLength,
+    };
+  }
+
+  /** Best-effort blob delete; a missing object is not an error. */
+  async delete(key: string): Promise<void> {
+    if (!this.client) return;
+    try {
+      await this.client.send(
+        new DeleteObjectCommand({ Bucket: this.bucket, Key: key }),
+      );
+    } catch (err) {
+      this.logger.warn(`Failed to delete blob "${key}": ${(err as Error).message}`);
+    }
+  }
+}

apps/api/src/storage/upload-file.ts

@@ -0,0 +1,32 @@
+import { extname } from "node:path";
+
+/** Multer file shape we rely on (subset of Express.Multer.File). */
+export interface UploadedFileLike {
+  buffer: Buffer;
+  originalname?: string;
+  mimetype?: string;
+  size?: number;
+}
+
+const MIME_EXT: Record<string, string> = {
+  "application/pdf": ".pdf",
+  "image/jpeg": ".jpg",
+  "image/png": ".png",
+  "image/gif": ".gif",
+  "image/tiff": ".tif",
+  "image/bmp": ".bmp",
+};
+
+/** File extension for a stored blob, from the original name, else the mimetype. */
+export function extForUpload(file: UploadedFileLike): string {
+  const fromName = file.originalname ? extname(file.originalname).toLowerCase() : "";
+  if (fromName) return fromName;
+  return (file.mimetype && MIME_EXT[file.mimetype]) || "";
+}
+
+/** Download filename for a stored document, from its key + document type. */
+export function downloadName(storageKey: string, documentType: string): string {
+  const ext = extname(storageKey) || "";
+  const base = documentType.replace(/[^\w.-]+/g, "_") || "document";
+  return base.toLowerCase().endsWith(ext.toLowerCase()) ? base : `${base}${ext}`;
+}

apps/api/src/users/users.controller.ts

@@ -1,7 +1,9 @@
 import {
   Body,
   Controller,
+  Delete,
   Get,
+  HttpCode,
   Param,
   Patch,
   Post,
@@ -69,4 +71,12 @@ export class UsersController {
     void this.audit.log(this.actingId(req), "user.reset_password", { userId: id });
     return user;
   }
+
+  @Delete(":id")
+  @HttpCode(204)
+  async remove(@Param("id") id: string, @Req() req: Request) {
+    const actingId = this.actingId(req);
+    await this.users.remove(id, actingId);
+    void this.audit.log(actingId, "user.delete", { userId: id });
+  }
 }

apps/api/src/users/users.service.ts

@@ -18,6 +18,7 @@ const safeSelect = {
   email: true,
   role: true,
   active: true,
+  uiScale: true,
   createdAt: true,
   updatedAt: true,
 } satisfies Prisma.UserSelect;
@@ -101,6 +102,18 @@ export class UsersService {
     }
   }
 
+  /**
+   * Self-service preference write — no ability check, because the only account
+   * it can touch is the caller's own (the controller passes the session id).
+   */
+  updatePreferences(id: string, uiScale: number): Promise<SafeUserRow> {
+    return this.prisma.user.update({
+      where: { id },
+      data: { uiScale },
+      select: safeSelect,
+    });
+  }
+
   async resetPassword(id: string, password: string): Promise<SafeUserRow> {
     await this.ensureExists(id);
     const passwordHash = await argon2.hash(password);
@@ -111,6 +124,30 @@ export class UsersService {
     });
   }
 
+  /**
+   * Hard-delete a user. The schema's ActivityLog.userId FK would otherwise
+   * block the row (default `Restrict`), so null it out in the same
+   * transaction. Rows + the actor id captured in the `message` JSON stay
+   * intact for the audit trail.
+   */
+  async remove(id: string, actingUserId: string): Promise<void> {
+    if (id === actingUserId) {
+      throw new BadRequestException("No puede eliminar su propia cuenta");
+    }
+    await this.ensureExists(id);
+    try {
+      await this.prisma.$transaction([
+        this.prisma.activityLog.updateMany({
+          where: { userId: id },
+          data: { userId: null },
+        }),
+        this.prisma.user.delete({ where: { id } }),
+      ]);
+    } catch (e) {
+      throw this.mapError(e);
+    }
+  }
+
   private async ensureExists(id: string): Promise<void> {
     const found = await this.prisma.user.findUnique({ where: { id }, select: { id: true } });
     if (!found) throw new NotFoundException(`Usuario ${id} no encontrado`);

apps/web/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@jorgecuadros/web",
-  "version": "0.1.0",
+  "version": "1.0.2",
   "private": true,
   "scripts": {
-    "dev": "next dev",
+    "dev": "next dev -p 4500",
     "build": "next build",
     "start": "next start",
     "lint": "next lint"

apps/web/src/app/banco/cuentas/page.tsx

@@ -0,0 +1,525 @@
+"use client";
+
+import Link from "next/link";
+import { useEffect, useState } from "react";
+import { AppShell } from "@/components/AppShell";
+import { useCan } from "@/lib/abilities";
+import {
+  createBankAccount,
+  createBankInstitution,
+  listBankAccounts,
+  listBankInstitutions,
+  updateBankAccount,
+  updateBankInstitution,
+} from "@/lib/api";
+import { domainLabel } from "@/lib/labels";
+import type {
+  BankAccount,
+  BankInstitution,
+  Currency,
+  TransactionDomain,
+} from "@/lib/types";
+
+/**
+ * Chequera accounts admin — docs/RECEIPT_CAPTURE_SPEC.md §3.
+ *
+ * Two levels: the bank (institution) and the accounts held at it. Opening an
+ * account is rare and consequential — its currency is what every movement
+ * booked into it is denominated in, and it can't be changed afterwards without
+ * silently re-denominating history, so the edit form deliberately has no
+ * currency field.
+ *
+ * Accounts are never deleted: `bank_transactions.bankAccountId` is a required
+ * FK, so a used account can't be removed without destroying its register.
+ * Closing one (`active: false`) hides it from new captures while leaving the
+ * history readable, matching this app's never-hard-delete convention.
+ */
+const CURRENCIES: Currency[] = ["MXN", "USD"];
+const BUSINESS_LINES: TransactionDomain[] = ["UTILITY", "INSURANCE", "TRUST"];
+
+export default function CuentasChequeraPage() {
+  return (
+    <AppShell>
+      <Cuentas />
+    </AppShell>
+  );
+}
+
+function Cuentas() {
+  const canEdit = useCan("bank:manage-accounts");
+  const [banks, setBanks] = useState<BankInstitution[] | null>(null);
+  const [accounts, setAccounts] = useState<BankAccount[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  function reload() {
+    Promise.all([listBankInstitutions(), listBankAccounts()])
+      .then(([b, a]) => {
+        setBanks(b);
+        setAccounts(a);
+      })
+      .catch((e) => setError(e?.message ?? "No se pudieron cargar las cuentas."));
+  }
+  useEffect(reload, []);
+
+  if (!canEdit) {
+    return (
+      <>
+        <div className="page-head">
+          <h1 className="page-title">Cuentas de chequera</h1>
+        </div>
+        <div className="state-box state-error">
+          No tiene permisos para administrar cuentas bancarias.
+        </div>
+      </>
+    );
+  }
+
+  return (
+    <>
+      <div className="page-head">
+        <p className="eyebrow">
+          <Link href="/banco">Chequera</Link>
+        </p>
+        <h1 className="page-title">Cuentas de chequera</h1>
+        <p className="section-note">
+          Cada cuenta es una chequera física y se lleva por separado. La moneda
+          se fija al darla de alta porque todos sus movimientos quedan
+          registrados en ella; para cambiarla hay que abrir otra cuenta. Las
+          cuentas no se eliminan: se cierran, y su historial sigue consultable.
+        </p>
+      </div>
+
+      {error && <div className="state-box state-error">{error}</div>}
+
+      {!banks || !accounts ? (
+        <div className="empty-inline">
+          <span className="spinner" aria-label="Cargando" />
+        </div>
+      ) : (
+        <>
+          <BanksSection banks={banks} onChanged={reload} />
+          <AccountsSection
+            banks={banks}
+            accounts={accounts}
+            onChanged={reload}
+          />
+        </>
+      )}
+    </>
+  );
+}
+
+/* ------------------------------------------------------------------ banks */
+
+function BanksSection({
+  banks,
+  onChanged,
+}: {
+  banks: BankInstitution[];
+  onChanged: () => void;
+}) {
+  const [adding, setAdding] = useState(false);
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [name, setName] = useState("");
+  const [country, setCountry] = useState("");
+  const [busy, setBusy] = useState(false);
+
+  function startAdd() {
+    setEditingId(null);
+    setAdding(true);
+    setName("");
+    setCountry("");
+  }
+  function startEdit(b: BankInstitution) {
+    setAdding(false);
+    setEditingId(b.id);
+    setName(b.name);
+    setCountry(b.country ?? "");
+  }
+  function cancel() {
+    setAdding(false);
+    setEditingId(null);
+  }
+
+  async function submit() {
+    if (!name.trim()) {
+      window.alert("El nombre del banco es obligatorio.");
+      return;
+    }
+    setBusy(true);
+    try {
+      const payload = { name: name.trim(), country: country.trim() };
+      if (editingId) await updateBankInstitution(editingId, payload);
+      else await createBankInstitution(payload);
+      cancel();
+      onChanged();
+    } catch (e) {
+      window.alert((e as Error)?.message ?? "No se pudo guardar el banco.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const editor = (
+    <div className="child-editor">
+      <div className="form-grid">
+        <label className="field">
+          <span className="field-label">
+            Banco <span aria-hidden>*</span>
+          </span>
+          <input
+            className="input"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+            placeholder="Ej. Scotiabank"
+          />
+        </label>
+        <label className="field">
+          <span className="field-label">País</span>
+          <input
+            className="input"
+            value={country}
+            onChange={(e) => setCountry(e.target.value)}
+            placeholder="MX / US"
+          />
+        </label>
+      </div>
+      <div className="form-actions">
+        <button
+          type="button"
+          className="btn btn-primary"
+          onClick={submit}
+          disabled={busy}
+        >
+          {busy ? "Guardando…" : editingId ? "Guardar" : "Agregar"}
+        </button>
+        <button type="button" className="btn btn-ghost" onClick={cancel}>
+          Cancelar
+        </button>
+      </div>
+    </div>
+  );
+
+  return (
+    <div className="card" style={{ padding: 16, marginBottom: 14 }}>
+      <div className="child-head">
+        <h3 className="section-title" style={{ margin: 0 }}>
+          Bancos
+          <span className="section-count"> {banks.length}</span>
+        </h3>
+        {!adding && editingId === null && (
+          <button type="button" className="btn btn-outline" onClick={startAdd}>
+            + Agregar
+          </button>
+        )}
+      </div>
+
+      {banks.length === 0 && !adding ? (
+        <div className="empty-inline">Sin bancos registrados.</div>
+      ) : (
+        <div className="tx-scroll">
+          <table className="tx-table">
+            <thead>
+              <tr>
+                <th>Banco</th>
+                <th>País</th>
+                <th className="num">Acciones</th>
+              </tr>
+            </thead>
+            <tbody>
+              {adding && (
+                <tr>
+                  <td colSpan={3}>{editor}</td>
+                </tr>
+              )}
+              {banks.map((b) =>
+                editingId === b.id ? (
+                  <tr key={b.id}>
+                    <td colSpan={3}>{editor}</td>
+                  </tr>
+                ) : (
+                  <tr key={b.id}>
+                    <td>{b.name}</td>
+                    <td>{b.country || "—"}</td>
+                    <td>
+                      <div className="row-actions">
+                        <button
+                          type="button"
+                          className="btn btn-ghost"
+                          onClick={() => startEdit(b)}
+                        >
+                          Editar
+                        </button>
+                      </div>
+                    </td>
+                  </tr>
+                ),
+              )}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+}
+
+/* --------------------------------------------------------------- accounts */
+
+function AccountsSection({
+  banks,
+  accounts,
+  onChanged,
+}: {
+  banks: BankInstitution[];
+  accounts: BankAccount[];
+  onChanged: () => void;
+}) {
+  const [adding, setAdding] = useState(false);
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [bankId, setBankId] = useState("");
+  const [label, setLabel] = useState("");
+  const [currency, setCurrency] = useState<Currency>("MXN");
+  const [businessLine, setBusinessLine] = useState<string>("");
+  const [active, setActive] = useState(true);
+  const [busy, setBusy] = useState(false);
+
+  function startAdd() {
+    setEditingId(null);
+    setAdding(true);
+    setBankId(banks[0]?.id ?? "");
+    setLabel("");
+    setCurrency("MXN");
+    setBusinessLine("");
+    setActive(true);
+  }
+  function startEdit(a: BankAccount) {
+    setAdding(false);
+    setEditingId(a.id);
+    setBankId(a.bankId);
+    setLabel(a.label);
+    setCurrency(a.currency);
+    setBusinessLine(a.businessLine ?? "");
+    setActive(a.active);
+  }
+  function cancel() {
+    setAdding(false);
+    setEditingId(null);
+  }
+
+  async function submit() {
+    if (!bankId) {
+      window.alert("Selecciona el banco de la cuenta.");
+      return;
+    }
+    if (!label.trim()) {
+      window.alert("El nombre de la cuenta es obligatorio.");
+      return;
+    }
+    setBusy(true);
+    try {
+      const line = businessLine
+        ? (businessLine as TransactionDomain)
+        : undefined;
+      if (editingId) {
+        // No `currency`: see the file header.
+        await updateBankAccount(editingId, {
+          bankId,
+          label: label.trim(),
+          businessLine: line,
+          active,
+        });
+      } else {
+        await createBankAccount({
+          bankId,
+          label: label.trim(),
+          currency,
+          businessLine: line,
+          active,
+        });
+      }
+      cancel();
+      onChanged();
+    } catch (e) {
+      window.alert((e as Error)?.message ?? "No se pudo guardar la cuenta.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const editor = (
+    <div className="child-editor">
+      <div className="form-grid">
+        <label className="field">
+          <span className="field-label">
+            Banco <span aria-hidden>*</span>
+          </span>
+          <select
+            className="select"
+            value={bankId}
+            onChange={(e) => setBankId(e.target.value)}
+          >
+            <option value="">—</option>
+            {banks.map((b) => (
+              <option key={b.id} value={b.id}>
+                {b.name}
+              </option>
+            ))}
+          </select>
+        </label>
+        <label className="field">
+          <span className="field-label">
+            Nombre de la cuenta <span aria-hidden>*</span>
+          </span>
+          <input
+            className="input"
+            value={label}
+            onChange={(e) => setLabel(e.target.value)}
+            placeholder="Ej. Seguros — Bank of America (USD)"
+          />
+        </label>
+        <label className="field">
+          <span className="field-label">
+            Moneda <span aria-hidden>*</span>
+          </span>
+          <select
+            className="select"
+            value={currency}
+            disabled={editingId !== null}
+            onChange={(e) => setCurrency(e.target.value as Currency)}
+          >
+            {CURRENCIES.map((c) => (
+              <option key={c} value={c}>
+                {c}
+              </option>
+            ))}
+          </select>
+          {editingId !== null && (
+            <span className="section-note">
+              No se puede cambiar: los movimientos ya registrados están en esta
+              moneda.
+            </span>
+          )}
+        </label>
+        <label className="field">
+          <span className="field-label">Línea de negocio</span>
+          <select
+            className="select"
+            value={businessLine}
+            onChange={(e) => setBusinessLine(e.target.value)}
+          >
+            <option value="">Sin asignar</option>
+            {BUSINESS_LINES.map((d) => (
+              <option key={d} value={d}>
+                {domainLabel(d)}
+              </option>
+            ))}
+          </select>
+          <span className="section-note">
+            Referencia nada más: una chequera puede pagar de varias líneas.
+          </span>
+        </label>
+        <label
+          className="field"
+          style={{ flexDirection: "row", alignItems: "center", gap: 8 }}
+        >
+          <input
+            type="checkbox"
+            checked={active}
+            onChange={(e) => setActive(e.target.checked)}
+          />
+          <span className="field-label" style={{ margin: 0 }}>
+            Cuenta abierta
+          </span>
+        </label>
+      </div>
+      <div className="form-actions">
+        <button
+          type="button"
+          className="btn btn-primary"
+          onClick={submit}
+          disabled={busy}
+        >
+          {busy ? "Guardando…" : editingId ? "Guardar" : "Agregar"}
+        </button>
+        <button type="button" className="btn btn-ghost" onClick={cancel}>
+          Cancelar
+        </button>
+      </div>
+    </div>
+  );
+
+  return (
+    <div className="card" style={{ padding: 16, marginBottom: 14 }}>
+      <div className="child-head">
+        <h3 className="section-title" style={{ margin: 0 }}>
+          Cuentas
+          <span className="section-count"> {accounts.length}</span>
+        </h3>
+        {!adding && editingId === null && banks.length > 0 && (
+          <button type="button" className="btn btn-outline" onClick={startAdd}>
+            + Agregar
+          </button>
+        )}
+      </div>
+
+      {banks.length === 0 ? (
+        <div className="empty-inline">
+          Registra primero el banco donde está la cuenta.
+        </div>
+      ) : accounts.length === 0 && !adding ? (
+        <div className="empty-inline">Sin cuentas registradas.</div>
+      ) : (
+        <div className="tx-scroll">
+          <table className="tx-table">
+            <thead>
+              <tr>
+                <th>Cuenta</th>
+                <th>Banco</th>
+                <th>Moneda</th>
+                <th>Línea</th>
+                <th>Estatus</th>
+                <th className="num">Acciones</th>
+              </tr>
+            </thead>
+            <tbody>
+              {adding && (
+                <tr>
+                  <td colSpan={6}>{editor}</td>
+                </tr>
+              )}
+              {accounts.map((a) =>
+                editingId === a.id ? (
+                  <tr key={a.id}>
+                    <td colSpan={6}>{editor}</td>
+                  </tr>
+                ) : (
+                  <tr key={a.id}>
+                    <td>{a.label}</td>
+                    <td>{a.bankName}</td>
+                    <td className="mono">{a.currency}</td>
+                    <td>{a.businessLine ? domainLabel(a.businessLine) : "—"}</td>
+                    <td>{a.active ? "Abierta" : "Cerrada"}</td>
+                    <td>
+                      <div className="row-actions">
+                        <button
+                          type="button"
+                          className="btn btn-ghost"
+                          onClick={() => startEdit(a)}
+                        >
+                          Editar
+                        </button>
+                        <Link href="/banco" className="btn btn-ghost">
+                          Ver movimientos
+                        </Link>
+                      </div>
+                    </td>
+                  </tr>
+                ),
+              )}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+}

apps/web/src/app/banco/page.tsx

@@ -1,12 +1,15 @@
 "use client";
 
+import Link from "next/link";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { AppShell } from "@/components/AppShell";
+import { ContextReports } from "@/components/ContextReports";
 import {
   createBankMovement,
   getBankFacets,
   getBankStats,
   getBankSummary,
+  listBankAccounts,
   listBankMovements,
   voidBankMovement,
 } from "@/lib/api";
@@ -21,6 +24,7 @@ import {
   monthName,
 } from "@/lib/labels";
 import type {
+  BankAccount,
   BankCleared,
   BankDirection,
   BankFacets,
@@ -31,23 +35,28 @@ import type {
   BankSummary,
   BankTotals,
   CreateBankMovementInput,
+  Currency,
 } from "@/lib/types";
 
 /**
- * Bank register (chequera) browser — plan step 7.
+ * Bank register (chequera) browser — plan step 7, multi-account since the
+ * step-11 multi-bank work.
  *
- * This is the office's OWN checking account, not customer money. It is a
+ * This is the office's OWN checking accounts, not customer money. It is a
  * separate page from /estado-cuenta on purpose: nothing here belongs in a
  * customer's statement and the two sets of figures are never combined.
  *
- * Two views:
+ * Two views, both scoped to the ONE account picked at the top:
  *   - "Movimientos": the register itself — every deposit and payment, by date,
  *     payee, cheque number or amount.
  *   - "Resumen": ingresos vs egresos per year, and per month inside a year,
- *     with the running net movement since the register opened in 2013.
+ *     with the running net movement since the register opened.
  *
- * Single currency (MXN) — the source has no currency column. See the module
- * header in `bank.service.ts` for why there is no category/ramo filter.
+ * Every amount is read in the selected account's currency. There is no "all
+ * accounts" option on purpose — Utilities banks in MXN and Seguros in USD, so
+ * one combined figure would be a number that never existed, exactly what
+ * /estado-cuenta's per-currency rule avoids. See the module header in
+ * `bank.service.ts` for why there is no category/ramo filter.
  */
 type View = "movimientos" | "resumen";
 
@@ -80,9 +89,18 @@ export default function BancoPage() {
   );
 }
 
+/** Remembers the last chequera a person looked at, per browser. */
+const ACCOUNT_KEY = "banco.bankAccountId";
+
 function BankBrowser() {
   const canCapture = useCan("bank:create");
   const canVoid = useCan("bank:void");
+  const canManageAccounts = useCan("bank:manage-accounts");
+
+  const [accounts, setAccounts] = useState<BankAccount[] | null>(null);
+  const [accountId, setAccountId] = useState<string | null>(null);
+  const [accountsError, setAccountsError] = useState<string | null>(null);
+
   const [stats, setStats] = useState<BankStats | null>(null);
   const [facets, setFacets] = useState<BankFacets | null>(null);
   const [view, setView] = useState<View>("movimientos");
@@ -103,16 +121,66 @@ function BankBrowser() {
 
   const debounceRef = useRef<ReturnType<typeof setTimeout>>();
 
+  const account = accounts?.find((a) => a.id === accountId) ?? null;
+  const currency = account?.currency ?? "MXN";
+
+  // Accounts load first: nothing else on this page can be requested until one
+  // is selected, because every read is scoped to exactly one chequera.
   useEffect(() => {
-    getBankStats().then(setStats).catch(() => setStats(null));
-    getBankFacets().then(setFacets).catch(() => setFacets(null));
+    listBankAccounts()
+      .then((rows) => {
+        setAccounts(rows);
+        const remembered =
+          typeof window !== "undefined"
+            ? window.localStorage.getItem(ACCOUNT_KEY)
+            : null;
+        const pick =
+          rows.find((a) => a.id === remembered) ??
+          rows.find((a) => a.active) ??
+          rows[0];
+        setAccountId(pick?.id ?? null);
+        if (rows.length === 0) setLoading(false);
+      })
+      .catch((e) => {
+        setAccountsError(e?.message ?? "No se pudieron cargar las cuentas.");
+        setLoading(false);
+      });
   }, []);
 
+  function pickAccount(id: string) {
+    setAccountId(id);
+    if (typeof window !== "undefined")
+      window.localStorage.setItem(ACCOUNT_KEY, id);
+    // The previous account's figures must not linger while the new ones load.
+    setStats(null);
+    setFacets(null);
+    setMovements(null);
+    setSummary(null);
+    setSummaryYear(null);
+  }
+
+  const refreshStats = useCallback(() => {
+    if (!accountId) return;
+    getBankStats(accountId)
+      .then(setStats)
+      .catch(() => setStats(null));
+  }, [accountId]);
+
+  useEffect(() => {
+    if (!accountId) return;
+    refreshStats();
+    getBankFacets(accountId)
+      .then(setFacets)
+      .catch(() => setFacets(null));
+  }, [accountId, refreshStats]);
+
   const runSearch = useCallback(
     (p: number) => {
+      if (!accountId) return;
       setLoading(true);
       setError(null);
       listBankMovements({
+        bankAccountId: accountId,
         query: query || undefined,
         direction: direction || undefined,
         cleared: cleared || undefined,
@@ -131,23 +199,23 @@ function BankBrowser() {
           setLoading(false);
         });
     },
-    [query, direction, cleared, from, to, sort],
+    [accountId, query, direction, cleared, from, to, sort],
   );
 
   useEffect(() => {
-    if (view !== "movimientos") return;
+    if (view !== "movimientos" || !accountId) return;
     if (debounceRef.current) clearTimeout(debounceRef.current);
     debounceRef.current = setTimeout(() => runSearch(1), 280);
     return () => {
       if (debounceRef.current) clearTimeout(debounceRef.current);
     };
-  }, [runSearch, view]);
+  }, [runSearch, view, accountId]);
 
   useEffect(() => {
-    if (view !== "resumen") return;
+    if (view !== "resumen" || !accountId) return;
     setLoading(true);
     setError(null);
-    getBankSummary(summaryYear ?? undefined)
+    getBankSummary(accountId, summaryYear ?? undefined)
       .then((res) => {
         setSummary(res);
         setLoading(false);
@@ -156,7 +224,7 @@ function BankBrowser() {
         setError(e?.message ?? "No se pudo cargar el resumen.");
         setLoading(false);
       });
-  }, [view, summaryYear]);
+  }, [view, summaryYear, accountId]);
 
   function goToPage(p: number) {
     runSearch(p);
@@ -193,21 +261,79 @@ function BankBrowser() {
     setSort("date_desc");
   }
 
+  if (accountsError) {
+    return (
+      <>
+        <div className="page-head">
+          <h1 className="page-title">Chequera</h1>
+        </div>
+        <div className="state-error" role="alert">
+          {accountsError}
+        </div>
+      </>
+    );
+  }
+
+  // No chequera on file: the register has nothing it could be scoped to.
+  if (accounts && accounts.length === 0) {
+    return (
+      <>
+        <div className="page-head">
+          <p className="eyebrow">Cuentas propias de la oficina</p>
+          <h1 className="page-title">Chequera</h1>
+        </div>
+        <div className="state-box">
+          <div className="state-glyph" aria-hidden>
+            ⌗
+          </div>
+          <h3>Sin cuentas registradas</h3>
+          <p>
+            {canManageAccounts ? (
+              <>
+                Registra una cuenta bancaria en{" "}
+                <Link href="/banco/cuentas">Cuentas de chequera</Link> para
+                empezar a capturar movimientos.
+              </>
+            ) : (
+              "Pide a un administrador que registre una cuenta bancaria."
+            )}
+          </p>
+        </div>
+      </>
+    );
+  }
+
   return (
     <>
       <div className="page-head rise">
         <p className="eyebrow">Cuenta propia de la oficina</p>
         <h1 className="page-title">Chequera</h1>
+        <AccountPicker
+          accounts={accounts}
+          accountId={accountId}
+          onPick={pickAccount}
+          canManageAccounts={canManageAccounts}
+        />
         <BankStatStrip
           stats={stats}
+          currency={currency}
           direction={view === "movimientos" ? direction : ""}
           onPickDirection={pickDirection}
         />
         <p className="section-note">
-          Movimientos de la cuenta bancaria de la oficina, en pesos. No forma
-          parte del estado de cuenta de los clientes y sus cifras no se suman
-          con las de ellos.
+          Movimientos de{" "}
+          <strong>{account ? account.label : "la cuenta seleccionada"}</strong>,
+          en {currency}. Cada cuenta se lee por separado: las cifras de dos
+          chequeras nunca se suman, igual que los saldos por moneda del estado
+          de cuenta. Tampoco forman parte del estado de cuenta de los clientes.
         </p>
+        <div style={{ marginTop: 8 }}>
+          <ContextReports
+            entries={[
+              { slug: "reporte-de-efectivo", label: "Reporte de efectivo" },
+            ]}
+          />
+        </div>
       </div>
 
       <div className="toolbar">
@@ -244,7 +370,7 @@ function BankBrowser() {
             </button>
           ))}
         </div>
-        {view === "movimientos" && canCapture && (
+        {view === "movimientos" && canCapture && account?.active && (
           <button
             type="button"
             className="btn btn-primary"
@@ -255,12 +381,20 @@ function BankBrowser() {
         )}
       </div>
 
-      {view === "movimientos" && captureOpen && (
+      {account && !account.active && (
+        <div className="section-note">
+          Esta cuenta está cerrada: su historial se consulta, pero no admite
+          movimientos nuevos.
+        </div>
+      )}
+
+      {view === "movimientos" && captureOpen && account && (
         <BankCaptureForm
+          account={account}
           onSaved={() => {
             setCaptureOpen(false);
             runSearch(movements?.page ?? 1);
-            getBankStats().then(setStats).catch(() => setStats(null));
+            refreshStats();
           }}
           onCancel={() => setCaptureOpen(false)}
         />
@@ -381,7 +515,7 @@ function BankBrowser() {
       )}
 
       {view === "movimientos" && movements && !loading && (
-        <FilteredTotals totals={movements.totals} />
+        <FilteredTotals totals={movements.totals} currency={currency} />
       )}
 
       {error ? (
@@ -394,6 +528,7 @@ function BankBrowser() {
         <SummaryView
           summary={summary}
           year={summaryYear}
+          currency={currency}
           onPickYear={pickYear}
         />
       ) : movements && movements.total === 0 ? (
@@ -422,12 +557,11 @@ function BankBrowser() {
                     <BankRow
                       key={m.id}
                       m={m}
+                      currency={currency}
                       canVoid={canVoid}
                       onVoided={() => {
                         runSearch(movements?.page ?? 1);
-                        getBankStats()
-                          .then(setStats)
-                          .catch(() => setStats(null));
+                        refreshStats();
                       }}
                     />
                   ))}
@@ -448,13 +582,66 @@ function BankBrowser() {
   );
 }
 
+/**
+ * Which chequera the whole page is reading. There is no "todas las cuentas"
+ * option and there must not be one — see the file header.
+ */
+function AccountPicker({
+  accounts,
+  accountId,
+  onPick,
+  canManageAccounts,
+}: {
+  accounts: BankAccount[] | null;
+  accountId: string | null;
+  onPick: (id: string) => void;
+  canManageAccounts: boolean;
+}) {
+  if (!accounts) {
+    return (
+      <div className="skeleton" style={{ height: 34, width: 260, marginTop: 12 }} />
+    );
+  }
+
+  return (
+    <div
+      className="filter-row"
+      style={{ marginTop: 12, alignItems: "flex-end" }}
+    >
+      <label className="filter-field">
+        <span className="filter-label">Cuenta</span>
+        <select
+          className="input select"
+          value={accountId ?? ""}
+          onChange={(e) => onPick(e.target.value)}
+          aria-label="Cuenta de chequera"
+        >
+          {accounts.map((a) => (
+            <option key={a.id} value={a.id}>
+              {a.label} · {a.currency}
+              {a.active ? "" : " (cerrada)"}
+            </option>
+          ))}
+        </select>
+      </label>
+      {canManageAccounts && (
+        <Link href="/banco/cuentas" className="btn btn-ghost">
+          Administrar cuentas
+        </Link>
+      )}
+    </div>
+  );
+}
+
 /** Headline figures; the ingreso/egreso cells double as register shortcuts. */
 function BankStatStrip({
   stats,
+  currency,
   direction,
   onPickDirection,
 }: {
   stats: BankStats | null;
+  currency: Currency;
   direction: BankDirection | "";
   onPickDirection: (d: BankDirection) => void;
 }) {
@@ -485,7 +672,7 @@ function BankStatStrip({
         aria-pressed={direction === "income"}
       >
         <div className="stat-value tx-amount pos">
-          {formatMoney(stats.income, "MXN")}
+          {formatMoney(stats.income, currency)}
         </div>
         <div className="stat-label">
           En ingresos · {formatNumber(stats.incomeCount)} movimientos
@@ -500,14 +687,14 @@ function BankStatStrip({
         aria-pressed={direction === "expense"}
       >
         <div className="stat-value tx-amount neg">
-          {formatMoney(stats.expense, "MXN")}
+          {formatMoney(stats.expense, currency)}
         </div>
         <div className="stat-label">
           En egresos · {formatNumber(stats.expenseCount)} movimientos
         </div>
       </button>
       <div className="stat-cell">
-        <div className="stat-value">{formatMoney(stats.net, "MXN")}</div>
+        <div className="stat-value">{formatMoney(stats.net, currency)}</div>
         {/* Not the bank balance: the register carries no opening balance. */}
         <div className="stat-label">Movimiento neto acumulado</div>
       </div>
@@ -536,27 +723,33 @@ function BankStatStrip({
 }
 
 /** Totals for everything the current filter matched, not just the page. */
-function FilteredTotals({ totals }: { totals: BankTotals }) {
+function FilteredTotals({
+  totals,
+  currency,
+}: {
+  totals: BankTotals;
+  currency: Currency;
+}) {
   if (totals.incomeCount + totals.expenseCount + totals.voidCount === 0)
     return null;
   return (
     <div className="filtered-totals">
       <div className="filtered-total">
-        <span className="filtered-total-cur">MXN</span>
+        <span className="filtered-total-cur">{currency}</span>
         <span>
           <strong className="tx-amount pos">
-            {formatMoney(totals.income, "MXN")}
+            {formatMoney(totals.income, currency)}
           </strong>{" "}
           en ingresos · {formatNumber(totals.incomeCount)}
         </span>
         <span>
           <strong className="tx-amount neg">
-            {formatMoney(totals.expense, "MXN")}
+            {formatMoney(totals.expense, currency)}
           </strong>{" "}
           en egresos · {formatNumber(totals.expenseCount)}
         </span>
         <span className="filtered-total-net">
-          Neto <strong>{formatMoney(totals.net, "MXN")}</strong>
+          Neto <strong>{formatMoney(totals.net, currency)}</strong>
         </span>
         {totals.voidCount > 0 && (
           <span>{formatNumber(totals.voidCount)} cancelados</span>
@@ -568,10 +761,12 @@ function FilteredTotals({ totals }: { totals: BankTotals }) {
 
 function BankRow({
   m,
+  currency,
   canVoid,
   onVoided,
 }: {
   m: BankListItem;
+  currency: Currency;
   canVoid: boolean;
   onVoided: () => void;
 }) {
@@ -612,7 +807,7 @@ function BankRow({
       <td>{bankSourceLabel(m.source)}</td>
       <td className="num">
         <span className={`tx-amount ${bankTone(m.direction)}`}>
-          {m.direction === "void" ? "—" : formatMoney(m.amount, "MXN")}
+          {m.direction === "void" ? "—" : formatMoney(m.amount, currency)}
         </span>
         <div className="tx-cur">{bankDirectionLabel(m.direction)}</div>
       </td>
@@ -642,10 +837,12 @@ function BankRow({
 function SummaryView({
   summary,
   year,
+  currency,
   onPickYear,
 }: {
   summary: BankSummary | null;
   year: number | null;
+  currency: Currency;
   onPickYear: (y: number) => void;
 }) {
   if (!summary) return null;
@@ -679,12 +876,12 @@ function SummaryView({
                   <td className="num">{formatNumber(r.count)}</td>
                   <td className="num">
                     <span className="tx-amount pos">
-                      {formatMoney(r.income, "MXN")}
+                      {formatMoney(r.income, currency)}
                     </span>
                   </td>
                   <td className="num">
                     <span className="tx-amount neg">
-                      {formatMoney(r.expense, "MXN")}
+                      {formatMoney(r.expense, currency)}
                     </span>
                   </td>
                   <td className="num">
@@ -693,10 +890,10 @@ function SummaryView({
                         Number(r.net) < 0 ? "neg" : "pos"
                       }`}
                     >
-                      {formatMoney(r.net, "MXN")}
+                      {formatMoney(r.net, currency)}
                     </span>
                   </td>
-                  <td className="num mono">{formatMoney(r.cumulative, "MXN")}</td>
+                  <td className="num mono">{formatMoney(r.cumulative, currency)}</td>
                 </tr>
               ))}
             </tbody>
@@ -716,7 +913,7 @@ function SummaryView({
             <span className="section-rule cuenta" />
             <h2 className="section-title">Meses de {year}</h2>
             <span className="section-count">
-              abre en {formatMoney(summary.opening, "MXN")}
+              abre en {formatMoney(summary.opening, currency)}
             </span>
           </div>
           <div className="card">
@@ -739,12 +936,12 @@ function SummaryView({
                       <td className="num">{formatNumber(r.count)}</td>
                       <td className="num">
                         <span className="tx-amount pos">
-                          {formatMoney(r.income, "MXN")}
+                          {formatMoney(r.income, currency)}
                         </span>
                       </td>
                       <td className="num">
                         <span className="tx-amount neg">
-                          {formatMoney(r.expense, "MXN")}
+                          {formatMoney(r.expense, currency)}
                         </span>
                       </td>
                       <td className="num">
@@ -753,11 +950,11 @@ function SummaryView({
                             Number(r.net) < 0 ? "neg" : "pos"
                           }`}
                         >
-                          {formatMoney(r.net, "MXN")}
+                          {formatMoney(r.net, currency)}
                         </span>
                       </td>
                       <td className="num mono">
-                        {formatMoney(r.cumulative, "MXN")}
+                        {formatMoney(r.cumulative, currency)}
                       </td>
                     </tr>
                   ))}
@@ -771,13 +968,16 @@ function SummaryView({
   );
 }
 
-/** Inline capture form for a single chequera movement. Single currency (MXN);
- *  sign convention: positive = ingreso, negative = egreso. Booked rows are
- *  never edited — fix mistakes with voidBankMovement + a fresh capture. */
+/** Inline capture form for a single chequera movement. The amount is in the
+ *  selected account's currency; sign convention: positive = ingreso, negative
+ *  = egreso. Booked rows are never edited — fix mistakes with voidBankMovement
+ *  + a fresh capture. */
 function BankCaptureForm({
+  account,
   onSaved,
   onCancel,
 }: {
+  account: BankAccount;
   onSaved: () => void;
   onCancel: () => void;
 }) {
@@ -810,6 +1010,7 @@ function BankCaptureForm({
     }
     const signed = direction === "income" ? Math.abs(abs) : -Math.abs(abs);
     const payload: CreateBankMovementInput = {
+      bankAccountId: account.id,
       amount: signed,
       transactionDate,
       concept: s(concept),
@@ -835,9 +1036,12 @@ function BankCaptureForm({
     <form onSubmit={submit}>
       {error && <div className="state-box state-error">{error}</div>}
       <div className="card" style={{ padding: 20, marginBottom: 16 }}>
-        <h2 className="section-title" style={{ marginBottom: 14 }}>
+        <h2 className="section-title" style={{ marginBottom: 4 }}>
           Capturar movimiento de chequera
         </h2>
+        <p className="section-note" style={{ marginBottom: 14 }}>
+          Se registra en <strong>{account.label}</strong>, en {account.currency}.
+        </p>
         <div className="form-grid">
           <label className="field">
             <span className="field-label">
@@ -866,7 +1070,7 @@ function BankCaptureForm({
           </label>
           <label className="field">
             <span className="field-label">
-              Monto (MXN) <span aria-hidden>*</span>
+              Monto ({account.currency}) <span aria-hidden>*</span>
             </span>
             <input
               className="input"

apps/web/src/app/clientes/[id]/page.tsx

@@ -3,7 +3,14 @@
 import { useEffect, useState } from "react";
 import Link from "next/link";
 import { AppShell } from "@/components/AppShell";
-import { archiveCustomer, getCustomer, restoreCustomer } from "@/lib/api";
+import { ContextReports } from "@/components/ContextReports";
+import {
+  archiveCustomer,
+  getCustomer,
+  policyDocumentDownloadUrl,
+  propertyDocumentDownloadUrl,
+  restoreCustomer,
+} from "@/lib/api";
 import { useCan } from "@/lib/abilities";
 import {
   domainLabel,
@@ -89,6 +96,15 @@ function Detail({ id }: { id: string }) {
     <div className="rise">
       <div className="detail-actionbar">
         <BackLink />
+        <ContextReports
+          entries={[
+            {
+              slug: "edo-cuenta-datos",
+              label: "Estado de cuenta (reporte)",
+              params: { customerId: data.id },
+            },
+          ]}
+        />
         <CustomerActions
           customer={data}
           onChange={() => getCustomer(id).then(setData).catch(() => {})}
@@ -765,9 +781,10 @@ function TxRow({ t }: { t: Transaction }) {
   const tipo =
     t.type?.nameEs || t.type?.nameEn || "—";
   const concept = t.message || t.period || "—";
+  const voided = !!t.voidedAt;
 
   return (
-    <tr>
+    <tr style={voided ? { textDecoration: "line-through", opacity: 0.55 } : undefined}>
       <td className="mono" style={{ whiteSpace: "nowrap" }}>
         {formatDate(t.transactionDate)}
       </td>
@@ -777,7 +794,14 @@ function TxRow({ t }: { t: Transaction }) {
       </td>
       <td>{tipo}</td>
       <td className="tx-ref">{t.reference || "—"}</td>
-      <td className="tx-concept">{concept}</td>
+      <td className="tx-concept">
+        {concept}
+        {voided && (
+          <span className="tx-cur" style={{ marginLeft: 6, textDecoration: "none" }}>
+            (anulado)
+          </span>
+        )}
+      </td>
       <td className="num">
         <span className={`tx-amount ${sign}`}>
           {formatMoney(t.amount, t.currency)}
@@ -790,15 +814,15 @@ function TxRow({ t }: { t: Transaction }) {
 
 /* ----------------------------------------------------------- Documentos */
 function DocumentosSection({ data }: { data: CustomerDetail }) {
-  type Doc = { type: string; key: string | null; scope: string };
+  type Doc = { type: string; scope: string; href: string | null };
   const docs: Doc[] = [];
   data.properties.forEach((p) => {
     const label = [p.addressLine1].filter(Boolean).join("") || "Propiedad";
     p.documents.forEach((d) =>
       docs.push({
         type: d.documentType || "Documento",
-        key: d.storageKey,
         scope: label,
+        href: d.id ? propertyDocumentDownloadUrl(p.id, d.id) : null,
       }),
     );
   });
@@ -806,8 +830,8 @@ function DocumentosSection({ data }: { data: CustomerDetail }) {
     p.documents.forEach((d) =>
       docs.push({
         type: d.documentType || "Documento",
-        key: d.storageKey,
         scope: `Póliza ${p.policyNumber ?? ""}`.trim(),
+        href: d.id ? policyDocumentDownloadUrl(p.id, d.id) : null,
       }),
     );
   });
@@ -821,28 +845,24 @@ function DocumentosSection({ data }: { data: CustomerDetail }) {
             No hay documentos registrados para este cliente.
           </div>
         ) : (
-          <>
           <div className="doc-list">
             {docs.map((d, i) => (
               <div className="doc-item" key={i}>
                 <span className="doc-icon" aria-hidden>
                   ▤
                 </span>
-                  <div style={{ minWidth: 0 }}>
+                <div style={{ minWidth: 0, flex: 1 }}>
                   <div className="doc-type">{d.type}</div>
                   <div className="doc-key">{d.scope}</div>
                 </div>
+                {d.href && (
+                  <a className="btn btn-ghost" href={d.href}>
+                    Descargar
+                  </a>
+                )}
               </div>
             ))}
           </div>
-            <div
-              className="section-note"
-              style={{ padding: "0 22px 18px" }}
-            >
-              Los archivos se almacenan en el object storage
-              (storageKey); no se descargan desde esta vista.
-            </div>
-          </>
         )}
       </div>
     </section>

apps/web/src/app/clientes/page.tsx

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import Link from "next/link";
 import { AppShell } from "@/components/AppShell";
+import { ContextReports } from "@/components/ContextReports";
 import { getStats, listCustomers } from "@/lib/api";
 import { useCan } from "@/lib/abilities";
 import { formatNumber, SIN_NOMBRE } from "@/lib/labels";
@@ -99,6 +100,12 @@ function ClientesBrowser() {
         <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
           <h1 className="page-title" style={{ margin: 0 }}>Clientes</h1>
           <span style={{ flex: 1 }} />
+          <ContextReports
+            entries={[
+              { slug: "listado-en-rojo", label: "En rojo" },
+              { slug: "pagos-no-efectuados", label: "Sin pagos (agua)" },
+            ]}
+          />
           {canCreate && (
             <Link href="/clientes/nuevo" className="btn btn-primary">
               + Nuevo cliente

apps/web/src/app/estado-cuenta/lote/page.tsx

@@ -0,0 +1,11 @@
+import { AppShell } from "@/components/AppShell";
+import { Captura } from "@/components/Captura";
+
+/** Daily capture, opened on the manual (key-by-hand) mode. */
+export default function BatchCapturePage() {
+  return (
+    <AppShell>
+      <Captura initialMode="manual" />
+    </AppShell>
+  );
+}

apps/web/src/app/estado-cuenta/page.tsx

@@ -3,12 +3,14 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import Link from "next/link";
 import { AppShell } from "@/components/AppShell";
+import { ContextReports } from "@/components/ContextReports";
 import { MovementForm } from "@/components/MovementForm";
 import {
   getBillingFacets,
   getBillingStats,
   listBalances,
   listMovements,
+  resolveOutstanding,
   voidMovement,
 } from "@/lib/api";
 import { useCan } from "@/lib/abilities";
@@ -116,6 +118,8 @@ function BillingBrowser() {
   const [direction, setDirection] = useState<LedgerDirection | "">("");
   const [typeId, setTypeId] = useState("");
   const [source, setSource] = useState("");
+  // "" = no filter, "true" = only NOPAGO rows, "false" = only settled ones.
+  const [outstanding, setOutstanding] = useState<"" | "true" | "false">("");
   const [from, setFrom] = useState("");
   const [to, setTo] = useState("");
   const [movementSort, setMovementSort] = useState<MovementSort>("date_desc");
@@ -125,6 +129,7 @@ function BillingBrowser() {
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [captureOpen, setCaptureOpen] = useState(false);
+  const [resolving, setResolving] = useState<MovementListItem | null>(null);
 
   const debounceRef = useRef<ReturnType<typeof setTimeout>>();
 
@@ -164,6 +169,7 @@ function BillingBrowser() {
           direction: direction || undefined,
           typeId: typeId || undefined,
           source: source || undefined,
+          outstanding: outstanding === "" ? undefined : outstanding === "true",
           from: from || undefined,
           to: to || undefined,
           sort: movementSort,
@@ -187,6 +193,7 @@ function BillingBrowser() {
       direction,
       typeId,
       source,
+      outstanding,
       from,
       to,
       movementSort,
@@ -256,6 +263,15 @@ function BillingBrowser() {
         <LedgerTotalsStrip stats={stats} />
       </div>
 
+      <div style={{ marginTop: 12 }}>
+        <ContextReports
+          entries={[
+            { slug: "listado-en-rojo", label: "En rojo" },
+            { slug: "reporte-de-efectivo", label: "Reporte de efectivo" },
+          ]}
+        />
+      </div>
+
       <div className="toolbar">
         <div className="search-box">
           <span className="search-icon" aria-hidden>
@@ -294,6 +310,10 @@ function BillingBrowser() {
           ))}
         </div>
         {view === "movimientos" && canCapture && (
+          <div style={{ display: "flex", gap: 10 }}>
+            <Link href="/estado-cuenta/lote" className="btn btn-outline">
+              Captura por cheque
+            </Link>
             <button
               type="button"
               className="btn btn-primary"
@@ -301,9 +321,24 @@ function BillingBrowser() {
             >
               {captureOpen ? "Cerrar captura" : "Capturar movimiento"}
             </button>
+          </div>
         )}
       </div>
 
+      {view === "movimientos" && resolving && (
+        <ResolveDialog
+          movement={resolving}
+          onCancel={() => setResolving(null)}
+          onDone={() => {
+            setResolving(null);
+            runSearch(movements?.page ?? 1);
+            getBillingStats()
+              .then(setStats)
+              .catch(() => setStats(null));
+          }}
+        />
+      )}
+
       {view === "movimientos" && captureOpen && (
         <section className="section">
           <div className="section-head">
@@ -437,6 +472,21 @@ function BillingBrowser() {
               </select>
             </label>
 
+            <label className="filter-field">
+              <span className="filter-label">Estado de pago</span>
+              <select
+                className="input select"
+                value={outstanding}
+                onChange={(e) =>
+                  setOutstanding(e.target.value as "" | "true" | "false")
+                }
+              >
+                <option value="">Todos</option>
+                <option value="true">Sin fondos (pendientes)</option>
+                <option value="false">Pagados</option>
+              </select>
+            </label>
+
             <label className="filter-field">
               <span className="filter-label">Desde</span>
               <input
@@ -542,7 +592,9 @@ function BillingBrowser() {
                     <th>Concepto</th>
                     <th>Referencia</th>
                     <th className="num">Monto</th>
-                    {canVoid && <th style={{ width: 1, whiteSpace: "nowrap" }}>Acciones</th>}
+                    {(canVoid || canCapture) && (
+                      <th style={{ width: 1, whiteSpace: "nowrap" }}>Acciones</th>
+                    )}
                   </tr>
                 </thead>
                 <tbody>
@@ -551,6 +603,8 @@ function BillingBrowser() {
                       key={m.id}
                       m={m}
                       canVoid={canVoid}
+                      canCapture={canCapture}
+                      onResolve={setResolving}
                       onVoided={() => {
                         runSearch(movements?.page ?? 1);
                         getBillingStats()
@@ -789,11 +843,15 @@ function BalanceRow({
 function MovementRow({
   m,
   canVoid,
+  canCapture,
   onVoided,
+  onResolve,
 }: {
   m: MovementListItem;
   canVoid: boolean;
+  canCapture: boolean;
   onVoided: () => void;
+  onResolve: (m: MovementListItem) => void;
 }) {
   const [busy, setBusy] = useState(false);
 
@@ -844,11 +902,29 @@ function MovementRow({
         </span>
         <div className="tx-cur">
           {m.currency} · {directionLabel(m.direction)}
+          {m.outstanding && !m.voided && (
+            <>
+              {" · "}
+              <span className="tx-outstanding">sin fondos</span>
+            </>
+          )}
         </div>
       </td>
-      {canVoid && (
+      {(canVoid || canCapture) && (
         <td style={{ whiteSpace: "nowrap" }}>
-          {!m.voided && (
+          {/* Resolver only makes sense on a live outstanding row, and it's a
+              capture action (completing one), not a void. */}
+          {!m.voided && m.outstanding && canCapture && (
+            <button
+              type="button"
+              className="btn btn-ghost"
+              style={{ padding: "4px 10px", fontSize: 12 }}
+              onClick={() => onResolve(m)}
+            >
+              Resolver
+            </button>
+          )}
+          {!m.voided && canVoid && (
             <button
               type="button"
               className="btn btn-ghost"
@@ -865,6 +941,97 @@ function MovementRow({
   );
 }
 
+/**
+ * Resolve an outstanding row: the check finally got cut. Takes the check number
+ * and the date it was paid, which also becomes the movement's date — the legacy
+ * behavior, since the ledger date is when money actually moved.
+ */
+function ResolveDialog({
+  movement,
+  onDone,
+  onCancel,
+}: {
+  movement: MovementListItem;
+  onDone: () => void;
+  onCancel: () => void;
+}) {
+  const [checkNumber, setCheckNumber] = useState("");
+  const [resolvedDate, setResolvedDate] = useState(
+    new Date().toISOString().slice(0, 10),
+  );
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    if (!checkNumber.trim()) {
+      setError("Indica el número de cheque.");
+      return;
+    }
+    setBusy(true);
+    setError(null);
+    try {
+      await resolveOutstanding(movement.id, {
+        checkNumber: checkNumber.trim(),
+        resolvedDate,
+      });
+      onDone();
+    } catch (e2) {
+      setError((e2 as Error)?.message ?? "No se pudo resolver el movimiento.");
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="card" style={{ padding: 20, marginBottom: 16 }}>
+      <h2 className="section-title" style={{ marginBottom: 6 }}>
+        Resolver movimiento sin fondos
+      </h2>
+      <p className="muted" style={{ marginBottom: 14 }}>
+        {movement.customerName} · {formatMoney(movement.amount, movement.currency)}{" "}
+        {movement.currency}
+        {movement.reference ? ` · ${movement.reference}` : ""}
+      </p>
+      {error && <div className="state-box state-error">{error}</div>}
+      <form onSubmit={submit}>
+        <div className="form-grid">
+          <label className="field">
+            <span className="field-label">Número de cheque *</span>
+            <input
+              className="input"
+              value={checkNumber}
+              onChange={(e) => setCheckNumber(e.target.value)}
+              autoFocus
+            />
+          </label>
+          <label className="field">
+            <span className="field-label">Fecha de pago *</span>
+            <input
+              className="input"
+              type="date"
+              required
+              value={resolvedDate}
+              onChange={(e) => setResolvedDate(e.target.value)}
+            />
+          </label>
+        </div>
+        <p className="muted" style={{ fontSize: 13, marginTop: 10 }}>
+          El movimiento tomará esta fecha y empezará a contar en el saldo del
+          cliente.
+        </p>
+        <div className="form-actions">
+          <button type="submit" className="btn btn-primary" disabled={busy}>
+            {busy ? "Resolviendo…" : "Resolver"}
+          </button>
+          <button type="button" className="btn btn-outline" onClick={onCancel}>
+            Cancelar
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}
+
 function Pager({
   page,
   pageCount,

apps/web/src/app/inicio/page.tsx

@@ -0,0 +1,501 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import Link from "next/link";
+import { AppShell } from "@/components/AppShell";
+import {
+  EXPIRY_WINDOW_DAYS,
+  getBankStats,
+  getBillingStats,
+  getPolicyStats,
+  getPropertyStats,
+  getStats,
+  listBankAccounts,
+} from "@/lib/api";
+import { useAuth } from "@/lib/abilities";
+import {
+  balancePhrase,
+  formatDate,
+  formatMoney,
+  formatNumber,
+  policyStatusLabel,
+  trustStatusLabel,
+} from "@/lib/labels";
+import type {
+  BankAccount,
+  BankStats,
+  BillingStats,
+  CustomerStats,
+  PolicyStats,
+  PropertyStats,
+} from "@/lib/types";
+
+export default function InicioPage() {
+  return (
+    <AppShell>
+      <HomeDashboard />
+    </AppShell>
+  );
+}
+
+interface DashboardData {
+  customers: CustomerStats | null;
+  policies: PolicyStats | null;
+  properties: PropertyStats | null;
+  billing: BillingStats | null;
+  /** Figures for ONE chequera — see `bankAccount` for which. */
+  bank: BankStats | null;
+  /**
+   * The chequera the card above is reading. The office keeps more than one, in
+   * different currencies, so this card shows the default account rather than a
+   * cross-account total, which would be a figure that never existed.
+   */
+  bankAccount: BankAccount | null;
+  bankAccountCount: number;
+}
+
+/** Same default as /banco, so the two screens agree on which chequera opens. */
+function defaultAccount(accounts: BankAccount[]): BankAccount | null {
+  const remembered =
+    typeof window !== "undefined"
+      ? window.localStorage.getItem("banco.bankAccountId")
+      : null;
+  return (
+    accounts.find((a) => a.id === remembered) ??
+    accounts.find((a) => a.active) ??
+    accounts[0] ??
+    null
+  );
+}
+
+function HomeDashboard() {
+  const user = useAuth();
+  const [data, setData] = useState<DashboardData>({
+    customers: null,
+    policies: null,
+    properties: null,
+    billing: null,
+    bank: null,
+    bankAccount: null,
+    bankAccountCount: 0,
+  });
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let alive = true;
+    // The chequera figures need an account id, so that read is a two-step:
+    // list the accounts, then ask the default one for its stats.
+    const bank = listBankAccounts().then(async (accounts) => {
+      const account = defaultAccount(accounts);
+      if (!account) return { account: null, stats: null, count: 0 };
+      return {
+        account,
+        stats: await getBankStats(account.id),
+        count: accounts.length,
+      };
+    });
+
+    Promise.allSettled([
+      getStats(),
+      getPolicyStats(),
+      getPropertyStats(),
+      getBillingStats(),
+      bank,
+    ]).then((results) => {
+      if (!alive) return;
+      const bankResult = results[4].status === "fulfilled" ? results[4].value : null;
+      setData({
+        customers: results[0].status === "fulfilled" ? results[0].value : null,
+        policies: results[1].status === "fulfilled" ? results[1].value : null,
+        properties: results[2].status === "fulfilled" ? results[2].value : null,
+        billing: results[3].status === "fulfilled" ? results[3].value : null,
+        bank: bankResult?.stats ?? null,
+        bankAccount: bankResult?.account ?? null,
+        bankAccountCount: bankResult?.count ?? 0,
+      });
+      setLoading(false);
+    });
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  const greeting = greetingFor(user?.name);
+  const lastBillingMovement = data.billing?.lastMovement ?? null;
+  const lastBankMovement = data.bank?.lastMovement ?? null;
+
+  return (
+    <div className="home rise">
+      <div className="page-head">
+        <p className="eyebrow">Resumen general</p>
+        <h1 className="page-title">{greeting}</h1>
+        <p className="muted" style={{ marginTop: 6, maxWidth: 640 }}>
+          Vista rápida del estado de la cartera de clientes, las pólizas
+          activas, los fideicomisos y los movimientos recientes.
+        </p>
+        <LastSeenLine
+          billing={lastBillingMovement}
+          bank={lastBankMovement}
+          loading={loading}
+        />
+      </div>
+
+      <section aria-label="Indicadores principales" className="home-section">
+        <KpiCard
+          href="/clientes"
+          label="Clientes"
+          loading={loading}
+          primary={data.customers ? formatNumber(data.customers.customers) : "—"}
+          sub={
+            data.customers
+              ? [
+                  `${formatNumber(data.customers.withUtilities)} con servicios`,
+                  `${formatNumber(data.customers.withInsurance)} con seguros`,
+                  `${formatNumber(data.customers.bothLines)} en ambos ramos`,
+                ]
+              : []
+          }
+        />
+        <KpiCard
+          href="/servicios"
+          label="Propiedades"
+          loading={loading}
+          primary={data.properties ? formatNumber(data.properties.properties) : "—"}
+          sub={
+            data.properties
+              ? [
+                  `${formatNumber(data.properties.services)} servicios`,
+                  `${formatNumber(data.properties.trusts)} fideicomisos`,
+                  `${formatNumber(data.properties.trustExpiring)} por vencer`,
+                ]
+              : []
+          }
+        />
+        <KpiCard
+          href="/polizas"
+          label="Pólizas"
+          loading={loading}
+          primary={data.policies ? formatNumber(data.policies.total) : "—"}
+          sub={
+            data.policies
+              ? [
+                  `${formatNumber(data.policies.active)} vigentes`,
+                  `${formatNumber(data.policies.expiring)} por vencer (${EXPIRY_WINDOW_DAYS} d)`,
+                  `${formatNumber(data.policies.expired + data.policies.undated)} vencidas o sin fecha`,
+                ]
+              : []
+          }
+        />
+        <KpiCard
+          href="/estado-cuenta"
+          label="Movimientos"
+          loading={loading}
+          primary={data.billing ? formatNumber(data.billing.movements) : "—"}
+          sub={
+            data.billing
+              ? [
+                  `${formatNumber(data.billing.ledgerCustomers)} clientes con cargo`,
+                  `${formatNumber(data.billing.crossLineCustomers)} con ambos ramos`,
+                  lastBillingMovement
+                    ? `Último: ${formatDate(lastBillingMovement)}`
+                    : "Sin movimientos",
+                ]
+              : []
+          }
+        />
+      </section>
+
+      <section aria-label="Atención" className="home-section">
+        <div className="section-head">
+          <h2 className="section-title">Atención</h2>
+          <span className="section-sub">
+            Lo que conviene revisar antes de cerrar el día
+          </span>
+        </div>
+
+        <div className="attention-grid">
+          <AttentionCard
+            href="/polizas?status=expiring"
+            tone="warn"
+            loading={loading}
+            title="Pólizas por vencer"
+            primary={
+              data.policies ? formatNumber(data.policies.expiring) : "—"
+            }
+            sub={
+              data.policies
+                ? `En los próximos ${EXPIRY_WINDOW_DAYS} días — ventana: ${policyStatusLabel("expiring")}`
+                : undefined
+            }
+            meta={
+              data.policies
+                ? `${formatNumber(data.policies.active)} vigentes · ${formatNumber(data.policies.expired)} vencidas`
+                : undefined
+            }
+          />
+          <AttentionCard
+            href="/servicios?trust=expiring"
+            tone="warn"
+            loading={loading}
+            title="Fideicomisos por vencer"
+            primary={
+              data.properties ? formatNumber(data.properties.trustExpiring) : "—"
+            }
+            sub={
+              data.properties
+                ? `Renueva en los próximos ${EXPIRY_WINDOW_DAYS} días (${trustStatusLabel("expiring")})`
+                : undefined
+            }
+            meta={
+              data.properties
+                ? `${formatNumber(data.properties.trusts)} fideicomisos en cartera`
+                : undefined
+            }
+          />
+          <AttentionCard
+            href="/polizas?status=undated"
+            tone="muted"
+            loading={loading}
+            title="Pólizas sin vigencia"
+            primary={data.policies ? formatNumber(data.policies.undated) : "—"}
+            sub={
+              data.policies
+                ? "Sin fecha de fin registrada — revisar y completar"
+                : undefined
+            }
+            meta={
+              data.policies
+                ? `${formatNumber(data.policies.liquidated)} liquidadas`
+                : undefined
+            }
+          />
+          <AttentionCard
+            href="/estado-cuenta"
+            tone="info"
+            loading={loading}
+            title="Clientes con adeudo"
+            primary={
+              data.billing ? (
+                <CurrencyTotals
+                  totals={data.billing.byCurrency}
+                  field="owing"
+                />
+              ) : (
+                "—"
+              )
+            }
+            sub={
+              data.billing
+                ? `En ${formatNumber(data.billing.ledgerCustomers)} expedientes con cargo`
+                : undefined
+            }
+            meta={
+              data.billing
+                ? `${formatNumber(data.billing.crossLineCustomers)} clientes con cargo en ambos ramos`
+                : undefined
+            }
+          />
+          <AttentionCard
+            href="/banco"
+            tone="info"
+            loading={loading}
+            title="Chequera del despacho"
+            primary={
+              data.bank && data.bankAccount ? (
+                <span className={data.bank.net.startsWith("-") ? "money-neg" : "money-pos"}>
+                  {formatMoney(data.bank.net, data.bankAccount.currency)}
+                </span>
+              ) : (
+                "—"
+              )
+            }
+            // Names the account, because this is one chequera's figure and the
+            // office has more than one — they are never added together.
+            sub={
+              data.bank && data.bankAccount
+                ? `${data.bankAccount.label} · ${balancePhrase(data.bank.net)}`
+                : undefined
+            }
+            meta={
+              data.bank
+                ? `${formatNumber(data.bank.movements)} movimientos · ${formatNumber(data.bank.pending)} pendientes` +
+                  (data.bankAccountCount > 1
+                    ? ` · ${formatNumber(data.bankAccountCount)} cuentas en total`
+                    : "")
+                : undefined
+            }
+          />
+        </div>
+      </section>
+
+      <section aria-label="Accesos rápidos" className="home-section">
+        <div className="section-head">
+          <h2 className="section-title">Accesos rápidos</h2>
+          <span className="section-sub">
+            Ir directo a cada módulo
+          </span>
+        </div>
+        <div className="quick-grid">
+          <QuickLink href="/clientes" label="Clientes" sub="Directorio unificado" />
+          <QuickLink href="/servicios" label="Propiedades" sub="Servicios y fideicomisos" />
+          <QuickLink href="/polizas" label="Pólizas" sub="Vigencias y liquidaciones" />
+          <QuickLink href="/estado-cuenta" label="Estado de cuenta" sub="Cargos y abonos" />
+          <QuickLink href="/banco" label="Chequera" sub="Ingresos y egresos" />
+        </div>
+      </section>
+    </div>
+  );
+}
+
+function greetingFor(name?: string): string {
+  const hour = new Date().getHours();
+  const partOfDay =
+    hour < 12 ? "Buenos días" : hour < 19 ? "Buenas tardes" : "Buenas noches";
+  const display = (name ?? "").trim().split(/\s+/)[0];
+  return display ? `${partOfDay}, ${display}` : partOfDay;
+}
+
+function LastSeenLine({
+  billing,
+  bank,
+  loading,
+}: {
+  billing: string | null;
+  bank: string | null;
+  loading: boolean;
+}) {
+  if (loading) {
+    return (
+      <p className="muted home-last-seen" aria-hidden="true">
+        <span className="skeleton" style={{ display: "inline-block", width: 220, height: 12 }} />
+      </p>
+    );
+  }
+  if (!billing && !bank) return null;
+  return (
+    <p className="muted home-last-seen">
+      {billing && <>Último movimiento de cartera: <strong>{formatDate(billing)}</strong></>}
+      {billing && bank && <span aria-hidden="true"> · </span>}
+      {bank && <>Último movimiento de chequera: <strong>{formatDate(bank)}</strong></>}
+    </p>
+  );
+}
+
+function KpiCard({
+  href,
+  label,
+  primary,
+  sub,
+  loading,
+}: {
+  href: string;
+  label: string;
+  primary: React.ReactNode;
+  sub: string[];
+  loading: boolean;
+}) {
+  return (
+    <Link href={href} className="kpi-card card">
+      <div className="kpi-label">{label}</div>
+      <div className="kpi-primary">
+        {loading ? (
+          <span
+            className="skeleton"
+            style={{ display: "inline-block", width: 90, height: 30 }}
+          />
+        ) : (
+          primary
+        )}
+      </div>
+      <ul className="kpi-sub">
+        {loading
+          ? Array.from({ length: 3 }).map((_, i) => (
+              <li key={i} className="skeleton" style={{ height: 10 }} />
+            ))
+          : sub.map((line) => <li key={line}>{line}</li>)}
+      </ul>
+      <span className="kpi-cta" aria-hidden="true">
+        Ver módulo →
+      </span>
+    </Link>
+  );
+}
+
+function AttentionCard({
+  href,
+  tone,
+  title,
+  primary,
+  sub,
+  meta,
+  loading,
+}: {
+  href: string;
+  tone: "warn" | "info" | "muted";
+  title: string;
+  primary: React.ReactNode;
+  sub?: string;
+  meta?: string;
+  loading: boolean;
+}) {
+  return (
+    <Link href={href} className={`attention-card tone-${tone} card`}>
+      <div className="attention-head">
+        <span className="attention-title">{title}</span>
+        <span className="attention-arrow" aria-hidden="true">→</span>
+      </div>
+      <div className="attention-primary">
+        {loading ? (
+          <span
+            className="skeleton"
+            style={{ display: "inline-block", width: 70, height: 28 }}
+          />
+        ) : (
+          primary
+        )}
+      </div>
+      {sub && !loading && <div className="attention-sub">{sub}</div>}
+      {meta && !loading && <div className="attention-meta">{meta}</div>}
+    </Link>
+  );
+}
+
+function QuickLink({
+  href,
+  label,
+  sub,
+}: {
+  href: string;
+  label: string;
+  sub: string;
+}) {
+  return (
+    <Link href={href} className="quick-link card">
+      <span className="quick-label">{label}</span>
+      <span className="quick-sub">{sub}</span>
+      <span className="quick-arrow" aria-hidden="true">→</span>
+    </Link>
+  );
+}
+
+function CurrencyTotals({
+  totals,
+  field,
+}: {
+  totals: BillingStats["byCurrency"];
+  field: "owing" | "inCredit";
+}) {
+  if (!totals || totals.length === 0) return <>—</>;
+  return (
+    <span className="home-currency-totals">
+      {totals.map((c) => (
+        <span key={c.currency} className="home-currency-totals-row">
+          <span className="badge badge-count">{c.currency}</span>
+          <span className="home-currency-totals-num">
+            {formatNumber(c[field])}
+          </span>
+        </span>
+      ))}
+    </span>
+  );
+}

apps/web/src/app/layout.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
 import "./globals.css";
+import { readBuildInfoFromEnv } from "@/lib/build-info";
 
 export const metadata = {
   title: "Jorge Cuadros & Asociados — Plataforma",
@@ -7,10 +8,45 @@ export const metadata = {
     "Plataforma interna unificada de clientes, servicios y seguros.",
 };
 
+// The browser talks to the API cross-origin, so it needs the API URL at
+// runtime. NEXT_PUBLIC_* would bake it at build time (one URL per image); we
+// want the URL to come from the deploy .env instead. So read it here on the
+// server per request and inject it as window.__API_ORIGIN__ (see lib/api.ts).
+// force-dynamic guarantees process.env is read at request time, never baked
+// into a static prerender.
+export const dynamic = "force-dynamic";
+
 export default function RootLayout({ children }: { children: ReactNode }) {
+  const apiOrigin =
+    process.env.API_ORIGIN ??
+    process.env.NEXT_PUBLIC_API_ORIGIN ??
+    "http://localhost:3001";
+  // Same reason as the API origin: read on the server per request so the built
+  // image is not pinned to one build identity in its client bundle.
+  const build = readBuildInfoFromEnv();
+
   return (
     <html lang="es">
       <head>
+        {/* Must run before the app bundle so lib/api.ts sees it at import. */}
+        <script
+          dangerouslySetInnerHTML={{
+            __html:
+              `window.__API_ORIGIN__=${JSON.stringify(apiOrigin)};` +
+              `window.__APP_BUILD__=${JSON.stringify(build)};`,
+          }}
+        />
+        {/* Text-size preference, applied before first paint so the page never
+            flashes at the default size. Mirrors lib/ui-scale.ts — keep the key
+            and the clamp in sync with it. */}
+        <script
+          dangerouslySetInnerHTML={{
+            __html:
+              `try{var s=parseFloat(localStorage.getItem("jc.ui-scale"));` +
+              `if(isFinite(s))document.documentElement.style.setProperty(` +
+              `"--ui-scale",String(Math.min(1.5,Math.max(0.9,s))));}catch(e){}`,
+          }}
+        />
         {/* Google Fonts via <link> so an offline build still runs with the
             system fallback stacks defined in globals.css. */}
         <link rel="preconnect" href="https://fonts.googleapis.com" />

apps/web/src/app/login/page.tsx

@@ -16,7 +16,7 @@ export default function LoginPage() {
   useEffect(() => {
     let alive = true;
     me()
-      .then(() => router.replace("/clientes"))
+      .then(() => router.replace("/inicio"))
       .catch(() => {
         if (alive) setBootChecking(false);
       });
@@ -31,7 +31,7 @@ export default function LoginPage() {
     setSubmitting(true);
     try {
       await login(email.trim(), password);
-      router.replace("/clientes");
+      router.replace("/inicio");
     } catch (err) {
       if (err instanceof ApiError && err.status === 401) {
         setError("Correo o contraseña incorrectos");
@@ -65,9 +65,11 @@ export default function LoginPage() {
       <aside className="login-aside" aria-hidden="false">
         <div className="login-aside-top">
           <div className="login-brand">
-            <span className="brand-mark" aria-hidden>
-              JC
-            </span>
+            <img
+              src="/images/company_logo.png"
+              alt=""
+              className="brand-mark"
+            />
             <div className="brand-text">
               <span className="brand-name" style={{ color: "#f6f3ec" }}>
                 Jorge Cuadros

apps/web/src/app/operaciones/page.tsx

@@ -27,6 +27,8 @@ import type {
   OpsJobKind,
 } from "@/lib/types";
 
+const INGEST_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+
 export default function OperacionesPage() {
   return (
     <AppShell>
@@ -37,6 +39,7 @@ export default function OperacionesPage() {
 
 type ConfirmState =
   | { kind: "REIMPORT" }
+  | { kind: "SYNC" }
   | { kind: "RESTORE"; file: string }
   | null;
 
@@ -176,6 +179,7 @@ function Operaciones() {
     const c = confirm;
     setConfirm(null);
     if (c.kind === "REIMPORT") await start("REIMPORT");
+    else if (c.kind === "SYNC") await start("SYNC");
     else await start("RESTORE", c.file);
   }
 
@@ -224,7 +228,7 @@ function Operaciones() {
         <h2 className="section-title">Carpeta de ingesta</h2>
         <p className="inline-form-note">
           Los cuatro archivos originales de Access. La reimportación y la
-          sincronización leen de aquí.
+          sincronización leen de aquí. Tamaño máximo por archivo: {formatBytes(INGEST_MAX_BYTES)}.
         </p>
         <div className="tx-scroll">
           <table className="tx-table">
@@ -306,11 +310,11 @@ function Operaciones() {
           />
           <OpTile
             title="Sincronizar"
-            desc="Conserva los datos actuales e importa solo lo nuevo del legado. Disponible en la Fase B."
-            action="Próximamente"
-            tone="muted"
-            disabled
-            onClick={() => {}}
+            desc="Respalda, luego importa lo nuevo del legado. Borra del sistema los registros del legado que ya no aparecen en los archivos de ingesta. Se conservan los datos capturados a mano."
+            action="Sincronizar"
+            tone="primary"
+            disabled={jobRunning || starting || !ingestReady}
+            onClick={() => askConfirm({ kind: "SYNC" })}
           />
         </div>
         {!ingestReady && (
@@ -446,11 +450,17 @@ function Operaciones() {
         <div className="modal-backdrop" role="dialog" aria-modal="true">
           <div className="card" style={{ padding: 24, maxWidth: 480 }}>
             <h2 className="section-title" style={{ marginTop: 0 }}>
-              {confirm.kind === "REIMPORT" ? "Confirmar reimportación" : "Confirmar restauración"}
+              {confirm.kind === "REIMPORT"
+                ? "Confirmar reimportación"
+                : confirm.kind === "SYNC"
+                  ? "Confirmar sincronización"
+                  : "Confirmar restauración"}
             </h2>
             <p className="inline-form-note">
               {confirm.kind === "REIMPORT"
                 ? "Esto BORRA todos los datos actuales (incluidos los capturados a mano) y reconstruye desde los archivos de ingesta. Se creará un respaldo previo automático."
+                : confirm.kind === "SYNC"
+                  ? "Se creará un respaldo previo automático. Luego se importarán al sistema los registros nuevos del legado y se eliminarán los del legado que ya no aparezcan en los archivos de ingesta. Los datos capturados a mano NO se borran."
                   : `Esto sobreescribe la base de datos completa con “${confirm.file}”. Se recomienda crear un respaldo antes.`}
             </p>
             <label className="field">
@@ -464,12 +474,16 @@ function Operaciones() {
             </label>
             <div className="form-actions">
               <button
-                className="btn btn-danger"
+                className={confirm.kind === "SYNC" ? "btn btn-primary" : "btn btn-danger"}
                 type="button"
                 disabled={confirmText !== "CONFIRMAR" || starting}
                 onClick={runConfirmed}
               >
-                {confirm.kind === "REIMPORT" ? "Reimportar" : "Restaurar"}
+                {confirm.kind === "REIMPORT"
+                  ? "Reimportar"
+                  : confirm.kind === "SYNC"
+                    ? "Sincronizar"
+                    : "Restaurar"}
               </button>
               <button className="btn btn-outline" type="button" onClick={() => setConfirm(null)}>
                 Cancelar

apps/web/src/app/page.tsx

@@ -1,5 +1,5 @@
 import { redirect } from "next/navigation";
 
 export default function HomePage() {
-  redirect("/clientes");
+  redirect("/inicio");
 }

apps/web/src/app/polizas/[id]/page.tsx

@@ -3,14 +3,18 @@
 import { useEffect, useState } from "react";
 import Link from "next/link";
 import { AppShell } from "@/components/AppShell";
+import { ContextReports } from "@/components/ContextReports";
 import {
   addPolicyChild,
   archivePolicy,
   getLookups,
   getPolicy,
+  policyDocumentDownloadUrl,
   removePolicyChild,
+  removePolicyDocument,
   restorePolicy,
   updatePolicyChild,
+  uploadPolicyDocument,
 } from "@/lib/api";
 import { useCan } from "@/lib/abilities";
 import { ChildCollection, type ChildConfig } from "@/components/ChildCollection";
@@ -89,6 +93,15 @@ function Detail({ id }: { id: string }) {
     <div className="rise">
       <div className="detail-actionbar">
         <BackLink />
+        <ContextReports
+          entries={[
+            {
+              slug: "edo-cuenta-datos",
+              label: "Estado de cuenta del cliente",
+              params: { customerId: data.customer.id },
+            },
+          ]}
+        />
         <PolicyActions data={data} onChange={reload} />
       </div>
       <Hero data={data} />
@@ -101,7 +114,7 @@ function Detail({ id }: { id: string }) {
       )}
       {data.claims.length > 0 && <SiniestrosSection data={data} />}
       <CoberturasSection data={data} />
-      <DocumentosSection data={data} />
+      <DocumentosSection data={data} onChange={reload} />
       <ChildrenEditor data={data} onChange={reload} />
     </div>
   );
@@ -664,7 +677,35 @@ function CoberturasSection({ data }: { data: PolicyDetail }) {
 }
 
 /* -------------------------------------------------------- Documentos */
-function DocumentosSection({ data }: { data: PolicyDetail }) {
+function DocumentosSection({
+  data,
+  onChange,
+}: {
+  data: PolicyDetail;
+  onChange: () => void;
+}) {
+  const canEdit = useCan("policy:update");
+  const [file, setFile] = useState<File | null>(null);
+  const [type, setType] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function upload() {
+    if (!file) return;
+    setBusy(true);
+    setError(null);
+    try {
+      await uploadPolicyDocument(data.id, file, type.trim() || undefined);
+      setFile(null);
+      setType("");
+      onChange();
+    } catch (e) {
+      setError((e as Error)?.message ?? "No se pudo subir el archivo.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
   return (
     <section className="section">
       <SectionHead rule="docs" title="Documentos" count={data.documents.length} />
@@ -674,25 +715,74 @@ function DocumentosSection({ data }: { data: PolicyDetail }) {
             No hay documentos registrados para esta póliza.
           </div>
         ) : (
-          <>
           <div className="doc-list">
             {data.documents.map((d, i) => (
               <div className="doc-item" key={d.id ?? i}>
                 <span className="doc-icon" aria-hidden>
                   ▤
                 </span>
-                  <div style={{ minWidth: 0 }}>
+                <div style={{ minWidth: 0, flex: 1 }}>
                   <div className="doc-type">{d.documentType || "Documento"}</div>
                   <div className="doc-key">{d.storageKey || "—"}</div>
                 </div>
+                {d.id && (
+                  <a
+                    className="btn btn-ghost"
+                    href={policyDocumentDownloadUrl(data.id, d.id)}
+                  >
+                    Descargar
+                  </a>
+                )}
+                {canEdit && d.id && (
+                  <button
+                    type="button"
+                    className="btn btn-ghost"
+                    onClick={async () => {
+                      if (!window.confirm("¿Eliminar este documento?")) return;
+                      try {
+                        await removePolicyDocument(data.id, d.id!);
+                        onChange();
+                      } catch (e) {
+                        window.alert((e as Error)?.message ?? "No se pudo eliminar.");
+                      }
+                    }}
+                  >
+                    Eliminar
+                  </button>
+                )}
               </div>
             ))}
           </div>
-            <div className="section-note" style={{ padding: "0 22px 18px" }}>
-              Los archivos se almacenan en el object storage (storageKey); no se
-              descargan desde esta vista.
+        )}
+        {canEdit && (
+          <div style={{ padding: "0 22px 18px" }}>
+            {error && (
+              <div className="state-box state-error" style={{ marginBottom: 12 }}>
+                {error}
+              </div>
+            )}
+            <div className="inline-form">
+              <input
+                className="input"
+                placeholder="Tipo (ej. CARATULA)"
+                value={type}
+                onChange={(e) => setType(e.target.value)}
+              />
+              <input
+                type="file"
+                className="input"
+                onChange={(e) => setFile(e.target.files?.[0] ?? null)}
+              />
+              <button
+                type="button"
+                className="btn btn-primary"
+                disabled={!file || busy}
+                onClick={upload}
+              >
+                {busy ? "Subiendo…" : "Subir"}
+              </button>
+            </div>
           </div>
-          </>
         )}
       </div>
     </section>

apps/web/src/app/polizas/page.tsx

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import Link from "next/link";
 import { AppShell } from "@/components/AppShell";
+import { ContextReports } from "@/components/ContextReports";
 import { useCan } from "@/lib/abilities";
 import {
   EXPIRY_WINDOW_DAYS,
@@ -127,6 +128,13 @@ function PolizasBrowser() {
         <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
           <h1 className="page-title" style={{ margin: 0 }}>Pólizas</h1>
           <span style={{ flex: 1 }} />
+          <ContextReports
+            entries={[
+              { slug: "vigente", label: "Por vencer (Lic.)", params: { typeName: "LICENCIAS" } },
+              { slug: "vigente", label: "Por vencer (Mult.)", params: { typeName: "MULT" } },
+              { slug: "vigente", label: "Por vencer (Incen.)", params: { typeName: "INCEN" } },
+            ]}
+          />
           {canCreate && (
             <Link href="/polizas/nuevo" className="btn btn-primary">+ Nueva póliza</Link>
           )}

apps/web/src/app/recibos/[id]/page.tsx

@@ -0,0 +1,478 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import Link from "next/link";
+import { AppShell } from "@/components/AppShell";
+import { CustomerPicker } from "@/components/CustomerPicker";
+import {
+  confirmStatementBatch,
+  getStatementBatch,
+  listStatementDocuments,
+  rejectStatementDocument,
+  reviewStatementDocument,
+  statementPageUrl,
+} from "@/lib/api";
+import { useCan } from "@/lib/abilities";
+import { formatDate, formatMoney, serviceKindLabel } from "@/lib/labels";
+import type {
+  ConfirmBatchInput,
+  StatementBatchDetail,
+  StatementDocument,
+  StatementDocumentStatus,
+} from "@/lib/types";
+
+/**
+ * Review queue for one batch of scanned bills.
+ *
+ * The reviewer's job is to answer one question per page — "is this the right
+ * customer for this amount?" — so the page image sits next to the extracted
+ * fields and every row can be corrected in place. Rows the matcher is sure
+ * about are pre-approved and can be posted in bulk; everything else is listed
+ * first, because that is the work.
+ */
+
+const STATUS_LABEL: Record<StatementDocumentStatus, string> = {
+  PENDING_OCR: "En proceso",
+  OCR_FAILED: "No se pudo leer",
+  NEEDS_REVIEW: "Requiere revisión",
+  MATCHED: "Identificado",
+  CONFIRMED: "Confirmado",
+  POSTED: "Registrado",
+  REJECTED: "Descartado",
+};
+
+/** Rows still needing a decision, listed before the settled ones. */
+const OPEN_FIRST: StatementDocumentStatus[] = [
+  "NEEDS_REVIEW",
+  "OCR_FAILED",
+  "MATCHED",
+  "CONFIRMED",
+  "POSTED",
+  "REJECTED",
+  "PENDING_OCR",
+];
+
+export default function RecibosBatchPage({ params }: { params: { id: string } }) {
+  return (
+    <AppShell>
+      <BatchReview id={params.id} />
+    </AppShell>
+  );
+}
+
+function BatchReview({ id }: { id: string }) {
+  const canReview = useCan("statement:review");
+  const [batch, setBatch] = useState<StatementBatchDetail | null>(null);
+  const [docs, setDocs] = useState<StatementDocument[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  const load = useCallback(async () => {
+    try {
+      const [b, d] = await Promise.all([
+        getStatementBatch(id),
+        listStatementDocuments(id),
+      ]);
+      setBatch(b);
+      setDocs(d);
+      setError(null);
+    } catch (e) {
+      setError((e as Error)?.message ?? "No se pudo cargar el lote.");
+    } finally {
+      setLoading(false);
+    }
+  }, [id]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const processing = batch?.status === "PROCESSING" || batch?.status === "UPLOADED";
+  useEffect(() => {
+    if (!processing) return;
+    const t = setInterval(() => void load(), 4000);
+    return () => clearInterval(t);
+  }, [processing, load]);
+
+  const sorted = useMemo(
+    () =>
+      [...docs].sort(
+        (a, b) =>
+          OPEN_FIRST.indexOf(a.status) - OPEN_FIRST.indexOf(b.status) ||
+          a.pageNumber - b.pageNumber,
+      ),
+    [docs],
+  );
+
+  const readyCount = docs.filter(
+    (d) => d.status === "MATCHED" && d.matchedCustomer,
+  ).length;
+
+  if (loading) return <div className="state-box">Cargando…</div>;
+  if (!batch) return <div className="state-box state-error">{error ?? "No encontrado."}</div>;
+
+  return (
+    <div className="stack">
+      <header className="page-head">
+        <div>
+          <h1 className="page-title">
+            Recibos — {serviceKindLabel(batch.serviceKind)}
+            {batch.label ? ` · ${batch.label}` : ""}
+          </h1>
+          <p className="page-sub">
+            {formatDate(batch.createdAt)} · {docs.length} página(s) ·{" "}
+            {STATUS_LABEL_BATCH[batch.status] ?? batch.status}
+          </p>
+        </div>
+        <Link className="btn btn-ghost" href="/recibos">
+          Volver a captura
+        </Link>
+      </header>
+
+      {error && <div className="state-box state-error">{error}</div>}
+
+      {processing && (
+        <div className="state-box">
+          Leyendo los recibos… esta pantalla se actualiza sola.
+        </div>
+      )}
+
+      <SummaryCard batch={batch} readyCount={readyCount} />
+
+      {canReview && readyCount > 0 && (
+        <ConfirmCard
+          batchId={id}
+          readyCount={readyCount}
+          onDone={load}
+          setError={setError}
+        />
+      )}
+
+      <section className="stack">
+        {sorted.map((doc) => (
+          <DocumentRow
+            key={doc.id}
+            doc={doc}
+            canReview={canReview}
+            onChange={load}
+          />
+        ))}
+      </section>
+    </div>
+  );
+}
+
+const STATUS_LABEL_BATCH: Record<string, string> = {
+  UPLOADED: "Recibido",
+  PROCESSING: "Procesando",
+  READY_FOR_REVIEW: "Listo para revisar",
+  COMPLETED: "Registrado",
+  FAILED: "Falló",
+};
+
+function SummaryCard({
+  batch,
+  readyCount,
+}: {
+  batch: StatementBatchDetail;
+  readyCount: number;
+}) {
+  const entries = Object.entries(batch.byStatus) as [StatementDocumentStatus, number][];
+  return (
+    <section className="card" style={{ padding: 16 }}>
+      <div className="inline-form" style={{ flexWrap: "wrap", gap: 20 }}>
+        {entries.map(([status, count]) => (
+          <div key={status}>
+            <div className="page-sub">{STATUS_LABEL[status] ?? status}</div>
+            <div style={{ fontSize: "1.4rem", fontWeight: 600 }}>{count}</div>
+          </div>
+        ))}
+        <div>
+          <div className="page-sub">Importe pendiente</div>
+          <div style={{ fontSize: "1.4rem", fontWeight: 600 }}>
+            {formatMoney(batch.pendingTotal, "MXN")}
+          </div>
+        </div>
+        <div>
+          <div className="page-sub">Listos para registrar</div>
+          <div style={{ fontSize: "1.4rem", fontWeight: 600 }}>{readyCount}</div>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+/**
+ * Posting is by check, exactly as on the manual capture screen — an OCR batch
+ * is still "these bills, paid with this check", so the same fields are asked
+ * for and the same ledger path is used.
+ */
+function ConfirmCard({
+  batchId,
+  readyCount,
+  onDone,
+  setError,
+}: {
+  batchId: string;
+  readyCount: number;
+  onDone: () => void;
+  setError: (m: string | null) => void;
+}) {
+  const [checkNumber, setCheckNumber] = useState("");
+  const [transactionDate, setTransactionDate] = useState(
+    new Date().toISOString().slice(0, 10),
+  );
+  const [outstanding, setOutstanding] = useState(false);
+  const [includeReviewed, setIncludeReviewed] = useState(true);
+  const [busy, setBusy] = useState(false);
+  const [result, setResult] = useState<string | null>(null);
+
+  async function submit() {
+    if (!checkNumber.trim()) return;
+    setBusy(true);
+    setError(null);
+    try {
+      const input: ConfirmBatchInput = {
+        checkNumber: checkNumber.trim(),
+        transactionDate,
+        outstanding,
+        includeReviewed,
+      };
+      const r = await confirmStatementBatch(batchId, input);
+      setResult(
+        `Se registraron ${r.posted} movimiento(s) por ${formatMoney(r.total, "MXN")} con el cheque ${r.checkNumber}.`,
+      );
+      setCheckNumber("");
+      onDone();
+    } catch (e) {
+      setError((e as Error)?.message ?? "No se pudo registrar el lote.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <section className="card" style={{ padding: 16 }}>
+      <h2 className="section-title" style={{ marginTop: 0 }}>
+        Registrar {readyCount} recibo(s)
+      </h2>
+      <div className="inline-form" style={{ flexWrap: "wrap", gap: 12 }}>
+        <label>
+          <span className="page-sub">Cheque</span>
+          <input
+            className="input"
+            value={checkNumber}
+            onChange={(e) => setCheckNumber(e.target.value)}
+            placeholder="Número de cheque"
+          />
+        </label>
+        <label>
+          <span className="page-sub">Fecha</span>
+          <input
+            type="date"
+            className="input"
+            value={transactionDate}
+            onChange={(e) => setTransactionDate(e.target.value)}
+          />
+        </label>
+        <label className="check">
+          <input
+            type="checkbox"
+            checked={outstanding}
+            onChange={(e) => setOutstanding(e.target.checked)}
+          />{" "}
+          Sin fondos (queda pendiente)
+        </label>
+        <label className="check">
+          <input
+            type="checkbox"
+            checked={includeReviewed}
+            onChange={(e) => setIncludeReviewed(e.target.checked)}
+          />{" "}
+          Incluir los confirmados a mano
+        </label>
+        <button
+          type="button"
+          className="btn btn-primary"
+          disabled={!checkNumber.trim() || busy}
+          onClick={submit}
+        >
+          {busy ? "Registrando…" : "Registrar"}
+        </button>
+      </div>
+      {result && (
+        <div className="state-box" style={{ marginTop: 12 }}>
+          {result}
+        </div>
+      )}
+      <p className="page-sub" style={{ marginTop: 12 }}>
+        Se registran como cargos del cliente, por la misma vía que la captura
+        manual. Un lote registrado dos veces no duplica cobros.
+      </p>
+    </section>
+  );
+}
+
+function DocumentRow({
+  doc,
+  canReview,
+  onChange,
+}: {
+  doc: StatementDocument;
+  canReview: boolean;
+  onChange: () => void;
+}) {
+  const [open, setOpen] = useState(
+    doc.status === "NEEDS_REVIEW" || doc.status === "OCR_FAILED",
+  );
+  const [amount, setAmount] = useState(doc.extractedAmount ?? "");
+  const [accountRef, setAccountRef] = useState(doc.extractedAccountRef ?? "");
+  const [customerId, setCustomerId] = useState(doc.matchedCustomer?.id ?? "");
+  const [customerName, setCustomerName] = useState(doc.matchedCustomer?.name ?? "");
+  const [busy, setBusy] = useState(false);
+  const [err, setErr] = useState<string | null>(null);
+
+  const settled = doc.status === "POSTED" || doc.status === "REJECTED";
+
+  async function save(status: "MATCHED" | "CONFIRMED") {
+    setBusy(true);
+    setErr(null);
+    try {
+      await reviewStatementDocument(doc.id, {
+        accountRef: accountRef.trim() || undefined,
+        amount: amount ? Number(amount) : undefined,
+        matchedCustomerId: customerId || undefined,
+        status,
+      });
+      onChange();
+    } catch (e) {
+      setErr((e as Error)?.message ?? "No se pudo guardar.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function reject() {
+    setBusy(true);
+    setErr(null);
+    try {
+      await rejectStatementDocument(doc.id);
+      onChange();
+    } catch (e) {
+      setErr((e as Error)?.message ?? "No se pudo descartar.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div className="card" style={{ padding: 16 }}>
+      <div
+        className="inline-form"
+        style={{ justifyContent: "space-between", flexWrap: "wrap", gap: 12 }}
+      >
+        <div>
+          <strong>Página {doc.pageNumber}</strong>{" "}
+          <span className="tag">{STATUS_LABEL[doc.status] ?? doc.status}</span>{" "}
+          {doc.provider && <span className="page-sub">{doc.provider}</span>}
+          <div className="page-sub" style={{ marginTop: 4 }}>
+            {doc.matchedCustomer ? (
+              <Link href={`/clientes/${doc.matchedCustomer.id}`}>
+                {doc.matchedCustomer.name}
+              </Link>
+            ) : (
+              "Sin cliente asignado"
+            )}
+            {doc.extractedAccountRef && ` · cuenta ${doc.extractedAccountRef}`}
+            {doc.extractedCadastralKey && ` · clave ${doc.extractedCadastralKey}`}
+          </div>
+          {doc.matchNote && (
+            <div className="page-sub" style={{ marginTop: 4 }}>
+              {doc.matchNote}
+            </div>
+          )}
+        </div>
+        <div className="inline-form" style={{ gap: 8 }}>
+          <strong>
+            {doc.extractedAmount
+              ? formatMoney(doc.extractedAmount, "MXN")
+              : "sin importe"}
+          </strong>
+          <button
+            type="button"
+            className="btn btn-ghost"
+            onClick={() => setOpen((v) => !v)}
+          >
+            {open ? "Ocultar" : "Ver recibo"}
+          </button>
+        </div>
+      </div>
+
+      {open && (
+        <div style={{ marginTop: 12, display: "grid", gap: 16 }}>
+          {/* The scan itself — the reviewer's source of truth, not the OCR. */}
+          <img
+            src={statementPageUrl(doc.id)}
+            alt={`Recibo página ${doc.pageNumber}`}
+            style={{
+              maxWidth: "100%",
+              border: "1px solid var(--border, #ddd)",
+              borderRadius: 6,
+            }}
+          />
+
+          {canReview && !settled && (
+            <div className="inline-form" style={{ flexWrap: "wrap", gap: 12 }}>
+              <label>
+                <span className="page-sub">Cuenta</span>
+                <input
+                  className="input"
+                  value={accountRef}
+                  onChange={(e) => setAccountRef(e.target.value)}
+                />
+              </label>
+              <label>
+                <span className="page-sub">Importe</span>
+                <input
+                  className="input"
+                  inputMode="decimal"
+                  value={amount}
+                  onChange={(e) => setAmount(e.target.value)}
+                />
+              </label>
+              <div style={{ minWidth: 260 }}>
+                <span className="page-sub">Cliente</span>
+                <CustomerPicker
+                  value={customerId}
+                  valueName={customerName}
+                  onPick={(cid, name) => {
+                    setCustomerId(cid);
+                    setCustomerName(name);
+                  }}
+                />
+              </div>
+              <button
+                type="button"
+                className="btn btn-primary"
+                disabled={busy || !customerId}
+                onClick={() => save("MATCHED")}
+              >
+                Guardar
+              </button>
+              <button
+                type="button"
+                className="btn btn-ghost"
+                disabled={busy}
+                onClick={reject}
+              >
+                Descartar
+              </button>
+            </div>
+          )}
+
+          {err && <div className="state-box state-error">{err}</div>}
+        </div>
+      )}
+    </div>
+  );
+}

apps/web/src/app/recibos/page.tsx

@@ -0,0 +1,15 @@
+import { AppShell } from "@/components/AppShell";
+import { Captura } from "@/components/Captura";
+
+/**
+ * Same capture screen as `/estado-cuenta/lote`, opened on the automatic
+ * (scanned recibos + OCR) mode. Kept as its own route so links from a batch
+ * review page and older bookmarks land on the right tab.
+ */
+export default function RecibosPage() {
+  return (
+    <AppShell>
+      <Captura initialMode="auto" />
+    </AppShell>
+  );
+}

apps/web/src/app/reportes/[slug]/page.tsx

@@ -0,0 +1,110 @@
+"use client";
+
+import Link from "next/link";
+import { useEffect, useState } from "react";
+import { AppShell } from "@/components/AppShell";
+import { ReportRunner } from "@/components/ReportRunner";
+import { getReportCatalog } from "@/lib/api";
+import type { ReportDef } from "@/lib/types";
+
+/**
+ * /reportes/[slug] — one report's runner page. The whole page is
+ * data-driven from the catalog; if a slug isn't in the registry the
+ * page shows a "not found" inline message.
+ */
+export default function ReporteRunnerPage({
+  params,
+  searchParams,
+}: {
+  params: { slug: string };
+  searchParams?: Record<string, string | string[] | undefined>;
+}) {
+  return (
+    <AppShell>
+      <Runner slug={params.slug} searchParams={searchParams} />
+    </AppShell>
+  );
+}
+
+function Runner({
+  slug,
+  searchParams,
+}: {
+  slug: string;
+  searchParams?: Record<string, string | string[] | undefined>;
+}) {
+  const [def, setDef] = useState<ReportDef | null>(null);
+  const [missing, setMissing] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    getReportCatalog()
+      .then((c) => {
+        const found = c.items.find((r) => r.slug === slug);
+        if (found) setDef(found);
+        else setMissing(true);
+      })
+      .catch((e) => setError(e?.message ?? "No se pudo cargar el reporte."));
+  }, [slug]);
+
+  if (error) {
+    return (
+      <>
+        <BackLink />
+        <div className="report-error">{error}</div>
+      </>
+    );
+  }
+  if (missing) {
+    return (
+      <>
+        <BackLink />
+        <div className="empty-inline">Reporte "{slug}" no encontrado.</div>
+      </>
+    );
+  }
+  if (!def) {
+    return (
+      <>
+        <BackLink />
+        <div className="empty-inline">Cargando reporte…</div>
+      </>
+    );
+  }
+
+  const initialParams: Record<string, string> = {};
+  if (searchParams) {
+    const allowed = new Set(def.params.map((p) => p.key));
+    for (const [k, v] of Object.entries(searchParams)) {
+      if (!allowed.has(k)) continue;
+      const s = Array.isArray(v) ? v[0] : v;
+      if (s) initialParams[k] = s;
+    }
+  }
+
+  return (
+    <>
+      <div className="page-head rise">
+        <p className="eyebrow">Reportes</p>
+        <h1 className="page-title">{def.title}</h1>
+        <p className="muted" style={{ marginTop: 6, maxWidth: 720 }}>
+          {def.description}
+        </p>
+        {def.legacyName && (
+          <p className="muted small" style={{ marginTop: 4 }}>
+            Equivalente en Access: <code>{def.legacyName}</code>
+          </p>
+        )}
+      </div>
+      <ReportRunner def={def} initialParams={initialParams} />
+    </>
+  );
+}
+
+function BackLink() {
+  return (
+    <Link href="/reportes" className="back-link">
+      ← Reportes
+    </Link>
+  );
+}

apps/web/src/app/reportes/page.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import Link from "next/link";
+import { useEffect, useState } from "react";
+import { AppShell } from "@/components/AppShell";
+import { getReportCatalog } from "@/lib/api";
+import type { ReportCatalog, ReportDef, ReportDomain } from "@/lib/types";
+
+/**
+ * The /reportes catalog. Index of every registered report, grouped by
+ * domain (matches the main nav). Discovery layer for the 280+ reports
+ * the system will eventually surface; for now we ship 6 in v1.
+ */
+export default function ReportesPage() {
+  return (
+    <AppShell>
+      <ReportesCatalog />
+    </AppShell>
+  );
+}
+
+const DOMAIN_LABEL: Record<ReportDomain, string> = {
+  clientes: "Clientes",
+  polizas: "Pólizas",
+  servicios: "Servicios",
+  "estado-cuenta": "Estado de cuenta",
+  chequera: "Chequera",
+};
+
+const DOMAIN_ORDER: ReportDomain[] = [
+  "clientes",
+  "estado-cuenta",
+  "polizas",
+  "servicios",
+  "chequera",
+];
+
+function ReportesCatalog() {
+  const [catalog, setCatalog] = useState<ReportCatalog | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    getReportCatalog()
+      .then(setCatalog)
+      .catch((e) => setError(e?.message ?? "No se pudo cargar el catálogo."));
+  }, []);
+
+  const grouped = new Map<ReportDomain, ReportDef[]>();
+  if (catalog) {
+    for (const r of catalog.items) {
+      const list = grouped.get(r.domain) ?? [];
+      list.push(r);
+      grouped.set(r.domain, list);
+    }
+  }
+
+  return (
+    <>
+      <div className="page-head rise">
+        <p className="eyebrow">Reportes</p>
+        <h1 className="page-title">Catálogo de reportes</h1>
+        <p className="muted" style={{ marginTop: 6, maxWidth: 640 }}>
+          {catalog
+            ? `${catalog.items.length} reportes disponibles. Cada uno corre como consulta sobre el esquema actual — los filtros y totales se recalculan en vivo.`
+            : "Cargando…"}
+        </p>
+      </div>
+
+      {error && <div className="report-error">{error}</div>}
+
+      <div className="report-catalog">
+        {DOMAIN_ORDER.filter((d) => grouped.has(d)).map((d) => (
+          <section key={d} className="report-catalog-group">
+            <h2 className="report-catalog-title">{DOMAIN_LABEL[d]}</h2>
+            <ul className="report-catalog-list">
+              {(grouped.get(d) ?? []).map((r) => (
+                <li key={r.slug} className="report-catalog-item">
+                  <Link href={`/reportes/${r.slug}`} className="report-catalog-link">
+                    <div className="report-catalog-item-title">{r.title}</div>
+                    <div className="report-catalog-item-desc">{r.description}</div>
+                    <div className="report-catalog-item-meta">
+                      {r.legacyName && (
+                        <span className="report-catalog-tag">
+                          Legacy: {r.legacyName}
+                        </span>
+                      )}
+                      <span className="report-catalog-tag muted">
+                        {r.format === "statement" ? "Estado de cuenta" : "Tabular"}
+                      </span>
+                    </div>
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </section>
+        ))}
+      </div>
+    </>
+  );
+}

apps/web/src/app/servicios/[id]/page.tsx

@@ -7,11 +7,13 @@ import {
   addService,
   archiveProperty,
   getProperty,
+  propertyDocumentDownloadUrl,
   removePropertyDocument,
   removeService,
   removeTrust,
   restoreProperty,
   updateService,
+  uploadPropertyDocument,
   upsertTrust,
 } from "@/lib/api";
 import { useCan } from "@/lib/abilities";
@@ -206,9 +208,44 @@ function PropertyEditor({
 
       <TrustEditor data={data} onChange={onChange} />
 
-      {data.documents.length > 0 && (
+      <DocumentsEditor data={data} onChange={onChange} />
+    </section>
+  );
+}
+
+/** Upload / download / delete document blobs stored in object storage (MinIO). */
+function DocumentsEditor({
+  data,
+  onChange,
+}: {
+  data: PropertyDetail;
+  onChange: () => void;
+}) {
+  const [file, setFile] = useState<File | null>(null);
+  const [type, setType] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function upload() {
+    if (!file) return;
+    setBusy(true);
+    setError(null);
+    try {
+      await uploadPropertyDocument(data.id, file, type.trim() || undefined);
+      setFile(null);
+      setType("");
+      onChange();
+    } catch (e) {
+      setError((e as Error)?.message ?? "No se pudo subir el archivo.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
     <div className="card" style={{ padding: 16 }}>
       <h3 className="section-title" style={{ marginTop: 0 }}>Documentos</h3>
+      {data.documents.length > 0 && (
         <div className="tx-scroll">
           <table className="tx-table">
             <thead>
@@ -221,6 +258,14 @@ function PropertyEditor({
                   <td className="mono">{d.storageKey ?? "—"}</td>
                   <td>
                     <div className="row-actions">
+                      {d.id && (
+                        <a
+                          className="btn btn-ghost"
+                          href={propertyDocumentDownloadUrl(data.id, d.id)}
+                        >
+                          Descargar
+                        </a>
+                      )}
                       <button
                         type="button"
                         className="btn btn-ghost"
@@ -244,13 +289,30 @@ function PropertyEditor({
             </tbody>
           </table>
         </div>
-          <p className="inline-form-note">
-            La carga de nuevos documentos requiere el almacenamiento de archivos
-            (pendiente); aquí solo se pueden eliminar los existentes.
-          </p>
-        </div>
       )}
-    </section>
+      {error && <div className="state-box state-error" style={{ marginTop: 12 }}>{error}</div>}
+      <div className="inline-form" style={{ marginTop: 12 }}>
+        <input
+          className="input"
+          placeholder="Tipo (ej. RECIBO)"
+          value={type}
+          onChange={(e) => setType(e.target.value)}
+        />
+        <input
+          type="file"
+          className="input"
+          onChange={(e) => setFile(e.target.files?.[0] ?? null)}
+        />
+        <button
+          type="button"
+          className="btn btn-primary"
+          disabled={!file || busy}
+          onClick={upload}
+        >
+          {busy ? "Subiendo…" : "Subir"}
+        </button>
+      </div>
+    </div>
   );
 }
 
@@ -744,17 +806,21 @@ function DocumentosSection({ data }: { data: PropertyDetail }) {
                   <span className="doc-icon" aria-hidden>
                     ▤
                   </span>
-                  <div style={{ minWidth: 0 }}>
+                  <div style={{ minWidth: 0, flex: 1 }}>
                     <div className="doc-type">{d.documentType || "Documento"}</div>
                     <div className="doc-key">{d.storageKey || "—"}</div>
                   </div>
+                  {d.id && (
+                    <a
+                      className="btn btn-ghost"
+                      href={propertyDocumentDownloadUrl(data.id, d.id)}
+                    >
+                      Descargar
+                    </a>
+                  )}
                 </div>
               ))}
             </div>
-            <div className="section-note" style={{ padding: "0 22px 18px" }}>
-              Los archivos se almacenan en el object storage (storageKey); no se
-              descargan desde esta vista.
-            </div>
           </>
         )}
       </div>

apps/web/src/app/servicios/page.tsx

@@ -3,6 +3,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import Link from "next/link";
 import { AppShell } from "@/components/AppShell";
+import { ContextReports } from "@/components/ContextReports";
 import { useCan } from "@/lib/abilities";
 import {
   EXPIRY_WINDOW_DAYS,
@@ -169,6 +170,13 @@ function ServiciosBrowser() {
         <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
           <h1 className="page-title" style={{ margin: 0 }}>Propiedades</h1>
           <span style={{ flex: 1 }} />
+          <ContextReports
+            entries={[
+              { slug: "faltantes", label: "Faltantes agua", params: { serviceKind: "WATER" } },
+              { slug: "faltantes", label: "Faltantes luz", params: { serviceKind: "ELECTRICITY" } },
+              { slug: "faltantes", label: "Faltantes tel.", params: { serviceKind: "PHONE" } },
+            ]}
+          />
           {canCreate && (
             <Link href="/servicios/nuevo" className="btn btn-primary">+ Nueva propiedad</Link>
           )}

apps/web/src/app/usuarios/page.tsx

@@ -6,6 +6,7 @@ import { useAuth, useCan } from "@/lib/abilities";
 import { ROLE_LABEL, ROLES_DESC } from "@/lib/labels";
 import {
   createUser,
+  deleteUser,
   listUsers,
   resetUserPassword,
   updateUser,
@@ -133,6 +134,22 @@ function UsuariosAdmin() {
     }
   }
 
+  async function submitDelete(u: UserRow) {
+    if (!window.confirm(`¿Eliminar al usuario "${u.name}"? Esta acción no se puede deshacer.`)) {
+      return;
+    }
+    setError(null);
+    setNotice(null);
+    try {
+      await deleteUser(u.id);
+      if (editingId === u.id) startCreate();
+      setNotice("Usuario eliminado.");
+      refresh();
+    } catch (e) {
+      setError((e as Error)?.message ?? "No se pudo eliminar el usuario.");
+    }
+  }
+
   return (
     <>
       <div className="page-head">
@@ -312,6 +329,19 @@ function UsuariosAdmin() {
                           >
                             Contraseña
                           </button>
+                          <button
+                            className="btn btn-ghost btn-danger"
+                            type="button"
+                            disabled={u.id === me?.id}
+                            title={
+                              u.id === me?.id
+                                ? "No puede eliminar su propia cuenta"
+                                : "Eliminar usuario"
+                            }
+                            onClick={() => submitDelete(u)}
+                          >
+                            Eliminar
+                          </button>
                         </div>
                       )}
                     </td>

apps/web/src/app/version/route.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from "next/server";
+import { readBuildInfoFromEnv } from "@/lib/build-info";
+
+// Read per request, never prerendered — the whole point is to report what THIS
+// running container is, and a baked answer would defeat that.
+export const dynamic = "force-dynamic";
+
+/**
+ * The web tier's counterpart to the API's GET /version.
+ *
+ * Without this, the only way to see what the web container is running was to
+ * scrape window.__APP_BUILD__ out of the HTML. The deploy workflow compares the
+ * two tiers' gitSha to catch a half-applied release, so it needs a stable,
+ * parseable answer from both sides.
+ */
+export function GET() {
+  return NextResponse.json({ service: "web", ...readBuildInfoFromEnv() });
+}

apps/web/src/components/AppShell.tsx

@@ -1,11 +1,20 @@
 "use client";
 
-import { useEffect, useState, type ReactNode } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 import { usePathname, useRouter } from "next/navigation";
 import Link from "next/link";
-import { logout, me } from "@/lib/api";
+import { getApiVersion, logout, me, updateUiScale, type ServiceVersion } from "@/lib/api";
+import { webBuildInfo } from "@/lib/build-info";
 import { AuthContext, can } from "@/lib/abilities";
 import { ROLE_LABEL } from "@/lib/labels";
+import {
+  DEFAULT_UI_SCALE,
+  applyUiScale,
+  normalizeUiScale,
+  readUiScale,
+  saveUiScale,
+} from "@/lib/ui-scale";
+import { FontScaleControl } from "./FontScaleControl";
 import type { AuthUser, Ability } from "@/lib/types";
 
 /**
@@ -14,32 +23,264 @@ import type { AuthUser, Ability } from "@/lib/types";
  * content. Provides the AuthContext so any page can read the user's
  * abilities. Used by every authenticated page.
  */
-const NAV: { href: string; label: string; ability?: Ability }[] = [
-  { href: "/clientes", label: "Clientes" },
-  { href: "/servicios", label: "Propiedades" },
-  { href: "/polizas", label: "Pólizas" },
+
+type NavLink = {
+  href: string;
+  label: string;
+  ability?: Ability;
+  exact?: boolean;
+  /** Extra path prefixes that belong to this entry (e.g. a second route into
+   *  the same screen), so they highlight it instead of nothing. */
+  aliases?: string[];
+};
+type NavEntry =
+  | ({ kind: "link" } & NavLink)
+  | { kind: "group"; label: string; items: NavLink[] };
+
+/**
+ * Top nav. Daily screens stay one click away; the movement screens and the
+ * admin screens are grouped behind menus so the bar doesn't saturate as the
+ * app grows. A group disappears entirely when the user can't see any of its
+ * items (gating here is cosmetic — the API enforces every write).
+ */
+const NAV: NavEntry[] = [
+  { kind: "link", href: "/inicio", label: "Inicio", exact: true },
+  { kind: "link", href: "/clientes", label: "Clientes" },
+  { kind: "link", href: "/polizas", label: "Pólizas" },
+  { kind: "link", href: "/servicios", label: "Propiedades" },
+  {
+    kind: "group",
+    label: "Cobranza",
+    items: [
+      // Daily data-entry screen (the legacy "Editor"). Hidden from VIEWER, who
+      // can't capture anyway — the page itself also refuses. Both capture modes
+      // live behind this one entry: keying receipts by hand, and scanning a
+      // stack of bills for OCR (the `/recibos` route opens the same screen on
+      // its automatic tab).
+      {
+        href: "/estado-cuenta/lote",
+        label: "Captura",
+        ability: "ledger:create",
+        aliases: ["/recibos"],
+      },
       { href: "/estado-cuenta", label: "Estado de cuenta" },
       { href: "/banco", label: "Chequera" },
+    ],
+  },
+  { kind: "link", href: "/reportes", label: "Reportes" },
+  {
+    kind: "group",
+    label: "Admin",
+    items: [
       { href: "/catalogos", label: "Catálogos", ability: "lookup:manage" },
+      {
+        href: "/banco/cuentas",
+        label: "Cuentas de chequera",
+        ability: "bank:manage-accounts",
+      },
       { href: "/usuarios", label: "Usuarios", ability: "user:manage" },
       { href: "/operaciones", label: "Operaciones", ability: "db:manage" },
+    ],
+  },
 ];
 
+/** Every nav destination, flattened out of the groups. */
+const NAV_LINKS: NavLink[] = NAV.flatMap((entry) =>
+  entry.kind === "link" ? [entry] : entry.items,
+);
+
+/** The nav the given user may see, with empty groups dropped. */
+function visibleNav(user: AuthUser | null): NavEntry[] {
+  const allowed = (item: NavLink) => !item.ability || can(user, item.ability);
+  const out: NavEntry[] = [];
+  for (const entry of NAV) {
+    if (entry.kind === "link") {
+      if (allowed(entry)) out.push(entry);
+      continue;
+    }
+    const items = entry.items.filter(allowed);
+    if (items.length > 0) out.push({ ...entry, items });
+  }
+  return out;
+}
+
+/**
+ * Which nav entry is highlighted for a path. Longest matching href wins, so a
+ * nested route (`/estado-cuenta/lote`) highlights its own entry instead of also
+ * lighting up its parent (`/estado-cuenta`) — while `/estado-cuenta/<id>`, which
+ * has no entry of its own, still correctly highlights the parent.
+ */
+function activeHref(pathname: string | null): string | null {
+  if (!pathname) return null;
+  let best: string | null = null;
+  for (const item of NAV_LINKS) {
+    const under = (href: string) =>
+      pathname === href || pathname.startsWith(`${href}/`);
+    const match = item.exact
+      ? pathname === item.href
+      : under(item.href) || (item.aliases?.some(under) ?? false);
+    if (match && (best === null || item.href.length > best.length)) {
+      best = item.href;
+    }
+  }
+  return best;
+}
+
+/**
+ * One collapsible group in the desktop bar. Opens on click, closes on outside
+ * click, Escape, or navigation. The trigger stays highlighted while any of its
+ * children is the current page.
+ */
+function NavMenu({
+  label,
+  items,
+  current,
+  pathname,
+}: {
+  label: string;
+  items: NavLink[];
+  current: string | null;
+  pathname: string | null;
+}) {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+  const holdsCurrent = items.some((item) => item.href === current);
+
+  useEffect(() => {
+    setOpen(false);
+  }, [pathname]);
+
+  useEffect(() => {
+    if (!open) return;
+    function onPointerDown(event: MouseEvent) {
+      if (ref.current && !ref.current.contains(event.target as Node)) {
+        setOpen(false);
+      }
+    }
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") setOpen(false);
+    }
+    document.addEventListener("mousedown", onPointerDown);
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      document.removeEventListener("mousedown", onPointerDown);
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [open]);
+
+  return (
+    <div className="appbar-menu" ref={ref}>
+      <button
+        type="button"
+        className={`appbar-link appbar-menu-trigger${holdsCurrent ? " active" : ""}`}
+        aria-expanded={open}
+        aria-haspopup="true"
+        onClick={() => setOpen((v) => !v)}
+      >
+        {label}
+        <span className="appbar-caret" aria-hidden="true" />
+      </button>
+      {open && (
+        <div className="appbar-dropdown" role="menu">
+          {items.map((item) => (
+            <Link
+              key={item.href}
+              href={item.href}
+              role="menuitem"
+              className={`appbar-dropdown-link${current === item.href ? " active" : ""}`}
+              aria-current={current === item.href ? "page" : undefined}
+              onClick={() => setOpen(false)}
+            >
+              {item.label}
+            </Link>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * What is deployed, from both halves. build.yml builds api + web in one matrix
+ * run, so their versions cannot drift at build time — but they can at DEPLOY
+ * time, if a stack is applied with only one image's tag moved. Showing both and
+ * flagging a mismatch is the cheap check that catches a half-applied release.
+ */
+function BuildFooter() {
+  const web = webBuildInfo();
+  const [api, setApi] = useState<ServiceVersion | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    getApiVersion()
+      .then((v) => {
+        if (alive) setApi(v);
+      })
+      .catch(() => {
+        // The shell already redirects to /login when the API is unreachable;
+        // a missing version line is not worth a second error surface.
+      });
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  // Compare the COMMIT, not the version string. On a branch build both tiers
+  // report APP_VERSION "master", so comparing versions cannot see drift — which
+  // is exactly how a stale web image once sat next to a current API with this
+  // footer showing nothing wrong. The sha is the only field that actually
+  // differs between two builds of the same branch.
+  const mismatch = api !== null && api.gitSha !== web.gitSha;
+
+  return (
+    <footer className="shell-footer">
+      <span>Jorge Cuadros &amp; Asociados</span>
+      {/* The FULL 40-char commit, not an abbreviation: this line exists to be
+          pasted into `git show` or compared against a registry tag, and a
+          7-char prefix makes both a manual step. It is what GIT_SHA already
+          carries — build.yml bakes in `github.sha` whole. */}
+      <span
+        className="shell-footer-build"
+        title={`web ${web.version} (${web.gitSha}) — ${web.buildDate}`}
+      >
+        v{web.version} · {web.gitSha}
+        {mismatch && api ? ` · API ${api.gitSha}` : ""}
+      </span>
+      {mismatch && (
+        <span className="shell-footer-warn" role="status">
+          versiones desincronizadas
+        </span>
+      )}
+    </footer>
+  );
+}
+
 export function AppShell({ children }: { children: ReactNode }) {
   const router = useRouter();
   const pathname = usePathname();
   const [user, setUser] = useState<AuthUser | null>(null);
   const [checking, setChecking] = useState(true);
   const [loggingOut, setLoggingOut] = useState(false);
+  const [drawerOpen, setDrawerOpen] = useState(false);
+  const [uiScale, setUiScale] = useState(DEFAULT_UI_SCALE);
+  const current = activeHref(pathname);
+  const nav = visibleNav(user);
 
   useEffect(() => {
     let alive = true;
     me()
       .then((u) => {
-        if (alive) {
+        if (!alive) return;
         setUser(u);
         setChecking(false);
-        }
+        // The account wins over the localStorage copy the pre-hydration script
+        // painted with: that copy is this browser's, while the account follows
+        // the person between machines. Re-save so the next cold paint here is
+        // already correct.
+        const accountScale = normalizeUiScale(u.uiScale ?? DEFAULT_UI_SCALE);
+        setUiScale(accountScale);
+        applyUiScale(accountScale);
+        saveUiScale(accountScale);
       })
       .catch(() => {
         router.replace("/login");
@@ -49,6 +290,39 @@ export function AppShell({ children }: { children: ReactNode }) {
     };
   }, [router]);
 
+  // Before /auth/me answers, show whatever the pre-hydration script applied so
+  // the control isn't briefly out of step with the page.
+  useEffect(() => {
+    setUiScale(readUiScale());
+  }, []);
+
+  function changeUiScale(next: number) {
+    setUiScale(next);
+    applyUiScale(next);
+    saveUiScale(next);
+    setUser((prev) => (prev ? { ...prev, uiScale: next } : prev));
+    // Fire and forget: the change is already applied and cached locally, so a
+    // failed write only means it won't follow the user to another machine.
+    updateUiScale(next).catch(() => {
+      /* ignore */
+    });
+  }
+
+  // Navigating away closes the mobile drawer — the route change is the only
+  // "done" signal we get from a <Link>.
+  useEffect(() => {
+    setDrawerOpen(false);
+  }, [pathname]);
+
+  useEffect(() => {
+    if (!drawerOpen) return;
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") setDrawerOpen(false);
+    }
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [drawerOpen]);
+
   async function handleLogout() {
     setLoggingOut(true);
     try {
@@ -78,34 +352,42 @@ export function AppShell({ children }: { children: ReactNode }) {
     <AuthContext.Provider value={user}>
       <header className="appbar">
         <div className="appbar-inner">
-          <Link href="/clientes" className="brand">
-            <span className="brand-mark" aria-hidden>
-              JC
-            </span>
+          <Link href="/inicio" className="brand">
+            <img
+              src="/images/company_logo.png"
+              alt=""
+              className="brand-mark"
+            />
             <span className="brand-text">
               <span className="brand-name">Jorge Cuadros</span>
               <span className="brand-sub">& Asociados</span>
             </span>
           </Link>
           <nav className="appbar-nav" aria-label="Principal">
-            {NAV.filter((item) => !item.ability || can(user, item.ability)).map(
-              (item) => {
-                const active = pathname?.startsWith(item.href) ?? false;
-                return (
+            {nav.map((entry) =>
+              entry.kind === "link" ? (
                 <Link
-                    key={item.href}
-                    href={item.href}
-                    className={`appbar-link${active ? " active" : ""}`}
-                    aria-current={active ? "page" : undefined}
+                  key={entry.href}
+                  href={entry.href}
+                  className={`appbar-link${current === entry.href ? " active" : ""}`}
+                  aria-current={current === entry.href ? "page" : undefined}
                 >
-                    {item.label}
+                  {entry.label}
                 </Link>
-                );
-              },
+              ) : (
+                <NavMenu
+                  key={entry.label}
+                  label={entry.label}
+                  items={entry.items}
+                  current={current}
+                  pathname={pathname}
+                />
+              ),
             )}
           </nav>
           <span className="appbar-spacer" />
           <div className="appbar-user">
+            <FontScaleControl value={uiScale} onChange={changeUiScale} />
             {user && (
               <span className="appbar-user-name">
                 {user.name}
@@ -121,9 +403,59 @@ export function AppShell({ children }: { children: ReactNode }) {
               {loggingOut ? "Saliendo…" : "Cerrar sesión"}
             </button>
           </div>
+          <button
+            type="button"
+            className="appbar-burger"
+            aria-label={drawerOpen ? "Cerrar menú" : "Abrir menú"}
+            aria-expanded={drawerOpen}
+            onClick={() => setDrawerOpen((v) => !v)}
+          >
+            <span className={`burger-icon${drawerOpen ? " open" : ""}`} aria-hidden="true" />
+          </button>
         </div>
+        {drawerOpen && (
+          <nav className="appbar-drawer" aria-label="Principal (móvil)">
+            {nav.map((entry) =>
+              entry.kind === "link" ? (
+                <Link
+                  key={entry.href}
+                  href={entry.href}
+                  className={`appbar-drawer-link${current === entry.href ? " active" : ""}`}
+                  aria-current={current === entry.href ? "page" : undefined}
+                >
+                  {entry.label}
+                </Link>
+              ) : (
+                <div key={entry.label} className="appbar-drawer-group">
+                  <span className="appbar-drawer-heading">{entry.label}</span>
+                  {entry.items.map((item) => (
+                    <Link
+                      key={item.href}
+                      href={item.href}
+                      className={`appbar-drawer-link${current === item.href ? " active" : ""}`}
+                      aria-current={current === item.href ? "page" : undefined}
+                    >
+                      {item.label}
+                    </Link>
+                  ))}
+                </div>
+              ),
+            )}
+            <FontScaleControl
+              value={uiScale}
+              onChange={changeUiScale}
+              variant="inline"
+            />
+            {user && (
+              <div className="appbar-drawer-user">
+                {user.name} · {ROLE_LABEL[user.role]}
+              </div>
+            )}
+          </nav>
+        )}
       </header>
       <main className="shell-main">{children}</main>
+      <BuildFooter />
     </AuthContext.Provider>
   );
 }

apps/web/src/components/Captura.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { ManualCheckCapture } from "@/components/ManualCheckCapture";
+import { StatementIntake } from "@/components/StatementIntake";
+import { useCan } from "@/lib/abilities";
+
+/**
+ * The daily capture screen (the legacy "Editor"), with two ways in:
+ *
+ * - **manual** — key each customer's receipt against one check by hand.
+ * - **auto** — scan the stack of paper bills and let OCR propose customer and
+ *   amount for every page, which a human still confirms.
+ *
+ * Both end in the same place: charges on the customer's ledger, posted against
+ * one check. They are modes of one screen rather than two menu entries because
+ * it is one job — staff pick the mode by what's on the desk that morning, a
+ * stack of bills or a keyboard.
+ *
+ * `/estado-cuenta/lote` opens on manual, `/recibos` opens on auto; both render
+ * this component, so an old bookmark still lands on the right tab.
+ */
+
+export type CaptureMode = "manual" | "auto";
+
+const MODE_HINT: Record<CaptureMode, string> = {
+  manual:
+    "Captura los recibos de varios clientes contra un mismo cheque y concilia el total antes de guardar.",
+  auto: "Escanea los recibos del mes y el sistema propone cliente e importe para cada página. Nada se registra sin tu confirmación.",
+};
+
+export function Captura({ initialMode = "manual" }: { initialMode?: CaptureMode }) {
+  const canCapture = useCan("ledger:create");
+  const canIngest = useCan("statement:ingest");
+
+  // Gating is cosmetic (the API enforces every write), but a user who only has
+  // one of the two abilities should land on the mode they can actually use.
+  const modes: { key: CaptureMode; label: string }[] = [
+    ...(canCapture ? [{ key: "manual" as const, label: "Captura manual" }] : []),
+    ...(canIngest
+      ? [{ key: "auto" as const, label: "Captura automática (OCR)" }]
+      : []),
+  ];
+
+  const [mode, setMode] = useState<CaptureMode>(
+    modes.some((m) => m.key === initialMode) ? initialMode : (modes[0]?.key ?? "manual"),
+  );
+
+  if (modes.length === 0) {
+    return (
+      <div className="state-box state-error">
+        No tienes permiso para capturar movimientos.
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <div className="page-head">
+        <div>
+          <h1 className="page-title">Captura</h1>
+          <p className="eyebrow">{MODE_HINT[mode]}</p>
+        </div>
+        <Link href="/estado-cuenta" className="btn btn-outline">
+          Volver a estado de cuenta
+        </Link>
+      </div>
+
+      {modes.length > 1 && (
+        <div className="seg" role="tablist" style={{ marginBottom: 16 }}>
+          {modes.map((m) => (
+            <button
+              key={m.key}
+              type="button"
+              role="tab"
+              aria-selected={mode === m.key}
+              className={`seg-btn ${mode === m.key ? "active" : ""}`}
+              onClick={() => setMode(m.key)}
+            >
+              {m.label}
+            </button>
+          ))}
+        </div>
+      )}
+
+      {mode === "manual" ? <ManualCheckCapture /> : <StatementIntake />}
+    </>
+  );
+}

apps/web/src/components/ContextReports.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+import Link from "next/link";
+
+/**
+ * The context-report shortcut. One row of pill buttons that link to
+ * pre-filtered /reportes/[slug] pages. Used in the page header of
+ * domain pages (clientes, polizas, servicios, estado-cuenta, banco).
+ *
+ * `entries` accepts both static links (slug + label) and pre-filtered
+ * links (slug + params object). Pre-filtered ones build the query
+ * string automatically; the runner pre-fills the form.
+ */
+export interface ReportLink {
+  slug: string;
+  label: string;
+  /** Optional pre-fill for the report's filter form. */
+  params?: Record<string, string>;
+  /** When true, opens the report in a new tab (for "see the catalog"
+   *  style entries where the user is going to look around). */
+  external?: boolean;
+}
+
+export function ContextReports({
+  label = "Reportes",
+  entries,
+}: {
+  label?: string;
+  entries: ReportLink[];
+}) {
+  if (entries.length === 0) return null;
+  return (
+    <div className="context-reports" aria-label={label}>
+      <span className="context-reports-label">{label}</span>
+      {entries.map((e) => {
+        const qs = e.params
+          ? "?" +
+            new URLSearchParams(
+              Object.entries(e.params).filter(([, v]) => v != null && v !== ""),
+            ).toString()
+          : "";
+        const href = `/reportes/${e.slug}${qs}`;
+        return (
+          <Link
+            key={`${e.slug}-${JSON.stringify(e.params ?? {})}`}
+            href={href}
+            className="context-report-link"
+            target={e.external ? "_blank" : undefined}
+            rel={e.external ? "noopener" : undefined}
+          >
+            {e.label}
+          </Link>
+        );
+      })}
+    </div>
+  );
+}

apps/web/src/components/FontScaleControl.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { UI_SCALES } from "@/lib/ui-scale";
+
+/**
+ * Text-size picker. Controlled: AppShell owns the value and handles applying
+ * and persisting it, because the same setting is edited from two places (the
+ * appbar popover and the mobile drawer) and reconciled against the account on
+ * load.
+ *
+ * `variant="menu"` is the compact appbar popover; `variant="inline"` is the
+ * flat row used inside the mobile drawer, where a popover inside a popover
+ * would be awkward.
+ */
+export function FontScaleControl({
+  value,
+  onChange,
+  variant = "menu",
+}: {
+  value: number;
+  onChange: (scale: number) => void;
+  variant?: "menu" | "inline";
+}) {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    function onPointerDown(event: MouseEvent) {
+      if (ref.current && !ref.current.contains(event.target as Node)) {
+        setOpen(false);
+      }
+    }
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") setOpen(false);
+    }
+    document.addEventListener("mousedown", onPointerDown);
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      document.removeEventListener("mousedown", onPointerDown);
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [open]);
+
+  function choose(next: number) {
+    onChange(next);
+    setOpen(false);
+  }
+
+  const options = UI_SCALES.map((option) => ({
+    ...option,
+    selected: Math.abs(value - option.value) < 0.001,
+  }));
+
+  if (variant === "inline") {
+    return (
+      <div className="scale-inline" role="radiogroup" aria-label="Tamaño de texto">
+        <span className="appbar-drawer-heading">Tamaño de texto</span>
+        <div className="scale-inline-options">
+          {options.map((option) => (
+            <button
+              key={option.value}
+              type="button"
+              role="radio"
+              aria-checked={option.selected}
+              className={`scale-chip${option.selected ? " active" : ""}`}
+              style={{ fontSize: `${option.value}em` }}
+              onClick={() => choose(option.value)}
+            >
+              {option.short}
+              <span className="sr-only"> {option.label}</span>
+            </button>
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="appbar-menu" ref={ref}>
+      <button
+        type="button"
+        className="appbar-scale-trigger"
+        aria-expanded={open}
+        aria-haspopup="true"
+        aria-label="Tamaño de texto"
+        title="Tamaño de texto"
+        onClick={() => setOpen((v) => !v)}
+      >
+        <span aria-hidden="true">
+          A<span className="appbar-scale-big">A</span>
+        </span>
+      </button>
+      {open && (
+        <div className="appbar-dropdown appbar-dropdown-right" role="menu">
+          {options.map((option) => (
+            <button
+              key={option.value}
+              type="button"
+              role="menuitemradio"
+              aria-checked={option.selected}
+              className={`appbar-dropdown-link scale-option${option.selected ? " active" : ""}`}
+              onClick={() => choose(option.value)}
+            >
+              <span style={{ fontSize: `${option.value}em` }}>{option.short}</span>
+              <span className="scale-option-label">{option.label}</span>
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

apps/web/src/components/ManualCheckCapture.tsx

@@ -0,0 +1,526 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import Link from "next/link";
+import { CustomerPicker } from "@/components/CustomerPicker";
+import { createMovementBatch, getBillingFacets, getByCheck } from "@/lib/api";
+import { formatMoney, formatNumber, txTypeLabel } from "@/lib/labels";
+import type {
+  BatchCreateInput,
+  BillingFacets,
+  ByCheckResponse,
+  Currency,
+  LedgerCurrency,
+  TransactionDomain,
+} from "@/lib/types";
+
+/**
+ * Batch capture by check — the "Editor" screen from the legacy system
+ * (docs/RECEIPT_CAPTURE_SPEC.md §1.2), and the manual half of the Captura
+ * screen (see `Captura`).
+ *
+ * Staff key many customers' receipts against ONE physical check before cutting
+ * it, then check that the captured total matches the check's amount. That
+ * reconciliation is the whole point, so the running total is the most prominent
+ * thing on the page and an optional "importe del cheque" field turns it into a
+ * live difference.
+ *
+ * No batch entity is persisted: `checkNumber` is a plain column, and grouping
+ * by it answers every by-check question (see the "Reporte por cheque" report).
+ */
+
+const DOMAINS: { key: TransactionDomain; label: string }[] = [
+  { key: "UTILITY", label: "Servicios" },
+  { key: "INSURANCE", label: "Seguros" },
+  { key: "TRUST", label: "Fideicomiso" },
+];
+
+interface Line {
+  /** Local row key — lines have no server identity until the batch posts. */
+  key: number;
+  customerId: string;
+  customerName: string;
+  amount: string;
+  reference: string;
+  period: string;
+  outstanding: boolean;
+}
+
+function blankLine(key: number): Line {
+  return {
+    key,
+    customerId: "",
+    customerName: "",
+    amount: "",
+    reference: "",
+    period: "",
+    outstanding: false,
+  };
+}
+
+export function ManualCheckCapture() {
+  const [facets, setFacets] = useState<BillingFacets | null>(null);
+
+  // Check-level fields — shared by every line.
+  const [domain, setDomain] = useState<TransactionDomain>("UTILITY");
+  const [currency, setCurrency] = useState<LedgerCurrency>("MXN");
+  const [typeId, setTypeId] = useState("");
+  const [checkNumber, setCheckNumber] = useState("");
+  const [transactionDate, setTransactionDate] = useState(
+    new Date().toISOString().slice(0, 10),
+  );
+  /** The physical check's amount, for reconciliation only — never submitted. */
+  const [checkAmount, setCheckAmount] = useState("");
+
+  const [lines, setLines] = useState<Line[]>([blankLine(1), blankLine(2), blankLine(3)]);
+  const [nextKey, setNextKey] = useState(4);
+
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [posted, setPosted] = useState<ByCheckResponse | null>(null);
+
+  useEffect(() => {
+    getBillingFacets().then(setFacets).catch(() => setFacets(null));
+  }, []);
+
+  const filled = lines.filter(
+    (l) => l.customerId && l.amount.trim() !== "" && Number.isFinite(Number(l.amount)),
+  );
+
+  // Charges are captured as positive numbers and signed on submit, matching
+  // MovementForm — staff type what's on the bill, not a negative.
+  const total = useMemo(
+    () =>
+      filled
+        .filter((l) => !l.outstanding)
+        .reduce((sum, l) => sum + Math.abs(Number(l.amount)), 0),
+    [filled],
+  );
+  const outstandingTotal = useMemo(
+    () =>
+      filled
+        .filter((l) => l.outstanding)
+        .reduce((sum, l) => sum + Math.abs(Number(l.amount)), 0),
+    [filled],
+  );
+
+  const checkAmt = Number(checkAmount);
+  const hasCheckAmt = checkAmount.trim() !== "" && Number.isFinite(checkAmt);
+  const diff = hasCheckAmt ? checkAmt - total : 0;
+  const reconciled = hasCheckAmt && Math.abs(diff) < 0.005;
+
+  function update(key: number, patch: Partial<Line>) {
+    setLines((ls) => ls.map((l) => (l.key === key ? { ...l, ...patch } : l)));
+  }
+
+  function addLine() {
+    setLines((ls) => [...ls, blankLine(nextKey)]);
+    setNextKey((k) => k + 1);
+  }
+
+  function removeLine(key: number) {
+    setLines((ls) => (ls.length === 1 ? ls : ls.filter((l) => l.key !== key)));
+  }
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    if (!checkNumber.trim()) {
+      setError("Indica el número de cheque.");
+      return;
+    }
+    if (filled.length === 0) {
+      setError("Captura al menos una línea con cliente y monto.");
+      return;
+    }
+    const dupes = filled
+      .map((l) => l.customerId)
+      .filter((id, i, arr) => arr.indexOf(id) !== i);
+    if (dupes.length) {
+      const names = filled
+        .filter((l) => dupes.includes(l.customerId))
+        .map((l) => l.customerName);
+      if (
+        !window.confirm(
+          `Hay más de una línea para el mismo cliente (${[...new Set(names)].join(
+            ", ",
+          )}). ¿Continuar?`,
+        )
+      )
+        return;
+    }
+
+    const payload: BatchCreateInput = {
+      domain,
+      transactionDate,
+      checkNumber: checkNumber.trim(),
+      currency: currency as Currency,
+      typeId: typeId || undefined,
+      lines: filled.map((l) => ({
+        customerId: l.customerId,
+        // Every line of a check batch is a charge the office paid out.
+        amount: -Math.abs(Number(l.amount)),
+        reference: l.reference.trim() || undefined,
+        period: l.period.trim() || undefined,
+        outstanding: l.outstanding || undefined,
+      })),
+    };
+
+    setSaving(true);
+    setError(null);
+    try {
+      await createMovementBatch(payload);
+      // Re-read through the by-check view so the confirmation shows what's
+      // actually stored (including anything captured against this check
+      // earlier), not just what this request sent.
+      setPosted(await getByCheck(payload.checkNumber));
+    } catch (e2) {
+      setError((e2 as Error)?.message ?? "No se pudo guardar el lote.");
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  function reset() {
+    setPosted(null);
+    setLines([blankLine(nextKey), blankLine(nextKey + 1), blankLine(nextKey + 2)]);
+    setNextKey((k) => k + 3);
+    setCheckNumber("");
+    setCheckAmount("");
+  }
+
+  if (posted) {
+    return (
+      <>
+        <div className="page-head">
+          <div>
+            <h2 className="page-title">Lote capturado</h2>
+            <p className="eyebrow">
+              Cheque {posted.checkNumber} · {formatNumber(posted.count)}{" "}
+              {posted.count === 1 ? "movimiento" : "movimientos"}
+            </p>
+          </div>
+          <div style={{ display: "flex", gap: 10 }}>
+            <button type="button" className="btn btn-primary" onClick={reset}>
+              Capturar otro cheque
+            </button>
+            <Link href="/estado-cuenta" className="btn btn-outline">
+              Volver a estado de cuenta
+            </Link>
+          </div>
+        </div>
+
+        <div className="filtered-totals" style={{ marginBottom: 16 }}>
+          {posted.totals.map((t) => (
+            <div className="filtered-total" key={t.currency}>
+              <span className="filtered-total-cur">{t.currency}</span>
+              <span className="filtered-total-net">
+                Total del cheque <strong>{formatMoney(t.total, t.currency)}</strong>
+              </span>
+              <span>{formatNumber(t.count)} movimientos</span>
+            </div>
+          ))}
+          {posted.outstandingCount > 0 && (
+            <div className="filtered-total">
+              <span>
+                {formatNumber(posted.outstandingCount)} sin fondos (no suman al
+                total)
+              </span>
+            </div>
+          )}
+        </div>
+
+        <div className="tx-scroll">
+          <table className="tx-table">
+            <thead>
+              <tr>
+                <th>Cliente</th>
+                <th>Referencia</th>
+                <th>Periodo</th>
+                <th>Estado</th>
+                <th className="num">Monto</th>
+              </tr>
+            </thead>
+            <tbody>
+              {posted.items.map((i) => (
+                <tr key={i.id}>
+                  <td>
+                    <Link
+                      href={`/estado-cuenta/${i.customerId}`}
+                      className="inline-link"
+                    >
+                      {i.customerName}
+                    </Link>
+                  </td>
+                  <td>{i.reference || "—"}</td>
+                  <td>{i.period || "—"}</td>
+                  <td>{i.outstanding ? "Sin fondos" : "Pagado"}</td>
+                  <td className="num">
+                    <span className="tx-amount neg">
+                      {formatMoney(i.amount, i.currency)}
+                    </span>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+
+        <p className="muted" style={{ marginTop: 14 }}>
+          Para imprimir la conciliación, usa el reporte{" "}
+          <Link
+            href={`/reportes/cheque-count?checkNumber=${encodeURIComponent(
+              posted.checkNumber,
+            )}`}
+            className="inline-link"
+          >
+            Reporte por cheque
+          </Link>
+          .
+        </p>
+      </>
+    );
+  }
+
+  return (
+    <>
+      {error && <div className="state-box state-error">{error}</div>}
+
+      <form onSubmit={submit}>
+        <div className="card" style={{ padding: 20, marginBottom: 16 }}>
+          <h2 className="section-title" style={{ marginBottom: 14 }}>
+            Datos del cheque
+          </h2>
+          <div className="form-grid">
+            <label className="field">
+              <span className="field-label">Número de cheque *</span>
+              <input
+                className="input"
+                value={checkNumber}
+                onChange={(e) => setCheckNumber(e.target.value)}
+                required
+              />
+            </label>
+            <label className="field">
+              <span className="field-label">Fecha *</span>
+              <input
+                className="input"
+                type="date"
+                required
+                value={transactionDate}
+                onChange={(e) => setTransactionDate(e.target.value)}
+              />
+            </label>
+            <label className="field">
+              <span className="field-label">Línea de negocio *</span>
+              <select
+                className="select"
+                value={domain}
+                onChange={(e) => setDomain(e.target.value as TransactionDomain)}
+              >
+                {DOMAINS.map((d) => (
+                  <option key={d.key} value={d.key}>
+                    {d.label}
+                  </option>
+                ))}
+              </select>
+            </label>
+            <label className="field">
+              <span className="field-label">Moneda *</span>
+              <select
+                className="select"
+                value={currency}
+                onChange={(e) => setCurrency(e.target.value as LedgerCurrency)}
+              >
+                <option value="MXN">Pesos (MXN)</option>
+                <option value="USD">Dólares (USD)</option>
+              </select>
+            </label>
+            <label className="field">
+              <span className="field-label">Concepto</span>
+              <select
+                className="select"
+                value={typeId}
+                onChange={(e) => setTypeId(e.target.value)}
+              >
+                <option value="">(sin concepto)</option>
+                {facets?.types.map((t) => (
+                  <option key={t.id} value={t.id}>
+                    {txTypeLabel({ nameEn: t.name })}
+                  </option>
+                ))}
+              </select>
+            </label>
+            <label className="field">
+              <span className="field-label">Importe del cheque</span>
+              <input
+                className="input"
+                type="number"
+                step="0.01"
+                min="0"
+                value={checkAmount}
+                onChange={(e) => setCheckAmount(e.target.value)}
+                placeholder="Para conciliar"
+              />
+            </label>
+          </div>
+        </div>
+
+        <div className="card" style={{ padding: 20, marginBottom: 16 }}>
+          <div
+            style={{
+              display: "flex",
+              justifyContent: "space-between",
+              alignItems: "center",
+              marginBottom: 14,
+            }}
+          >
+            <h2 className="section-title" style={{ margin: 0 }}>
+              Recibos ({formatNumber(filled.length)})
+            </h2>
+            <button type="button" className="btn btn-outline" onClick={addLine}>
+              Agregar línea
+            </button>
+          </div>
+
+          <div className="tx-scroll">
+            <table className="tx-table">
+              <thead>
+                <tr>
+                  <th style={{ minWidth: 240 }}>Cliente *</th>
+                  <th style={{ minWidth: 120 }}>Referencia</th>
+                  <th style={{ minWidth: 100 }}>Periodo</th>
+                  <th style={{ minWidth: 110 }} className="num">
+                    Monto *
+                  </th>
+                  <th style={{ whiteSpace: "nowrap" }}>Sin fondos</th>
+                  <th style={{ width: 1 }} />
+                </tr>
+              </thead>
+              <tbody>
+                {lines.map((l) => (
+                  <tr key={l.key}>
+                    <td>
+                      <CustomerPicker
+                        value={l.customerId}
+                        valueName={l.customerId ? l.customerName : undefined}
+                        onPick={(id, name) =>
+                          update(l.key, { customerId: id, customerName: name })
+                        }
+                      />
+                    </td>
+                    <td>
+                      <input
+                        className="input"
+                        value={l.reference}
+                        onChange={(e) =>
+                          update(l.key, { reference: e.target.value })
+                        }
+                      />
+                    </td>
+                    <td>
+                      <input
+                        className="input"
+                        value={l.period}
+                        onChange={(e) => update(l.key, { period: e.target.value })}
+                        placeholder="2026-07"
+                      />
+                    </td>
+                    <td>
+                      <input
+                        className="input num"
+                        type="number"
+                        step="0.01"
+                        min="0"
+                        value={l.amount}
+                        onChange={(e) => update(l.key, { amount: e.target.value })}
+                        placeholder="0.00"
+                      />
+                    </td>
+                    <td style={{ textAlign: "center" }}>
+                      <input
+                        type="checkbox"
+                        checked={l.outstanding}
+                        onChange={(e) =>
+                          update(l.key, { outstanding: e.target.checked })
+                        }
+                        aria-label="Sin fondos"
+                      />
+                    </td>
+                    <td>
+                      <button
+                        type="button"
+                        className="btn btn-ghost"
+                        style={{ padding: "4px 10px", fontSize: 12 }}
+                        onClick={() => removeLine(l.key)}
+                        disabled={lines.length === 1}
+                      >
+                        Quitar
+                      </button>
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </div>
+
+        <div className="card" style={{ padding: 20, marginBottom: 16 }}>
+          <h2 className="section-title" style={{ marginBottom: 14 }}>
+            Conciliación
+          </h2>
+          <div className="filtered-totals">
+            <div className="filtered-total">
+              <span className="filtered-total-cur">{currency}</span>
+              <span className="filtered-total-net">
+                Capturado <strong>{formatMoney(String(-total), currency)}</strong>
+              </span>
+              <span>{formatNumber(filled.filter((l) => !l.outstanding).length)} recibos</span>
+            </div>
+            {outstandingTotal > 0 && (
+              <div className="filtered-total">
+                <span>
+                  Sin fondos{" "}
+                  <strong>{formatMoney(String(-outstandingTotal), currency)}</strong>{" "}
+                  (no suma al cheque)
+                </span>
+              </div>
+            )}
+            {hasCheckAmt && (
+              <div className="filtered-total">
+                <span className="filtered-total-net">
+                  {reconciled ? (
+                    <strong className="tx-amount pos">Cuadra con el cheque</strong>
+                  ) : (
+                    <>
+                      Diferencia{" "}
+                      <strong className="tx-amount neg">
+                        {formatMoney(String(diff), currency)}
+                      </strong>
+                    </>
+                  )}
+                </span>
+              </div>
+            )}
+          </div>
+        </div>
+
+        <div className="form-actions">
+          <button
+            type="submit"
+            className="btn btn-primary"
+            disabled={saving || filled.length === 0}
+          >
+            {saving
+              ? "Guardando…"
+              : `Capturar ${formatNumber(filled.length)} ${
+                  filled.length === 1 ? "recibo" : "recibos"
+                }`}
+          </button>
+          <Link href="/estado-cuenta" className="btn btn-outline">
+            Cancelar
+          </Link>
+        </div>
+      </form>
+    </>
+  );
+}

apps/web/src/components/MovementForm.tsx

@@ -62,9 +62,15 @@ export function MovementForm({
   const [reference, setReference] = useState("");
   const [checkNumber, setCheckNumber] = useState("");
   const [message, setMessage] = useState("");
+  const [outstanding, setOutstanding] = useState(false);
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
+  // "Sin fondos" is a per-service *charge* concept: the office recorded a
+  // utility bill it couldn't cover. It never applies to a credit (a payment
+  // that arrived is, by definition, funded) or to the insurance/trust lines.
+  const canBeOutstanding = domain === "UTILITY" && direction === "charge";
+
   async function submit(e: React.FormEvent) {
     e.preventDefault();
     if (!customerId) {
@@ -88,6 +94,9 @@ export function MovementForm({
       reference: s(reference),
       checkNumber: s(checkNumber),
       message: s(message),
+      // Guarded by canBeOutstanding so a stale checkbox can't ride along after
+      // the user switches the row to a credit or another business line.
+      outstanding: canBeOutstanding && outstanding ? true : undefined,
     };
     setSaving(true);
     setError(null);
@@ -225,6 +234,28 @@ export function MovementForm({
             onChange={(e) => setMessage(e.target.value)}
           />
         </label>
+
+        {canBeOutstanding && (
+          <label
+            className="field"
+            style={{ marginTop: 16, flexDirection: "row", alignItems: "center", gap: 10 }}
+          >
+            <input
+              type="checkbox"
+              checked={outstanding}
+              onChange={(e) => setOutstanding(e.target.checked)}
+            />
+            <span>
+              <span className="field-label" style={{ display: "block" }}>
+                Sin fondos (pendiente de pago)
+              </span>
+              <span className="muted" style={{ fontSize: 13 }}>
+                El cargo se registra pero no afecta el saldo del cliente hasta
+                que se resuelva con un cheque.
+              </span>
+            </span>
+          </label>
+        )}
       </div>
 
       <div className="form-actions">

apps/web/src/components/ReportRunner.tsx

@@ -0,0 +1,635 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import {
+  API_ORIGIN,
+  reportDownloadUrl,
+  runReport,
+} from "@/lib/api";
+import { CustomerPicker } from "@/components/CustomerPicker";
+import { formatMoney, formatNumber } from "@/lib/labels";
+import type {
+  ReportDef,
+  ReportParam,
+  ReportRunResult,
+} from "@/lib/types";
+
+/**
+ * The shared runner. Renders the filter form, fetches the result, and
+ * shows the table + output buttons. One component, every report — the
+ * per-report shape comes entirely from the def the API returns.
+ */
+export function ReportRunner({
+  def,
+  initialParams,
+}: {
+  def: ReportDef;
+  /** Pre-filled param values (e.g. when launched with a customerId from
+   *  a context button on a customer detail page). */
+  initialParams?: Record<string, string>;
+}) {
+  // The form state, keyed by param.key. Initialised from defaults +
+  // initialParams (initialParams wins for explicitly-set keys).
+  const [params, setParams] = useState<Record<string, string>>(() => {
+    const seed: Record<string, string> = {};
+    for (const p of def.params) {
+      if (p.kind === "select" || p.kind === "text" || p.kind === "number" || p.kind === "date") {
+        if (p.defaultValue != null) seed[p.key] = p.defaultValue;
+      }
+    }
+    if (initialParams) Object.assign(seed, initialParams);
+    return seed;
+  });
+
+  const [result, setResult] = useState<ReportRunResult | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const run = useCallback(
+    (p: Record<string, string>) => {
+      setLoading(true);
+      setError(null);
+      runReport(def.slug, p)
+        .then(setResult)
+        .catch((e) => {
+          setError(e?.message ?? "No se pudo correr el reporte.");
+          setResult(null);
+        })
+        .finally(() => setLoading(false));
+    },
+    [def.slug],
+  );
+
+  // Auto-run on mount so the runner opens with results, not blank.
+  useEffect(() => {
+    run(params);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  function updateParam(key: string, value: string) {
+    setParams((prev) => ({ ...prev, [key]: value }));
+  }
+
+  function applyFilters(e?: React.FormEvent) {
+    e?.preventDefault();
+    run(params);
+  }
+
+  return (
+    <div className="report-runner">
+      <form className="report-filters" onSubmit={applyFilters}>
+        {def.params.map((p) => (
+          <ParamField
+            key={p.key}
+            param={p}
+            value={params[p.key] ?? ""}
+            onChange={(v) => updateParam(p.key, v)}
+          />
+        ))}
+        <div className="report-filters-actions">
+          <button
+            type="submit"
+            className="btn btn-primary"
+            disabled={loading}
+          >
+            {loading ? "Corriendo…" : "Correr reporte"}
+          </button>
+        </div>
+      </form>
+
+      {error && <div className="report-error">{error}</div>}
+
+      {result && (
+        <ResultBlock def={def} result={result} params={params} loading={loading} />
+      )}
+    </div>
+  );
+}
+
+/* ---------------------------------------------------------- one param field */
+
+function ParamField({
+  param,
+  value,
+  onChange,
+}: {
+  param: ReportParam;
+  value: string;
+  onChange: (v: string) => void;
+}) {
+  const label = (
+    <span className="filter-label">
+      {param.label}
+      {param.kind === "customer-picker" && !value && (
+        <span className="muted" style={{ marginLeft: 6, fontWeight: 400 }}>
+          (requerido)
+        </span>
+      )}
+    </span>
+  );
+
+  if (param.kind === "select") {
+    return (
+      <label className="filter-field">
+        {label}
+        <select
+          className="input select"
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+        >
+          {!param.defaultValue && <option value="">—</option>}
+          {param.options.map((o) => (
+            <option key={o.value} value={o.value}>
+              {o.label}
+            </option>
+          ))}
+        </select>
+      </label>
+    );
+  }
+  if (param.kind === "date") {
+    return (
+      <label className="filter-field">
+        {label}
+        <input
+          type="date"
+          className="input"
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+        />
+      </label>
+    );
+  }
+  if (param.kind === "number") {
+    return (
+      <label className="filter-field">
+        {label}
+        <input
+          type="number"
+          className="input"
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+          placeholder={param.defaultValue}
+        />
+      </label>
+    );
+  }
+  if (param.kind === "customer-picker") {
+    return (
+      <div className="filter-field">
+        {label}
+        <CustomerPicker
+          value={value}
+          onPick={(id) => onChange(id)}
+        />
+      </div>
+    );
+  }
+  return (
+    <label className="filter-field">
+      {label}
+      <input
+        type="text"
+        className="input"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={param.placeholder ?? ""}
+      />
+    </label>
+  );
+}
+
+/* ---------------------------------------------------------- results block */
+
+function ResultBlock({
+  def,
+  result,
+  params,
+  loading,
+}: {
+  def: ReportDef;
+  result: ReportRunResult;
+  params: Record<string, string>;
+  loading: boolean;
+}) {
+  return (
+    <div className="report-result">
+      <div className="report-result-head">
+        <div className="report-result-meta">
+          {result.subtitle && <p className="muted">{result.subtitle}</p>}
+          <p className="muted small">
+            {formatNumber(result.rows.length)} fila
+            {result.rows.length === 1 ? "" : "s"}
+            {result.totals && (
+              <>
+                {" "}·{" "}
+                {Object.entries(result.totals)
+                  .map(([k, v]) => `${k}: ${v}`)
+                  .join(" · ")}
+              </>
+            )}
+          </p>
+        </div>
+        <div className="report-output-buttons">
+          <a
+            className="btn btn-outline btn-sm"
+            href={reportDownloadUrl(def.slug, "print", params)}
+            target="_blank"
+            rel="noopener"
+          >
+            Imprimir
+          </a>
+          <a
+            className="btn btn-outline btn-sm"
+            href={reportDownloadUrl(def.slug, "csv", params)}
+            download
+          >
+            CSV
+          </a>
+          <a
+            className="btn btn-outline btn-sm"
+            href={reportDownloadUrl(def.slug, "xlsx", params)}
+            download
+          >
+            Excel
+          </a>
+          <a
+            className="btn btn-outline btn-sm"
+            href={reportDownloadUrl(def.slug, "pdf", params)}
+            download
+          >
+            PDF
+          </a>
+        </div>
+      </div>
+
+      {loading && <div className="report-loading">Actualizando…</div>}
+
+      {def.format === "statement" ? (
+        <StatementLayout result={result} />
+      ) : def.format === "letter" ? (
+        <LetterLayout result={result} />
+      ) : (
+        <TabularLayout result={result} />
+      )}
+    </div>
+  );
+}
+
+/* ---------------------------------------------------------- tabular layout */
+
+function TabularLayout({ result }: { result: ReportRunResult }) {
+  if (result.rows.length === 0) {
+    return (
+      <div className="empty-inline">
+        No se encontraron filas con los filtros actuales.
+      </div>
+    );
+  }
+  return (
+    <div className="report-table-wrap">
+      <table className="report-table">
+        <thead>
+          <tr>
+            {result.columns.map((c) => (
+              <th
+                key={c.key}
+                style={{
+                  textAlign: c.align ?? "left",
+                  width: c.width ? `${c.width * 6}px` : undefined,
+                }}
+              >
+                {c.label}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {result.rows.map((r, i) => (
+            <tr key={i}>
+              {result.columns.map((c) => {
+                const v = r[c.key];
+                return (
+                  <td
+                    key={c.key}
+                    style={{
+                      textAlign: c.align ?? "left",
+                      fontVariantNumeric:
+                        c.type === "money" || c.type === "number"
+                          ? "tabular-nums"
+                          : undefined,
+                    }}
+                  >
+                    {formatCell(v, c.type)}
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+        {result.totals && (
+          <tfoot>
+            <tr>
+              <td
+                colSpan={result.columns.length}
+                className="report-totals"
+              >
+                {Object.entries(result.totals)
+                  .map(([k, v]) => `${k}: ${v}`)
+                  .join("   ·   ")}
+              </td>
+            </tr>
+          </tfoot>
+        )}
+      </table>
+    </div>
+  );
+}
+
+function formatCell(v: unknown, type: string): string {
+  if (v === null || v === undefined || v === "") return "—";
+  if (type === "money") {
+    const n = Number(v);
+    return Number.isFinite(n)
+      ? new Intl.NumberFormat("es-MX", {
+          minimumFractionDigits: 2,
+          maximumFractionDigits: 2,
+        }).format(n)
+      : String(v);
+  }
+  if (type === "number") {
+    const n = Number(v);
+    return Number.isFinite(n) ? formatNumber(n) : String(v);
+  }
+  return String(v);
+}
+
+/* --------------------------------------------------------- statement layout */
+
+function StatementLayout({ result }: { result: ReportRunResult }) {
+  // The edo-cuenta-datos report synthesises a list with __kind
+  // discriminators (header, summary, movements-header, plain movement).
+  // Group by kind and render each block inline.
+  const header = result.rows.find((r) => r.__kind === "header") as
+    | Record<string, unknown>
+    | undefined;
+  const summaries = result.rows.filter((r) => r.__kind === "summary");
+  const movements = result.rows.filter(
+    (r) => r.__kind !== "header" && r.__kind !== "summary" && r.__kind !== "movements-header",
+  );
+
+  if (!header) {
+    return (
+      <div className="empty-inline">
+        Selecciona un cliente y corre el reporte para ver el estado de cuenta.
+      </div>
+    );
+  }
+
+  return (
+    <div className="statement">
+      <header className="statement-head">
+        <h2 className="statement-name">{String(header.name ?? "—")}</h2>
+        {Boolean(header.address) && (
+          <p className="muted">{String(header.address)}</p>
+        )}
+        {Boolean(header.city) && <p className="muted">{String(header.city)}</p>}
+        {Boolean(header.phone || header.email) && (
+          <p className="muted small">
+            {String(header.phone ?? "")}
+            {header.phone && header.email ? " · " : ""}
+            {String(header.email ?? "")}
+          </p>
+        )}
+      </header>
+
+      {summaries.length > 0 && (
+        <section className="statement-summary">
+          <h3 className="statement-section-title">Resumen por moneda</h3>
+          <table className="report-table">
+            <thead>
+              <tr>
+                <th>Moneda</th>
+                <th style={{ textAlign: "right" }}>Cargos</th>
+                <th style={{ textAlign: "right" }}>Abonos</th>
+                <th style={{ textAlign: "right" }}>Saldo</th>
+                <th style={{ textAlign: "right" }}>Movs.</th>
+              </tr>
+            </thead>
+            <tbody>
+              {summaries.map((s, i) => (
+                <tr key={i}>
+                  <td>{String(s.currency)}</td>
+                  <td style={{ textAlign: "right", fontVariantNumeric: "tabular-nums" }}>
+                    {formatCell(s.charges, "money")}
+                  </td>
+                  <td style={{ textAlign: "right", fontVariantNumeric: "tabular-nums" }}>
+                    {formatCell(s.credits, "money")}
+                  </td>
+                  <td style={{ textAlign: "right", fontVariantNumeric: "tabular-nums" }}>
+                    {formatCell(s.balance, "money")}
+                  </td>
+                  <td style={{ textAlign: "right" }}>{formatCell(s.count, "number")}</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </section>
+      )}
+
+      {movements.length > 0 && (
+        <section className="statement-movements">
+          <h3 className="statement-section-title">Movimientos</h3>
+          <div className="report-table-wrap">
+            <table className="report-table">
+              <thead>
+                <tr>
+                  <th>Fecha</th>
+                  <th>Concepto</th>
+                  <th>Referencia</th>
+                  <th style={{ textAlign: "right" }}>Cargo / Abono</th>
+                  <th style={{ textAlign: "right" }}>Saldo</th>
+                </tr>
+              </thead>
+              <tbody>
+                {movements.map((m, i) => (
+                  <tr key={i}>
+                    <td>{String(m.date ?? "")}</td>
+                    <td>{String(m.concept ?? "")}</td>
+                    <td>{String(m.reference ?? "")}</td>
+                    <td style={{ textAlign: "right", fontVariantNumeric: "tabular-nums" }}>
+                      {formatCell(m.amount, "money")}
+                    </td>
+                    <td style={{ textAlign: "right", fontVariantNumeric: "tabular-nums" }}>
+                      {formatCell(m.balanceAfter, "money")}
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </section>
+      )}
+    </div>
+  );
+}
+
+/* ----------------------------------------------------------- letter layout */
+
+const GENERATION_LABEL: Record<string, string> = {
+  "1": "1er aviso",
+  "2": "2o aviso",
+  "3": "3er aviso",
+};
+
+interface LetterVehicle {
+  make?: string | null;
+  model?: string | null;
+  modelYear?: string | number | null;
+  bodyType?: string | null;
+  engineNumber?: string | null;
+  licensePlate?: string | null;
+}
+
+/**
+ * One card per policy due for renewal — the parameterized replacement for
+ * the ~40 cloned "AVISO DE RENOVACION" Access reports (see
+ * docs/RENEWAL_NOTICES.md). Coverage figures (CSL limit, medical coverage,
+ * etc.) come from data (`aviso-renovacion`'s ReportDef reads
+ * `Policy.coveragesJson`) instead of the legacy's hand-typed label text, so
+ * one layout renders every carrier/coverage combination.
+ */
+function LetterLayout({ result }: { result: ReportRunResult }) {
+  const letters = result.rows.filter((r) => r.__kind === "letter");
+
+  if (letters.length === 0) {
+    return (
+      <div className="empty-inline">
+        No hay pólizas por vencer con los filtros actuales.
+      </div>
+    );
+  }
+
+  return (
+    <div className="renewal-letters">
+      {letters.map((r, i) => {
+        const vehicle = r.vehicle as LetterVehicle | null;
+        const generation = String(r.generation ?? "1");
+        return (
+          <article className="renewal-letter" key={String(r.policyId ?? i)}>
+            <header className="renewal-letter-head">
+              <div>
+                <h2 className="renewal-letter-title">Aviso de renovación</h2>
+                <p className="muted small">
+                  {GENERATION_LABEL[generation] ?? `Aviso ${generation}`}
+                </p>
+              </div>
+              <div className="renewal-letter-status">
+                {r.sentAt ? (
+                  <span className="badge badge-positive">
+                    <span className="dot" />
+                    Enviado {String(r.sentAt)}
+                  </span>
+                ) : (
+                  <span className="badge badge-neutral">
+                    <span className="dot" />
+                    Pendiente
+                  </span>
+                )}
+              </div>
+            </header>
+
+            <div className="renewal-letter-grid">
+              <div>
+                <p className="muted small">Cliente</p>
+                <p className="renewal-letter-value">
+                  {String(r.customerName ?? "—")}
+                </p>
+              </div>
+              <div>
+                <p className="muted small">Póliza</p>
+                <p className="renewal-letter-value">
+                  {String(r.policyNumber ?? "—")}
+                </p>
+              </div>
+              <div>
+                <p className="muted small">Aseguradora</p>
+                <p className="renewal-letter-value">
+                  {String(r.provider ?? "—")}
+                </p>
+              </div>
+              <div>
+                <p className="muted small">Vence</p>
+                <p className="renewal-letter-value">
+                  {String(r.policyTo ?? "—")}
+                </p>
+              </div>
+            </div>
+
+            {vehicle && (
+              <div className="renewal-letter-vehicle">
+                <p className="muted small">Vehículo asegurado</p>
+                <p className="renewal-letter-value">
+                  {[vehicle.modelYear, vehicle.make, vehicle.model]
+                    .filter(Boolean)
+                    .join(" ")}
+                  {vehicle.bodyType ? ` · ${vehicle.bodyType}` : ""}
+                </p>
+                <p className="muted small">
+                  {[
+                    vehicle.engineNumber && `Motor: ${vehicle.engineNumber}`,
+                    vehicle.licensePlate && `Placa: ${vehicle.licensePlate}`,
+                  ]
+                    .filter(Boolean)
+                    .join(" · ")}
+                </p>
+              </div>
+            )}
+
+            <div className="renewal-letter-coverage">
+              <CoverageItem label="Cobertura (días)" value={r.coverageDays} />
+              <CoverageItem label="CSL" value={r.cslLimit} money />
+              <CoverageItem label="Gastos médicos" value={r.medicalCoverage} money />
+              <CoverageItem label="Daños a propiedad" value={r.propertyDamage} money />
+              <CoverageItem label="Responsabilidad por persona" value={r.perPersonLiability} money />
+            </div>
+
+            <div className="renewal-letter-premium">
+              {Boolean(r.netPremium) && (
+                <span>Prima neta: {formatCell(r.netPremium, "money")}</span>
+              )}
+              {Boolean(r.total) && (
+                <span className="renewal-letter-total">
+                  Total: {formatCell(r.total, "money")} {String(r.currency ?? "")}
+                </span>
+              )}
+            </div>
+          </article>
+        );
+      })}
+    </div>
+  );
+}
+
+function CoverageItem({
+  label,
+  value,
+  money,
+}: {
+  label: string;
+  value: unknown;
+  money?: boolean;
+}) {
+  if (value === null || value === undefined || value === "") return null;
+  return (
+    <div className="renewal-letter-coverage-item">
+      <p className="muted small">{label}</p>
+      <p className="renewal-letter-value">
+        {money ? formatCell(value, "money") : String(value)}
+      </p>
+    </div>
+  );
+}
+
+// Hint to the bundler that API_ORIGIN is part of the API surface used here.
+void API_ORIGIN;

apps/web/src/components/StatementIntake.tsx

@@ -0,0 +1,272 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import Link from "next/link";
+import {
+  getStatementStatus,
+  listStatementBatches,
+  uploadStatementBatch,
+} from "@/lib/api";
+import { useCan } from "@/lib/abilities";
+import { formatDate, SERVICE_KIND_LABELS, serviceKindLabel } from "@/lib/labels";
+import type { ServiceKind, StatementBatch, StatementBatchStatus } from "@/lib/types";
+
+/**
+ * Automatic capture — statement OCR intake (docs/RECEIPT_CAPTURE_SPEC.md §2).
+ *
+ * Each utility company mails 300+ paper bills a month, one per customer, which
+ * staff otherwise key in by hand on the manual tab of the same "Captura"
+ * screen. Here they scan the stack instead, and the machine proposes customer +
+ * amount for every page; a human still confirms before anything reaches the
+ * ledger. Same daily job, same ledger path — only the input differs, which is
+ * why it lives as a mode of Captura rather than a screen of its own.
+ *
+ * One batch = one service kind, because the matcher is scoped per kind: a
+ * water account number and a phone number are compared against different
+ * columns, and mixing them in one upload is how a bill gets posted to the
+ * wrong customer.
+ */
+
+/** The kinds the parsers actually recognise today. */
+const SUPPORTED: ServiceKind[] = ["ELECTRIC", "WATER", "TELEPHONE"];
+/** Uploadable, but every page will land in review until a parser learns it. */
+const OTHER_KINDS: ServiceKind[] = ["GAS", "PROPERTY_TAX", "FEDERAL_ZONE", "CABLE"];
+
+const STATUS_LABEL: Record<StatementBatchStatus, string> = {
+  UPLOADED: "Recibido",
+  PROCESSING: "Procesando…",
+  READY_FOR_REVIEW: "Listo para revisar",
+  COMPLETED: "Registrado",
+  FAILED: "Falló",
+};
+
+export function StatementIntake() {
+  const canIngest = useCan("statement:ingest");
+  const [batches, setBatches] = useState<StatementBatch[]>([]);
+  const [ocrAvailable, setOcrAvailable] = useState<boolean | null>(null);
+  const [storageAvailable, setStorageAvailable] = useState<boolean | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    try {
+      const [list, status] = await Promise.all([
+        listStatementBatches(),
+        getStatementStatus(),
+      ]);
+      setBatches(list.items);
+      setOcrAvailable(status.ocrAvailable);
+      setStorageAvailable(status.storageAvailable);
+      setError(null);
+    } catch (e) {
+      setError((e as Error)?.message ?? "No se pudieron cargar los lotes.");
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  // A batch of 300 pages takes minutes to OCR, so the list refreshes itself
+  // while anything is still working rather than making staff reload.
+  const working = batches.some(
+    (b) => b.status === "PROCESSING" || b.status === "UPLOADED",
+  );
+  useEffect(() => {
+    if (!working) return;
+    const t = setInterval(() => void load(), 4000);
+    return () => clearInterval(t);
+  }, [working, load]);
+
+  const ready = ocrAvailable === true && storageAvailable === true;
+
+  return (
+    <div className="stack">
+      {ocrAvailable === false && (
+        <div className="state-box state-error">
+          Este servidor no tiene OCR instalado, así que no se pueden leer recibos
+          escaneados. Usa la captura manual; el resto del sistema funciona con
+          normalidad.
+        </div>
+      )}
+
+      {storageAvailable === false && (
+        <div className="state-box state-error">
+          Este servidor no tiene configurado el almacenamiento de documentos, así
+          que no hay dónde guardar los recibos escaneados. Usa la captura manual
+          mientras se configura.
+        </div>
+      )}
+
+      {canIngest && ready && <UploadCard onDone={load} />}
+
+      {error && <div className="state-box state-error">{error}</div>}
+
+      <section className="card" style={{ padding: 16 }}>
+        <h2 className="section-title" style={{ marginTop: 0 }}>
+          Lotes
+        </h2>
+        {loading ? (
+          <div className="state-box">Cargando…</div>
+        ) : batches.length === 0 ? (
+          <div className="state-box">Todavía no hay lotes de recibos.</div>
+        ) : (
+          <div className="tx-scroll">
+            <table className="tx-table">
+              <thead>
+                <tr>
+                  <th>Fecha</th>
+                  <th>Servicio</th>
+                  <th>Referencia</th>
+                  <th>Estado</th>
+                  <th className="num">Páginas</th>
+                  <th>Subido por</th>
+                  <th />
+                </tr>
+              </thead>
+              <tbody>
+                {batches.map((b) => (
+                  <tr key={b.id}>
+                    <td style={{ whiteSpace: "nowrap" }}>{formatDate(b.createdAt)}</td>
+                    <td>{serviceKindLabel(b.serviceKind)}</td>
+                    <td>{b.label || "—"}</td>
+                    <td>
+                      <StatusTag status={b.status} />
+                      {b.error && (
+                        <div className="page-sub" style={{ marginTop: 4 }}>
+                          {b.error}
+                        </div>
+                      )}
+                    </td>
+                    <td className="num">{b._count?.documents ?? 0}</td>
+                    <td>{b.uploadedBy?.name ?? "—"}</td>
+                    <td>
+                      <Link className="btn btn-ghost" href={`/recibos/${b.id}`}>
+                        Revisar
+                      </Link>
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+      </section>
+    </div>
+  );
+}
+
+function StatusTag({ status }: { status: StatementBatchStatus }) {
+  return <span className="tag">{STATUS_LABEL[status] ?? status}</span>;
+}
+
+function UploadCard({ onDone }: { onDone: () => void }) {
+  const [files, setFiles] = useState<File[]>([]);
+  const [serviceKind, setServiceKind] = useState<ServiceKind>("ELECTRIC");
+  const [label, setLabel] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit() {
+    if (!files.length) return;
+    setBusy(true);
+    setError(null);
+    try {
+      await uploadStatementBatch(files, serviceKind, label.trim() || undefined);
+      setFiles([]);
+      setLabel("");
+      onDone();
+    } catch (e) {
+      setError((e as Error)?.message ?? "No se pudo subir el lote.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const unsupported = !SUPPORTED.includes(serviceKind);
+
+  return (
+    <section className="card" style={{ padding: 16 }}>
+      <h2 className="section-title" style={{ marginTop: 0 }}>
+        Subir recibos escaneados
+      </h2>
+      <div className="inline-form" style={{ flexWrap: "wrap", gap: 12 }}>
+        <label>
+          <span className="page-sub">Servicio</span>
+          <select
+            className="input"
+            value={serviceKind}
+            onChange={(e) => setServiceKind(e.target.value as ServiceKind)}
+          >
+            <optgroup label="Con lectura automática">
+              {SUPPORTED.map((k) => (
+                <option key={k} value={k}>
+                  {SERVICE_KIND_LABELS[k] ?? k}
+                </option>
+              ))}
+            </optgroup>
+            <optgroup label="Sin lectura automática (revisión manual)">
+              {OTHER_KINDS.map((k) => (
+                <option key={k} value={k}>
+                  {SERVICE_KIND_LABELS[k] ?? k}
+                </option>
+              ))}
+            </optgroup>
+          </select>
+        </label>
+
+        <label>
+          <span className="page-sub">Referencia (opcional)</span>
+          <input
+            className="input"
+            placeholder="ej. CFE julio 2026"
+            value={label}
+            onChange={(e) => setLabel(e.target.value)}
+          />
+        </label>
+
+        <label>
+          <span className="page-sub">Archivos PDF</span>
+          <input
+            type="file"
+            className="input"
+            accept="application/pdf"
+            multiple
+            onChange={(e) => setFiles(Array.from(e.target.files ?? []))}
+          />
+        </label>
+
+        <button
+          type="button"
+          className="btn btn-primary"
+          disabled={!files.length || busy}
+          onClick={submit}
+        >
+          {busy ? "Subiendo…" : `Procesar ${files.length || ""}`.trim()}
+        </button>
+      </div>
+
+      {error && (
+        <div className="state-box state-error" style={{ marginTop: 12 }}>
+          {error}
+        </div>
+      )}
+
+      {unsupported && (
+        <div className="state-box" style={{ marginTop: 12 }}>
+          Todavía no hay lectura automática para{" "}
+          {SERVICE_KIND_LABELS[serviceKind] ?? serviceKind}: cada página quedará
+          para revisión manual. Al confirmarlas se guarda el número de cuenta,
+          así que los recibos del mes siguiente sí se reconocerán solos.
+        </div>
+      )}
+
+      <p className="page-sub" style={{ marginTop: 12 }}>
+        Un lote es de un solo servicio. Cada página del PDF se trata como un
+        recibo distinto, salvo que el proveedor imprima varias hojas por cliente.
+      </p>
+    </section>
+  );
+}

apps/web/src/lib/api.ts

@@ -6,18 +6,34 @@ import type {
   BalanceFilter,
   BalanceListResponse,
   BalanceSort,
+  BankAccount,
   BankCleared,
   BankDirection,
   BankFacets,
+  BankInstitution,
   BankListResponse,
   BankSort,
   BankStats,
   BankSummary,
+  BatchCreateInput,
+  ConfirmBatchInput,
+  ConfirmBatchResult,
+  BatchCreateResponse,
   BillingFacets,
   BillingStats,
   BusinessLine,
+  ByCheckResponse,
+  CreateBankAccountInput,
+  CreateBankInput,
   CreateBankMovementInput,
   CreateMovementInput,
+  UpdateBankAccountInput,
+  ResolveOutstandingInput,
+  ReviewDocumentInput,
+  StatementBatch,
+  StatementBatchDetail,
+  StatementDocument,
+  StatementDocumentStatus,
   CustomerDetail,
   CustomerInput,
   CustomerListResponse,
@@ -44,6 +60,8 @@ import type {
   PropertyListResponse,
   PropertySort,
   PropertyStats,
+  ReportCatalog,
+  ReportRunResult,
   ServiceInput,
   TrustInput,
   Role,
@@ -55,8 +73,24 @@ import type {
   UserRow,
 } from "./types";
 
-export const API_ORIGIN =
-  process.env.NEXT_PUBLIC_API_ORIGIN ?? "http://localhost:3001";
+// Resolve the API origin at runtime, not build time. In the browser it comes
+// from window.__API_ORIGIN__, injected server-side by the root layout from the
+// deploy .env (API_ORIGIN) — so one built image serves any deployment. On the
+// server (SSR) read process.env directly. NEXT_PUBLIC_API_ORIGIN stays as the
+// dev/build fallback.
+function resolveApiOrigin(): string {
+  if (typeof window !== "undefined") {
+    const injected = (window as { __API_ORIGIN__?: string }).__API_ORIGIN__;
+    if (injected) return injected;
+  }
+  return (
+    process.env.API_ORIGIN ??
+    process.env.NEXT_PUBLIC_API_ORIGIN ??
+    "http://localhost:3001"
+  );
+}
+
+export const API_ORIGIN = resolveApiOrigin();
 
 export class ApiError extends Error {
   status: number;
@@ -114,10 +148,30 @@ export function me(): Promise<AuthUser> {
   return apiFetch<AuthUser>("/auth/me");
 }
 
+/** Persist the caller's own text-size preference on their account. */
+export function updateUiScale(uiScale: number): Promise<AuthUser> {
+  return apiFetch<AuthUser>("/auth/preferences", {
+    method: "PATCH",
+    body: JSON.stringify({ uiScale }),
+  });
+}
+
 export function logout(): Promise<{ success: boolean }> {
   return apiFetch<{ success: boolean }>("/auth/logout", { method: "POST" });
 }
 
+export interface ServiceVersion {
+  service: string;
+  version: string;
+  gitSha: string;
+  buildDate: string;
+}
+
+/** What the API container reports it is running. Unauthenticated by design. */
+export function getApiVersion(): Promise<ServiceVersion> {
+  return apiFetch<ServiceVersion>("/version");
+}
+
 export function getStats(): Promise<CustomerStats> {
   return apiFetch<CustomerStats>("/customers/stats");
 }
@@ -413,6 +467,47 @@ export function removePropertyDocument(
   });
 }
 
+export function propertyDocumentDownloadUrl(
+  propertyId: string,
+  documentId: string,
+): string {
+  return `${API_ORIGIN}/properties/${propertyId}/documents/${documentId}/download`;
+}
+
+export function uploadPropertyDocument(
+  propertyId: string,
+  file: File,
+  type?: string,
+): Promise<unknown> {
+  const q = type ? `?type=${encodeURIComponent(type)}` : "";
+  return uploadFile(`/properties/${propertyId}/documents${q}`, file);
+}
+
+export function removePolicyDocument(
+  policyId: string,
+  documentId: string,
+): Promise<unknown> {
+  return apiFetch(`/policies/${policyId}/documents/${documentId}`, {
+    method: "DELETE",
+  });
+}
+
+export function policyDocumentDownloadUrl(
+  policyId: string,
+  documentId: string,
+): string {
+  return `${API_ORIGIN}/policies/${policyId}/documents/${documentId}/download`;
+}
+
+export function uploadPolicyDocument(
+  policyId: string,
+  file: File,
+  type?: string,
+): Promise<unknown> {
+  const q = type ? `?type=${encodeURIComponent(type)}` : "";
+  return uploadFile(`/policies/${policyId}/documents${q}`, file);
+}
+
 /* ------------------------------------------- Billing / statements module */
 
 export interface MovementQuery {
@@ -425,6 +520,10 @@ export interface MovementQuery {
   typeId?: string;
   source?: string;
   customerId?: string;
+  /** Restrict to captured-but-unpaid rows (the NOPAGO worklist). */
+  outstanding?: boolean;
+  /** Exact check number — the by-check reconciliation lookup. */
+  checkNumber?: string;
   /** `YYYY-MM-DD`, inclusive on both ends. */
   from?: string;
   to?: string;
@@ -442,6 +541,8 @@ export function listMovements(q: MovementQuery): Promise<MovementListResponse> {
   if (q.typeId) params.set("typeId", q.typeId);
   if (q.source) params.set("source", q.source);
   if (q.customerId) params.set("customerId", q.customerId);
+  if (q.outstanding !== undefined) params.set("outstanding", String(q.outstanding));
+  if (q.checkNumber) params.set("checkNumber", q.checkNumber);
   if (q.from) params.set("from", q.from);
   if (q.to) params.set("to", q.to);
   if (q.sort) params.set("sort", q.sort);
@@ -500,9 +601,45 @@ export function voidMovement(id: string): Promise<Transaction> {
   return apiFetch<Transaction>(`/billing/${id}/void`, { method: "POST" });
 }
 
+/** Capture many customers' receipts against one check, in one transaction. The
+ *  returned `items` are positionally parallel to `input.lines`. */
+export function createMovementBatch(
+  input: BatchCreateInput,
+): Promise<BatchCreateResponse> {
+  return apiFetch<BatchCreateResponse>("/billing/batch", {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+/** Clear an outstanding (NOPAGO) row: stamps the check number + resolution date
+ *  and starts counting it toward the balance. 400 if not outstanding or voided. */
+export function resolveOutstanding(
+  id: string,
+  input: ResolveOutstandingInput,
+): Promise<Transaction> {
+  return apiFetch<Transaction>(`/billing/${id}/resolve-outstanding`, {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+/** Everything captured against one check, with its reconciliation total. */
+export function getByCheck(checkNumber: string): Promise<ByCheckResponse> {
+  return apiFetch<ByCheckResponse>(
+    `/billing/by-check?checkNumber=${encodeURIComponent(checkNumber)}`,
+  );
+}
+
 /* ------------------------------------------------- Bank register (chequera) */
 
+/**
+ * Every read below is scoped to one chequera. `bankAccountId` is required, not
+ * defaulted to "all accounts": the office's registers are in different
+ * currencies, and a combined total would be a figure that never existed.
+ */
 export interface BankQuery {
+  bankAccountId: string;
   query?: string;
   page?: number;
   pageSize?: number;
@@ -515,7 +652,7 @@ export interface BankQuery {
 }
 
 export function listBankMovements(q: BankQuery): Promise<BankListResponse> {
-  const params = new URLSearchParams();
+  const params = new URLSearchParams({ bankAccountId: q.bankAccountId });
   if (q.query) params.set("query", q.query);
   if (q.page) params.set("page", String(q.page));
   if (q.pageSize) params.set("pageSize", String(q.pageSize));
@@ -524,20 +661,78 @@ export function listBankMovements(q: BankQuery): Promise<BankListResponse> {
   if (q.from) params.set("from", q.from);
   if (q.to) params.set("to", q.to);
   if (q.sort) params.set("sort", q.sort);
-  const qs = params.toString();
-  return apiFetch<BankListResponse>(`/bank${qs ? `?${qs}` : ""}`);
+  return apiFetch<BankListResponse>(`/bank?${params.toString()}`);
 }
 
-export function getBankStats(): Promise<BankStats> {
-  return apiFetch<BankStats>("/bank/stats");
+export function getBankStats(bankAccountId: string): Promise<BankStats> {
+  return apiFetch<BankStats>(
+    `/bank/stats?bankAccountId=${encodeURIComponent(bankAccountId)}`,
+  );
 }
 
-export function getBankFacets(): Promise<BankFacets> {
-  return apiFetch<BankFacets>("/bank/facets");
+export function getBankFacets(bankAccountId: string): Promise<BankFacets> {
+  return apiFetch<BankFacets>(
+    `/bank/facets?bankAccountId=${encodeURIComponent(bankAccountId)}`,
+  );
 }
 
-export function getBankSummary(year?: number): Promise<BankSummary> {
-  return apiFetch<BankSummary>(`/bank/summary${year ? `?year=${year}` : ""}`);
+export function getBankSummary(
+  bankAccountId: string,
+  year?: number,
+): Promise<BankSummary> {
+  const params = new URLSearchParams({ bankAccountId });
+  if (year) params.set("year", String(year));
+  return apiFetch<BankSummary>(`/bank/summary?${params.toString()}`);
+}
+
+/* --------------------------------------------- Chequera accounts (catalog) */
+
+/** The account picker's source. Includes closed accounts, which stay readable. */
+export function listBankAccounts(): Promise<BankAccount[]> {
+  return apiFetch<BankAccount[]>("/bank/accounts");
+}
+
+export function listBankInstitutions(): Promise<BankInstitution[]> {
+  return apiFetch<BankInstitution[]>("/bank/banks");
+}
+
+export function createBankInstitution(
+  input: CreateBankInput,
+): Promise<BankInstitution> {
+  return apiFetch<BankInstitution>("/bank/banks", {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+export function updateBankInstitution(
+  id: string,
+  input: Partial<CreateBankInput>,
+): Promise<BankInstitution> {
+  return apiFetch<BankInstitution>(`/bank/banks/${id}`, {
+    method: "PATCH",
+    body: JSON.stringify(input),
+  });
+}
+
+export function createBankAccount(
+  input: CreateBankAccountInput,
+): Promise<unknown> {
+  return apiFetch("/bank/accounts", {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+/** No `currency` — an account's booked movements are denominated in it. */
+export function updateBankAccount(
+  id: string,
+  input: UpdateBankAccountInput,
+): Promise<unknown> {
+  return apiFetch(`/bank/accounts/${id}`, {
+    method: "PATCH",
+    body: JSON.stringify(input),
+  });
 }
 
 /** Append a new chequera movement. Booked rows are never edited — fix mistakes
@@ -598,17 +793,29 @@ export function resetUserPassword(id: string, password: string): Promise<UserRow
   });
 }
 
+export function deleteUser(id: string): Promise<void> {
+  return apiFetch<void>(`/users/${id}`, { method: "DELETE" });
+}
+
 /* ------------------------------------------- DB operations (admin only) */
 
 export function listIngest(): Promise<IngestFile[]> {
   return apiFetch<IngestFile[]>("/ops/ingest");
 }
 
-/** Multipart upload — not JSON, so it bypasses apiFetch's Content-Type. */
-export async function uploadIngest(name: string, file: File): Promise<void> {
+/**
+ * Multipart upload — not JSON, so it bypasses apiFetch's Content-Type. `path`
+ * is API-relative (may include a query string); `filename` overrides the part
+ * name sent to the server.
+ */
+export async function uploadFile(
+  path: string,
+  file: File,
+  filename?: string,
+): Promise<unknown> {
   const body = new FormData();
-  body.append("file", file, name);
-  const res = await fetch(`${API_ORIGIN}/ops/ingest/${encodeURIComponent(name)}`, {
+  body.append("file", file, filename ?? file.name);
+  const res = await fetch(`${API_ORIGIN}${path}`, {
     method: "POST",
     credentials: "include",
     body,
@@ -623,6 +830,11 @@ export async function uploadIngest(name: string, file: File): Promise<void> {
     }
     throw new ApiError(res.status, message);
   }
+  return res.status === 204 ? undefined : res.json().catch(() => undefined);
+}
+
+export function uploadIngest(name: string, file: File): Promise<unknown> {
+  return uploadFile(`/ops/ingest/${encodeURIComponent(name)}`, file, name);
 }
 
 export function deleteIngest(name: string): Promise<unknown> {
@@ -656,3 +868,133 @@ export function startOpsJob(kind: OpsJobKind, file?: string): Promise<OpsJob> {
     body: JSON.stringify({ kind, file }),
   });
 }
+
+/* ----------------------------------------------------------- Reports module */
+
+export function getReportCatalog(): Promise<ReportCatalog> {
+  return apiFetch<ReportCatalog>("/reports");
+}
+
+export function runReport(
+  slug: string,
+  params: Record<string, string | undefined>,
+): Promise<ReportRunResult> {
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v != null && v !== "") qs.set(k, v);
+  }
+  const tail = qs.toString();
+  return apiFetch<ReportRunResult>(`/reports/${slug}${tail ? `?${tail}` : ""}`);
+}
+
+/** Build a download URL for a report's file output. The session cookie
+ *  travels with the browser's same-origin navigation, so a plain `href`
+ *  is enough — no fetch-with-credentials dance. */
+export function reportDownloadUrl(
+  slug: string,
+  format: "csv" | "xlsx" | "pdf" | "print",
+  params: Record<string, string | undefined>,
+): string {
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v != null && v !== "") qs.set(k, v);
+  }
+  const tail = qs.toString();
+  return `${API_ORIGIN}/reports/${slug}/${format}${tail ? `?${tail}` : ""}`;
+}
+
+/* ------------------------------------- Statement OCR intake (recibos) */
+
+/**
+ * Whether this deployment can ingest scans — automatic capture is hidden
+ * without it. OCR reads the page, object storage keeps it; both are required.
+ */
+export function getStatementStatus(): Promise<{
+  ocrAvailable: boolean;
+  storageAvailable: boolean;
+}> {
+  return apiFetch("/statements/status");
+}
+
+export function listStatementBatches(
+  page = 1,
+  pageSize = 25,
+): Promise<{
+  items: StatementBatch[];
+  total: number;
+  page: number;
+  pageSize: number;
+  pageCount: number;
+}> {
+  return apiFetch(`/statements/batches?page=${page}&pageSize=${pageSize}`);
+}
+
+export function getStatementBatch(id: string): Promise<StatementBatchDetail> {
+  return apiFetch(`/statements/batches/${id}`);
+}
+
+export function listStatementDocuments(
+  batchId: string,
+  status?: StatementDocumentStatus,
+): Promise<StatementDocument[]> {
+  const q = status ? `?status=${status}` : "";
+  return apiFetch(`/statements/batches/${batchId}/documents${q}`);
+}
+
+/** Multi-file upload — one batch is usually several multi-page scans. */
+export async function uploadStatementBatch(
+  files: File[],
+  serviceKind: ServiceKind,
+  label?: string,
+): Promise<StatementBatch> {
+  const body = new FormData();
+  for (const f of files) body.append("files", f, f.name);
+  const qs = new URLSearchParams({ serviceKind });
+  if (label) qs.set("label", label);
+
+  const res = await fetch(`${API_ORIGIN}/statements/batches?${qs}`, {
+    method: "POST",
+    credentials: "include",
+    body,
+  });
+  if (!res.ok) {
+    let message = `Error ${res.status}`;
+    try {
+      const b = await res.json();
+      if (b?.message) message = b.message;
+    } catch {
+      /* non-JSON error body */
+    }
+    throw new Error(message);
+  }
+  return res.json();
+}
+
+export function reviewStatementDocument(
+  id: string,
+  input: ReviewDocumentInput,
+): Promise<StatementDocument> {
+  return apiFetch(`/statements/documents/${id}`, {
+    method: "PATCH",
+    body: JSON.stringify(input),
+  });
+}
+
+export function rejectStatementDocument(id: string): Promise<StatementDocument> {
+  return apiFetch(`/statements/documents/${id}/reject`, { method: "POST" });
+}
+
+export function confirmStatementBatch(
+  batchId: string,
+  input: ConfirmBatchInput,
+): Promise<ConfirmBatchResult> {
+  return apiFetch(`/statements/batches/${batchId}/confirm`, {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+/** The rendered page image. A plain <img src> — the cookie rides along. */
+export function statementPageUrl(documentId: string): string {
+  return `${API_ORIGIN}/statements/documents/${documentId}/page`;
+}

apps/web/src/lib/build-info.ts

@@ -0,0 +1,37 @@
+/**
+ * The web image's own build identity.
+ *
+ * Same runtime-injection trick as API_ORIGIN (lib/api.ts): docker/web.Dockerfile
+ * bakes APP_VERSION / GIT_SHA / BUILD_DATE as ENV, layout.tsx reads them on the
+ * server per request and paints them into window.__APP_BUILD__. Reading
+ * process.env directly from a client component would return undefined — Next
+ * only inlines NEXT_PUBLIC_* into the browser bundle, and baking the version in
+ * at build time is exactly what we are avoiding elsewhere.
+ */
+export interface BuildInfo {
+  version: string;
+  gitSha: string;
+  buildDate: string;
+}
+
+export const UNKNOWN_BUILD: BuildInfo = {
+  version: "dev",
+  gitSha: "unknown",
+  buildDate: "unknown",
+};
+
+/** Server-side read, used by layout.tsx to produce the injected payload. */
+export function readBuildInfoFromEnv(): BuildInfo {
+  return {
+    version: process.env.APP_VERSION ?? UNKNOWN_BUILD.version,
+    gitSha: process.env.GIT_SHA ?? UNKNOWN_BUILD.gitSha,
+    buildDate: process.env.BUILD_DATE ?? UNKNOWN_BUILD.buildDate,
+  };
+}
+
+/** Browser-side read of what layout.tsx injected. */
+export function webBuildInfo(): BuildInfo {
+  if (typeof window === "undefined") return readBuildInfoFromEnv();
+  const injected = (window as { __APP_BUILD__?: BuildInfo }).__APP_BUILD__;
+  return injected ?? UNKNOWN_BUILD;
+}

apps/web/src/lib/labels.ts

@@ -45,6 +45,7 @@ export const SERVICE_KIND_LABELS: Record<string, string> = {
   PROPERTY_TAX: "Predial",
   FEDERAL_ZONE: "Zona Federal",
   ALARM: "Alarma",
+  TELEPHONE: "Teléfono",
   OTHER: "Otro",
 };
 
@@ -57,6 +58,7 @@ export const SERVICE_KIND_GLYPH: Record<string, string> = {
   WATER: "≈",
   ELECTRIC: "⚡",
   GAS: "◐",
+  TELEPHONE: "☎",
   CABLE: "▤",
   PROPERTY_TAX: "⌂",
   FEDERAL_ZONE: "⇲",

apps/web/src/lib/types.ts

@@ -19,6 +19,9 @@ export type Ability =
   | "ledger:void"
   | "bank:create"
   | "bank:void"
+  | "bank:manage-accounts"
+  | "statement:ingest"
+  | "statement:review"
   | "lookup:manage"
   | "user:manage"
   | "db:manage";
@@ -29,6 +32,10 @@ export interface AuthUser {
   email: string;
   role: Role;
   active: boolean;
+  // Text-size preference, stored per account so it follows the person across
+  // machines. localStorage still holds a copy, but only as a pre-paint cache —
+  // this value is the source of truth. See lib/ui-scale.ts.
+  uiScale: number;
   // Resolved server-side from role (abilitiesFor in the API); the UI only ever
   // reads this map, never re-derives the rules. Server still enforces.
   abilities: Record<Ability, boolean>;
@@ -129,6 +136,7 @@ export type ServiceKind =
   | "PROPERTY_TAX"
   | "FEDERAL_ZONE"
   | "ALARM"
+  | "TELEPHONE"
   | "OTHER"
   | string;
 
@@ -667,6 +675,8 @@ export interface Transaction {
   period?: string | null;
   message: string | null;
   checkNumber: string | null;
+  /** App-voided (`voidedAt` set). UI strikes; totals exclude. */
+  voidedAt?: string | null;
   type: TransactionType | null;
 }
 
@@ -716,6 +726,9 @@ export interface Movement {
   type: TransactionType | null;
   /** App-voided (`voidedAt` set). UI strikes; totals exclude. */
   voided: boolean;
+  /** Legacy "NOPAGO": captured but unpaid (no funds). Shown tagged, and kept
+   *  out of every balance until resolved via resolveOutstanding(). */
+  outstanding?: boolean;
 }
 
 /** Payload for POST /billing — a new ledger movement. Sign convention: negative
@@ -731,6 +744,73 @@ export interface CreateMovementInput {
   reference?: string;
   checkNumber?: string;
   message?: string;
+  /** Legacy NOPAGO — captured but unpaid; excluded from balances until resolved. */
+  outstanding?: boolean;
+}
+
+/** One customer's line inside a check batch; check-level fields sit on the parent. */
+export interface BatchLineInput {
+  customerId: string;
+  amount: number;
+  reference?: string;
+  period?: string;
+  message?: string;
+  outstanding?: boolean;
+}
+
+/** Payload for POST /billing/batch — many receipts cut against one check. */
+export interface BatchCreateInput {
+  domain: TransactionDomain;
+  transactionDate: string;
+  checkNumber: string;
+  currency?: Currency;
+  typeId?: string;
+  lines: BatchLineInput[];
+}
+
+export interface BatchCreateResponse {
+  /** Positionally parallel to the submitted `lines`. */
+  items: Transaction[];
+  checkNumber: string;
+  currency: LedgerCurrency;
+  source: "MANUAL" | "BATCH" | "OCR";
+  count: number;
+  outstandingCount: number;
+  /** Excludes outstanding lines — this is the figure to reconcile against the
+   *  physical check. */
+  total: string;
+}
+
+/** Payload for POST /billing/:id/resolve-outstanding. */
+export interface ResolveOutstandingInput {
+  checkNumber: string;
+  resolvedDate: string;
+}
+
+export interface ByCheckItem {
+  id: string;
+  transactionDate: string | null;
+  domain: TransactionDomain;
+  amount: string;
+  currency: LedgerCurrency;
+  direction: LedgerDirection;
+  reference: string | null;
+  period: string | null;
+  message: string | null;
+  outstanding: boolean;
+  type: TransactionType | null;
+  customerId: string;
+  customerName: string;
+  customerNameSource: string | null;
+}
+
+/** GET /billing/by-check — everything cut against one check, for reconciliation. */
+export interface ByCheckResponse {
+  checkNumber: string;
+  items: ByCheckItem[];
+  count: number;
+  outstandingCount: number;
+  totals: { currency: LedgerCurrency; total: string; count: number }[];
 }
 
 export interface MovementListItem extends Movement {
@@ -925,12 +1005,57 @@ export interface CustomerInput {
 /* ------------------------------------------------- Bank register (chequera) */
 
 /**
- * The office's own checking account. Single-currency (MXN) and with no customer
- * link — see `bank.service.ts`. Positive is a deposit, negative a payment, and
- * exactly zero a cancelled cheque.
+ * The office's own checking accounts — one register per chequera, no customer
+ * link. See `bank.service.ts`. Positive is a deposit, negative a payment, and
+ * exactly zero a cancelled cheque. Every figure below belongs to exactly one
+ * `BankAccount` and is denominated in that account's currency; two accounts'
+ * figures are never combined.
  */
 export type BankDirection = "income" | "expense" | "void";
 
+/** A bank the office holds chequeras at. */
+export interface BankInstitution {
+  id: string;
+  name: string;
+  /** "MX" | "US" — informational. */
+  country: string | null;
+}
+
+/** One chequera. Its `currency` is what every figure on the page is read in. */
+export interface BankAccount {
+  id: string;
+  label: string;
+  currency: Currency;
+  /** Soft hint about which line of business it serves; never enforced. */
+  businessLine: TransactionDomain | null;
+  /** Closed accounts stay readable but take no new movements. */
+  active: boolean;
+  bankId: string;
+  bankName: string;
+  bankCountry: string | null;
+}
+
+export interface CreateBankInput {
+  name: string;
+  country?: string;
+}
+
+export interface CreateBankAccountInput {
+  bankId: string;
+  label: string;
+  /** Fixed at creation — an account's booked history is denominated in it. */
+  currency: Currency;
+  businessLine?: TransactionDomain;
+  active?: boolean;
+}
+
+export interface UpdateBankAccountInput {
+  bankId?: string;
+  label?: string;
+  businessLine?: TransactionDomain;
+  active?: boolean;
+}
+
 export type BankCleared = "cleared" | "pending";
 
 export type BankSort =
@@ -962,8 +1087,10 @@ export interface BankListItem {
 }
 
 /** Payload for POST /bank — a new chequera movement. Sign convention: positive
- *  = ingreso, negative = egreso. MXN only. */
+ *  = ingreso, negative = egreso. The currency comes from the account. */
 export interface CreateBankMovementInput {
+  /** Which chequera it lands in. Required. */
+  bankAccountId: string;
   amount: number;
   transactionDate: string;
   concept?: string;
@@ -1025,3 +1152,144 @@ export interface BankSummary {
   /** Cumulative figure the selected year opened on. */
   opening: string;
 }
+
+/* ----------------------------------------------------------- Reports module */
+
+export type ReportDomain =
+  | "clientes"
+  | "polizas"
+  | "servicios"
+  | "estado-cuenta"
+  | "chequera";
+
+export type ReportFormat = "tabular" | "statement" | "letter";
+
+/** Param declaration a report exposes to its filter form. */
+export type ReportParam =
+  | { key: string; label: string; kind: "text"; placeholder?: string; defaultValue?: string }
+  | { key: string; label: string; kind: "number"; defaultValue?: string }
+  | { key: string; label: string; kind: "date"; endOfDay?: boolean; defaultValue?: string }
+  | {
+      key: string;
+      label: string;
+      kind: "select";
+      options: { value: string; label: string }[];
+      defaultValue?: string;
+    }
+  | { key: string; label: string; kind: "customer-picker" };
+
+export interface ReportColumn {
+  key: string;
+  label: string;
+  type: "text" | "number" | "money" | "date";
+  align?: "left" | "right";
+  width?: number;
+}
+
+export interface ReportDef {
+  slug: string;
+  title: string;
+  description: string;
+  domain: ReportDomain;
+  legacyName: string | null;
+  format: ReportFormat;
+  params: ReportParam[];
+  columns: ReportColumn[];
+}
+
+export interface ReportRunResult {
+  columns: ReportColumn[];
+  rows: Array<Record<string, unknown>>;
+  totals?: Record<string, string | number>;
+  subtitle?: string;
+}
+
+export interface ReportCatalog {
+  items: ReportDef[];
+}
+
+/* ------------------------------------- Statement OCR intake (recibos) */
+
+export type StatementBatchStatus =
+  | "UPLOADED"
+  | "PROCESSING"
+  | "READY_FOR_REVIEW"
+  | "COMPLETED"
+  | "FAILED";
+
+export type StatementDocumentStatus =
+  | "PENDING_OCR"
+  | "OCR_FAILED"
+  | "NEEDS_REVIEW"
+  | "MATCHED"
+  | "CONFIRMED"
+  | "POSTED"
+  | "REJECTED";
+
+export interface StatementBatch {
+  id: string;
+  serviceKind: ServiceKind;
+  status: StatementBatchStatus;
+  label: string | null;
+  fileCount: number;
+  error: string | null;
+  createdAt: string;
+  completedAt: string | null;
+  uploadedBy?: { name: string };
+  _count?: { documents: number };
+}
+
+export interface StatementBatchDetail extends StatementBatch {
+  byStatus: Partial<Record<StatementDocumentStatus, number>>;
+  /** Sum of the amounts still awaiting posting. */
+  pendingTotal: string;
+}
+
+export interface StatementDocument {
+  id: string;
+  pageNumber: number;
+  status: StatementDocumentStatus;
+  provider: string | null;
+  ocrConfidence: string | null;
+  extractedAccountRef: string | null;
+  extractedAmount: string | null;
+  extractedPeriod: string | null;
+  extractedDueDate: string | null;
+  extractedCadastralKey: string | null;
+  matchNote: string | null;
+  matchedCustomer: { id: string; name: string } | null;
+  matchedPropertyService: {
+    id: string;
+    kind: ServiceKind;
+    accountNumber: string | null;
+    meterNumber: string | null;
+    property: { id: string; addressLine1: string | null };
+  } | null;
+  postedTransactionId: string | null;
+}
+
+export interface ReviewDocumentInput {
+  accountRef?: string;
+  amount?: number;
+  period?: string;
+  dueDate?: string;
+  matchedPropertyServiceId?: string;
+  matchedCustomerId?: string;
+  status?: "MATCHED" | "NEEDS_REVIEW" | "CONFIRMED";
+}
+
+/** Check-level fields shared by every line posted from a batch. */
+export interface ConfirmBatchInput {
+  checkNumber: string;
+  transactionDate: string;
+  currency?: Currency;
+  typeId?: string;
+  outstanding?: boolean;
+  includeReviewed?: boolean;
+}
+
+export interface ConfirmBatchResult {
+  posted: number;
+  total: string;
+  checkNumber: string;
+}

apps/web/src/lib/ui-scale.ts

@@ -0,0 +1,54 @@
+// App-wide text size. Every font-size *and* every spacing value in globals.css
+// is in rem and the root size is `calc(100% * var(--ui-scale))`, so writing one
+// variable on <html> rescales the entire UI — no per-component work, and the
+// browser's own base font size still applies underneath.
+//
+// The account is the source of truth (User.uiScale, served on /auth/me).
+// localStorage holds a copy purely so the pre-hydration script in
+// app/layout.tsx can paint at the right size before the session is known;
+// AppShell reconciles the two once /auth/me answers. Keep UI_SCALE_KEY and the
+// bounds in sync with that script and with the API's UpdatePreferencesDto.
+
+export const UI_SCALE_KEY = "jc.ui-scale";
+export const DEFAULT_UI_SCALE = 1;
+export const MIN_UI_SCALE = 0.9;
+export const MAX_UI_SCALE = 1.5;
+
+export const UI_SCALES: { value: number; label: string; short: string }[] = [
+  { value: 0.9, label: "Compacto", short: "A" },
+  { value: 1, label: "Normal", short: "A" },
+  { value: 1.15, label: "Grande", short: "A" },
+  { value: 1.3, label: "Muy grande", short: "A" },
+  { value: 1.5, label: "Máximo", short: "A" },
+];
+
+/** Clamp to the supported range; anything unparseable falls back to default. */
+export function normalizeUiScale(value: unknown): number {
+  const n = typeof value === "number" ? value : Number.parseFloat(String(value));
+  if (!Number.isFinite(n)) return DEFAULT_UI_SCALE;
+  return Math.min(MAX_UI_SCALE, Math.max(MIN_UI_SCALE, n));
+}
+
+export function readUiScale(): number {
+  if (typeof window === "undefined") return DEFAULT_UI_SCALE;
+  try {
+    const raw = window.localStorage.getItem(UI_SCALE_KEY);
+    return raw === null ? DEFAULT_UI_SCALE : normalizeUiScale(raw);
+  } catch {
+    // Private mode / storage disabled — the default is still usable.
+    return DEFAULT_UI_SCALE;
+  }
+}
+
+export function applyUiScale(scale: number): void {
+  if (typeof document === "undefined") return;
+  document.documentElement.style.setProperty("--ui-scale", String(scale));
+}
+
+export function saveUiScale(scale: number): void {
+  try {
+    window.localStorage.setItem(UI_SCALE_KEY, String(scale));
+  } catch {
+    /* ignore — the setting just won't survive a reload */
+  }
+}

deploy/galactus/jorgecuadros-app.compose.yml

@@ -0,0 +1,126 @@
+# NestJS API + Next.js web on galactus (standalone Docker, Portainer endpoint 3).
+#
+# Standalone port of deploy/jorgecuadros-app.stack.yml — see the header of
+# deploy/galactus/jorgecuadros-db.compose.yml for the Swarm keys plain compose
+# silently ignores. The one that matters most here: without
+# `restart: unless-stopped` neither service returns after a host reboot.
+#
+# Cross-stack traffic still goes over the HOST, not service DNS. db and minio
+# are separate Portainer stacks, so they are on separate compose networks and
+# their service names do not resolve from here. DATABASE_URL / S3_ENDPOINT must
+# name galactus's own address and the published port — exactly as on cubex
+# today. Do not "simplify" them to `mysql:3306`.
+#
+# ...which means these containers have to resolve galactus's MagicDNS name, and
+# by default they CANNOT. The host runs systemd-resolved, whose 127.0.0.53 stub
+# is unreachable from a container, so Docker falls back to the upstream resolver
+# in /run/systemd/resolve/resolv.conf — the LAN router, which knows nothing
+# about the tailnet. Routing to 100.x works fine; only the lookup fails, and the
+# API dies with Prisma P1001 "can't reach database server". Pointing the
+# containers at Tailscale's own resolver fixes it. 100.100.100.100 is Tailscale's
+# fixed anycast MagicDNS address (identical on every tailnet); the search domain
+# is this tailnet's suffix.
+#
+# The web image is NOT URL-baked: the browser's API origin is injected at
+# runtime from API_ORIGIN (apps/web/src/app/layout.tsx), so the same image works
+# for any deployment. APP_VERSION / GIT_SHA / BUILD_DATE come baked in from
+# build.yml and are surfaced at GET /version (api) and in the web footer.
+#
+# Keep in sync with deploy/jorgecuadros-app.stack.yml when either changes.
+
+services:
+  api:
+    image: git.mancinas.io/rmancinas/jorgecuadros-api:${APP_TAG:-latest}
+    restart: unless-stopped
+    # Stable handle for deploy/scripts/pre-migrate-backup.sh, which finds this
+    # container by label to run mysqldump into the backup volume. A label
+    # survives stack renames; the compose service name does not.
+    labels:
+      io.jorgecuadros.role: "api"
+    dns:
+      # MagicDNS first, then a public resolver. Listing ONLY 100.100.100.100
+      # costs the container public name resolution — apk/npm/any outbound
+      # hostname stops resolving — because MagicDNS does not forward to an
+      # upstream unless the tailnet is configured with global nameservers.
+      - ${TAILSCALE_DNS:-100.100.100.100}
+      - ${FALLBACK_DNS:-1.1.1.1}
+    dns_search:
+      - ${TAILNET_SUFFIX:-tail01aa2.ts.net}
+    environment:
+      DATABASE_URL: ${DATABASE_URL:?DATABASE_URL must be set}
+      SESSION_SECRET: ${SESSION_SECRET:?SESSION_SECRET must be set}
+      # This deployment is HTTP, so a Secure session cookie would never be sent
+      # and login would silently never establish a session (express-session
+      # declines to emit a Secure cookie over a plain connection). Acceptable
+      # here ONLY because galactus is reachable exclusively over Tailscale, so
+      # WireGuard already encrypts the wire. Set this back to "true" the moment
+      # the app is served over TLS or exposed off-tailnet.
+      SESSION_COOKIE_SECURE: ${SESSION_COOKIE_SECURE:-false}
+      WEB_ORIGIN: ${WEB_ORIGIN:?WEB_ORIGIN must be set}
+      PORT: "3001"
+      INGEST_DIR: /data/ingest
+      BACKUP_DIR: /data/backups
+      MIGRATION_ENV: prod
+      # Credentials the "Operaciones" screen runs mysqldump/mysql as. NOT the
+      # application user: --single-transaction needs the global RELOAD privilege
+      # and the app user has only ALL ON jorgecuadros.*, so every backup, sync
+      # and re-import fails without this. Host/port/database still come from
+      # DATABASE_URL — this only changes who logs in. See opsConn() in
+      # apps/api/src/ops/ops.service.ts.
+      OPS_DB_ADMIN_USER: ${OPS_DB_ADMIN_USER:-root}
+      OPS_DB_ADMIN_PASSWORD: ${OPS_DB_ADMIN_PASSWORD:?OPS_DB_ADMIN_PASSWORD must be set}
+      S3_ENDPOINT: ${S3_ENDPOINT:?S3_ENDPOINT must be set}
+      S3_BUCKET: ${S3_BUCKET:-jorgecuadros-documents}
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:?MINIO_ROOT_USER must be set}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?MINIO_ROOT_PASSWORD must be set}
+    ports:
+      - "${API_PORT:-3001}:3001"
+    volumes:
+      # Uploaded Access files and DB backups. Named, so they survive every
+      # redeploy — and so the pre-migrate dump the deploy takes is the same
+      # file the "Operaciones" restore screen lists.
+      - ingest_data:/data/ingest
+      - backup_data:/data/backups
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:3001/health || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+  web:
+    image: git.mancinas.io/rmancinas/jorgecuadros-web:${APP_TAG:-latest}
+    restart: unless-stopped
+    labels:
+      io.jorgecuadros.role: "web"
+    # Next server-side rendering can call the API by API_ORIGIN, which is the
+    # same MagicDNS name — so the web container needs the resolver too.
+    dns:
+      # MagicDNS first, then a public resolver. Listing ONLY 100.100.100.100
+      # costs the container public name resolution — apk/npm/any outbound
+      # hostname stops resolving — because MagicDNS does not forward to an
+      # upstream unless the tailnet is configured with global nameservers.
+      - ${TAILSCALE_DNS:-100.100.100.100}
+      - ${FALLBACK_DNS:-1.1.1.1}
+    dns_search:
+      - ${TAILNET_SUFFIX:-tail01aa2.ts.net}
+    environment:
+      # Public API URL the browser calls (injected at runtime, see layout.tsx).
+      API_ORIGIN: ${API_ORIGIN:?API_ORIGIN must be set}
+    ports:
+      - "${WEB_PORT:-3000}:3000"
+    depends_on:
+      # Unlike Swarm — which ignores depends_on entirely — plain compose honours
+      # this, so web waits for the API to pass its healthcheck.
+      api:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:3000/ >/dev/null 2>&1 || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+volumes:
+  ingest_data:
+  backup_data:

deploy/galactus/jorgecuadros-db.compose.yml

@@ -0,0 +1,64 @@
+# MySQL for the Jorge Cuadros platform on galactus — the PROD source of truth.
+#
+# galactus is STANDALONE Docker (Portainer endpoint 3, `swarm: inactive`), not
+# the 3-node Swarm on cubex. deploy/jorgecuadros-db.stack.yml is the Swarm
+# version of this file; the deltas are called out below because plain compose
+# SILENTLY IGNORES the Swarm keys rather than erroring on them:
+#
+#   1. `deploy.restart_policy` is ignored -> `restart: unless-stopped` instead.
+#      Without this MySQL does not come back after a host reboot. This is the
+#      single highest-risk difference.
+#   2. `deploy.placement.constraints` is meaningless on one host — dropped,
+#      along with its `docker node update --label-add jorgecuadros_db=true`
+#      prerequisite.
+#   3. `deploy.replicas` / `update_config` are ignored — dropped.
+#   4. `ports: {mode: ingress}` long syntax is Swarm-only -> short syntax.
+#   5. Named volumes stay exactly as they were: the node-pinning hazard that
+#      motivated them was purely a Swarm problem, and Portainer still namespaces
+#      the volume by stack name.
+#
+# This node is the REPLICATION MASTER for the whole topology. Every other MySQL
+# is a replica of it. server-id must be unique across the topology (prod=1,
+# cubex dev=11); a duplicate silently breaks replication. binlog + GTID are on
+# from first boot so a replica can attach with SOURCE_AUTO_POSITION=1 and no
+# file/position bookkeeping.
+#
+# Keep in sync with deploy/jorgecuadros-db.stack.yml when either changes.
+
+services:
+  mysql:
+    image: mysql:8.4
+    restart: unless-stopped
+    command:
+      # (caching_sha2_password is already the default in 8.4; the old
+      #  --default-authentication-plugin flag was REMOVED in 8.4 and aborts boot.)
+      - --server-id=${MYSQL_SERVER_ID:-1}
+      - --log-bin=mysql-bin
+      - --binlog-format=ROW
+      - --gtid-mode=ON
+      - --enforce-gtid-consistency=ON
+      # A replica offline longer than this needs a full re-seed, because the
+      # binlogs it still needs are gone. The 8.4 default is 30 days; raise it
+      # here rather than discovering the gap during an outage.
+      - --binlog-expire-logs-seconds=${MYSQL_BINLOG_EXPIRE_SECONDS:-5184000}
+    environment:
+      MYSQL_DATABASE: ${MYSQL_DATABASE:-jorgecuadros}
+      MYSQL_USER: ${MYSQL_USER:-jorgecuadros}
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD:?MYSQL_PASSWORD must be set}
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:?MYSQL_ROOT_PASSWORD must be set}
+    ports:
+      # Standalone: binds directly on the host. Reachable at
+      # <galactus>:${MYSQL_PORT}. Replicas connect here — see
+      # docs/DEPLOY_AND_MIGRATIONS.md on NOT exposing raw 3306 to the internet.
+      - "${MYSQL_PORT:-3306}:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p$$MYSQL_ROOT_PASSWORD"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 40s
+
+volumes:
+  mysql_data:

deploy/galactus/jorgecuadros-minio.compose.yml

@@ -0,0 +1,32 @@
+# MinIO object storage on galactus (standalone Docker, Portainer endpoint 3).
+#
+# Holds the document blobs extracted from the Access LONGBINARY columns; MySQL
+# keeps only the storageKey pointer. Standalone port of
+# deploy/jorgecuadros-minio.stack.yml — see the header of
+# deploy/galactus/jorgecuadros-db.compose.yml for the full list of Swarm keys
+# that plain compose silently ignores.
+#
+# Keep in sync with deploy/jorgecuadros-minio.stack.yml when either changes.
+
+services:
+  minio:
+    image: minio/minio:RELEASE.2024-10-13T13-34-11Z
+    restart: unless-stopped
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:?MINIO_ROOT_USER must be set}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?MINIO_ROOT_PASSWORD must be set}
+    ports:
+      - "${MINIO_API_PORT:-9000}:9000"
+      - "${MINIO_CONSOLE_PORT:-9001}:9001"
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ["CMD-SHELL", "mc ready local || curl -f http://localhost:9000/minio/health/live || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
+
+volumes:
+  minio_data:

deploy/jorgecuadros-app.env.example

@@ -0,0 +1,34 @@
+# Stack env for deploy/jorgecuadros-app.stack.yml (PROD).
+# Paste these into the Portainer stack's "Environment variables" at deploy time.
+# Do NOT commit real secrets — this file is a template only.
+#
+# HOST below = the swarm host the db/minio/app stacks publish on (cubex).
+
+# Which built image tag to run. latest = default-branch build; or pin sha-<x> / vX.Y.Z.
+APP_TAG=latest
+
+# --- Public URLs (what the end user's BROWSER hits) ---------------------------
+# API_ORIGIN is injected into the web app at runtime and used for browser fetches
+# + document download links, so it must be browser-reachable (not swarm-internal).
+# WEB_ORIGIN is the web app's own public origin; the API allows it via CORS.
+API_ORIGIN=http://192.168.4.212:3001
+WEB_ORIGIN=http://192.168.4.212:3000
+
+# Published ports on the swarm host.
+API_PORT=3001
+WEB_PORT=3000
+
+# --- Database (points at the jorgecuadros-prod-db stack) ----------------------
+# prod db publishes 3306 on the host (see deploy/jorgecuadros-db.stack.yml).
+DATABASE_URL=mysql://jorgecuadros:CHANGE_ME@192.168.4.212:3306/jorgecuadros
+
+# --- Auth --------------------------------------------------------------------
+# 64-hex random. Generate: openssl rand -hex 32
+SESSION_SECRET=CHANGE_ME
+
+# --- Object storage (points at the jorgecuadros-prod-minio stack) -------------
+# Server-side only; prod minio API publishes 9000 on the host.
+S3_ENDPOINT=http://192.168.4.212:9000
+S3_BUCKET=jorgecuadros-documents
+MINIO_ROOT_USER=jc_minio
+MINIO_ROOT_PASSWORD=CHANGE_ME

deploy/jorgecuadros-app.stack.yml

@@ -0,0 +1,111 @@
+# Application stack for the Jorge Cuadros platform: the NestJS API + the Next.js
+# web front-end. The two images are built + pushed by .gitea/workflows/build.yml:
+#   git.mancinas.io/rmancinas/jorgecuadros-api
+#   git.mancinas.io/rmancinas/jorgecuadros-web
+#
+# This stack does NOT ship MySQL or MinIO — those are their own stacks
+# (deploy/jorgecuadros-db.stack.yml, deploy/jorgecuadros-minio.stack.yml). The
+# API reaches them over the network via DATABASE_URL / S3_ENDPOINT, which point
+# at the db + minio stacks' published ingress ports on the swarm host.
+#
+# Target: Portainer local endpoint on cubex (3-node Swarm). PROD only.
+# Deploy with a stack env that supplies every ${VAR:?...} below — see
+# deploy/jorgecuadros-app.env.example for the full list.
+#
+# Statefulness: the API keeps uploaded Access files (ingest) and DB backups on
+# named volumes, which are node-local. So the API is pinned to the same node as
+# the db/minio stacks (node label jorgecuadros_db == true) — a reschedule would
+# otherwise start against empty ingest/backup volumes. The web tier is
+# stateless and floats freely.
+#
+# The web image is NOT URL-baked: the browser's API origin is injected at
+# runtime from API_ORIGIN (see apps/web/src/app/layout.tsx), so this same image
+# works for any deployment — set the URL here, not at build time.
+
+version: "3.8"
+
+services:
+  api:
+    image: git.mancinas.io/rmancinas/jorgecuadros-api:${APP_TAG:-latest}
+    # Container label (not `deploy.labels`, which labels the swarm SERVICE).
+    # deploy/scripts/pre-migrate-backup.mjs finds the container by this label to
+    # run its pre-migrate mysqldump into the backup volume.
+    labels:
+      io.jorgecuadros.role: "api"
+    environment:
+      DATABASE_URL: ${DATABASE_URL:?DATABASE_URL must be set}
+      SESSION_SECRET: ${SESSION_SECRET:?SESSION_SECRET must be set}
+      # CORS: the public origin the browser loads the web app from.
+      WEB_ORIGIN: ${WEB_ORIGIN:?WEB_ORIGIN must be set}
+      PORT: "3001"
+      INGEST_DIR: /data/ingest
+      BACKUP_DIR: /data/backups
+      MIGRATION_ENV: prod
+      # Credentials the "Operaciones" screen runs mysqldump/mysql as. NOT the
+      # application user: --single-transaction needs the global RELOAD privilege
+      # and the app user has only ALL ON jorgecuadros.*, so every backup, sync
+      # and re-import fails without this. Host/port/database still come from
+      # DATABASE_URL — this only changes who logs in. See opsConn() in
+      # apps/api/src/ops/ops.service.ts.
+      OPS_DB_ADMIN_USER: ${OPS_DB_ADMIN_USER:-root}
+      OPS_DB_ADMIN_PASSWORD: ${OPS_DB_ADMIN_PASSWORD:?OPS_DB_ADMIN_PASSWORD must be set}
+      # Object storage — internal endpoint the API (server-side) uses to reach
+      # the minio stack. Not browser-facing (downloads proxy through the API).
+      S3_ENDPOINT: ${S3_ENDPOINT:?S3_ENDPOINT must be set}
+      S3_BUCKET: ${S3_BUCKET:-jorgecuadros-documents}
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:?MINIO_ROOT_USER must be set}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:?MINIO_ROOT_PASSWORD must be set}
+    ports:
+      - target: 3001
+        published: ${API_PORT:-3001}
+        protocol: tcp
+        mode: ingress
+    volumes:
+      - ingest_data:/data/ingest
+      - backup_data:/data/backups
+    deploy:
+      replicas: 1
+      placement:
+        constraints:
+          - node.labels.jorgecuadros_db == true
+      restart_policy:
+        condition: any
+      update_config:
+        order: stop-first
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:3001/health || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+  web:
+    image: git.mancinas.io/rmancinas/jorgecuadros-web:${APP_TAG:-latest}
+    labels:
+      io.jorgecuadros.role: "web"
+    environment:
+      # Public API URL the browser calls (injected at runtime, see layout.tsx).
+      API_ORIGIN: ${API_ORIGIN:?API_ORIGIN must be set}
+    ports:
+      - target: 3000
+        published: ${WEB_PORT:-3000}
+        protocol: tcp
+        mode: ingress
+    depends_on:
+      - api
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: any
+      update_config:
+        order: start-first
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://localhost:3000/ >/dev/null 2>&1 || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+volumes:
+  ingest_data:
+  backup_data:

deploy/scripts/pre-migrate-backup.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+/**
+ * Take a mysqldump immediately before a deploy runs `prisma migrate deploy`.
+ *
+ * The dump runs in a DEDICATED, throwaway container built from the MySQL image,
+ * with the API's backup volume mounted — not inside the API container. Three
+ * reasons, each learned the hard way:
+ *
+ *  1. Deadlock. Dumping inside the API container makes the backup depend on
+ *     whatever toolchain that image happens to carry. When the image shipped a
+ *     MySQL client that could not authenticate, the backup failed, which blocked
+ *     the very deploy that would have replaced the broken image. The backup must
+ *     not depend on the thing being deployed.
+ *  2. The right client. Alpine's `mysql-client` is MariaDB's and cannot perform
+ *     caching_sha2_password (MySQL 8.4's default auth). The official MySQL image
+ *     obviously can.
+ *  3. Diagnosability. A container's logs can simply be read, whereas a detached
+ *     exec reports nothing but an exit code.
+ *
+ * The file still lands in the API's BACKUP_DIR volume, because the only restore
+ * path this platform has is the "Operaciones" admin screen, which lists whatever
+ * `*.sql.gz` sits there (apps/api/src/ops/ops.service.ts).
+ *
+ * It must run BEFORE the app stack is re-applied, while the old container is up
+ * — that container is how the backup volume's name is discovered.
+ *
+ * Required env:
+ *   PORTAINER_URL           https://<host>:9443
+ *   PORTAINER_API_KEY       Portainer access token
+ *   PORTAINER_ENDPOINT_ID   numeric endpoint id (galactus = 3)
+ *   DATABASE_URL            mysql://user:pass@host:port/db — host/port/db only
+ *   MYSQL_ROOT_PASSWORD     the dump runs as root, see below
+ *   BACKUP_TAG              label for the filename, e.g. the deployed tag
+ * Optional env:
+ *   ALLOW_MISSING_CONTAINER=true   exit 0 when no API container exists yet
+ *   BACKUP_VOLUME           override the auto-discovered volume name
+ *   DUMP_IMAGE              default mysql:8.4
+ *   API_CONTAINER_LABEL     default io.jorgecuadros.role=api
+ *   TAILSCALE_DNS / FALLBACK_DNS / TAILNET_SUFFIX
+ *   EXEC_TIMEOUT_SECONDS    default 1800
+ *
+ * Why root: mysqldump --single-transaction issues FLUSH TABLES, which needs the
+ * global RELOAD (or FLUSH_TABLES) privilege. The application user is granted
+ * only ALL ON `<db>`.* by the MySQL image and deliberately has no global rights,
+ * so it cannot take a consistent dump. Backups are an administrative operation;
+ * elevating the app's own runtime user instead would be the worse trade.
+ *
+ * TLS: Portainer here is self-signed; the caller sets
+ * NODE_TLS_REJECT_UNAUTHORIZED=0 for this step.
+ */
+
+function required(name) {
+  const v = process.env[name];
+  if (!v) {
+    console.error(`missing required env: ${name}`);
+    process.exit(1);
+  }
+  return v;
+}
+
+const PORTAINER_URL = required("PORTAINER_URL").replace(/\/+$/, "");
+const API_KEY = required("PORTAINER_API_KEY");
+const ENDPOINT_ID = required("PORTAINER_ENDPOINT_ID");
+const DATABASE_URL = required("DATABASE_URL");
+const ROOT_PASSWORD = required("MYSQL_ROOT_PASSWORD");
+const BACKUP_TAG = required("BACKUP_TAG");
+
+const CONTAINER_LABEL =
+  process.env.API_CONTAINER_LABEL ?? "io.jorgecuadros.role=api";
+const ALLOW_MISSING = process.env.ALLOW_MISSING_CONTAINER === "true";
+const DUMP_IMAGE = process.env.DUMP_IMAGE ?? "mysql:8.4";
+const DNS = [
+  process.env.TAILSCALE_DNS ?? "100.100.100.100",
+  process.env.FALLBACK_DNS ?? "1.1.1.1",
+];
+const DNS_SEARCH = [process.env.TAILNET_SUFFIX ?? "tail01aa2.ts.net"];
+const TIMEOUT_MS = Number(process.env.EXEC_TIMEOUT_SECONDS ?? 1800) * 1000;
+
+const DOCKER = `${PORTAINER_URL}/api/endpoints/${ENDPOINT_ID}/docker`;
+
+async function docker(path, init = {}) {
+  const res = await fetch(`${DOCKER}${path}`, {
+    ...init,
+    headers: {
+      "X-API-Key": API_KEY,
+      ...(init.body ? { "Content-Type": "application/json" } : {}),
+      ...(init.headers ?? {}),
+    },
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`docker ${path} -> ${res.status} ${text.slice(0, 400)}`);
+  }
+  return text ? JSON.parse(text) : null;
+}
+
+/** Single-quote for `sh -c`, the same discipline ops.service.ts uses. */
+function shq(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function parseDbUrl(raw) {
+  const u = new URL(raw);
+  return {
+    host: u.hostname,
+    port: u.port || "3306",
+    database: u.pathname.replace(/^\//, ""),
+  };
+}
+
+/** Matches ops.service.ts's own naming: ISO, colons and dots flattened. */
+function timestamp() {
+  return new Date()
+    .toISOString()
+    .replace(/[:.]/g, "-")
+    .replace("T", "_")
+    .slice(0, 19);
+}
+
+/**
+ * ops.service.ts refuses to restore any name outside this character set, so a
+ * file written with, say, a `/` in the tag would be permanently unrestorable
+ * through the UI. Sanitise before writing, not after.
+ */
+function safeTag(tag) {
+  return tag.replace(/[^A-Za-z0-9._-]/g, "-");
+}
+
+async function findApiContainer() {
+  const [key, value] = CONTAINER_LABEL.split("=");
+  const filters = encodeURIComponent(
+    JSON.stringify({ label: [`${key}=${value}`], status: ["running"] }),
+  );
+  const list = await docker(`/containers/json?filters=${filters}`);
+  return list.length ? list[0] : null;
+}
+
+/** The named volume the API mounts at /data/backups — where restores look. */
+function backupVolumeOf(container) {
+  const mount = (container.Mounts ?? []).find(
+    (m) => m.Destination === "/data/backups",
+  );
+  return mount?.Name ?? null;
+}
+
+/**
+ * Ensure the dump image is present. A `scope: app` deploy never touches the db
+ * stack, so a host can legitimately be missing it — and container/create fails
+ * with a bare 404 that reads like a Portainer problem rather than a missing
+ * image. The image is public, so no registry auth is involved.
+ */
+async function ensureDumpImage() {
+  const [repo, tag = "latest"] = DUMP_IMAGE.split(":");
+  const existing = await docker(`/images/${encodeURIComponent(DUMP_IMAGE)}/json`)
+    .then(() => true)
+    .catch(() => false);
+  if (existing) return;
+  console.log(`pulling ${DUMP_IMAGE} (not present on the host)...`);
+  const res = await fetch(
+    `${DOCKER}/images/create?fromImage=${encodeURIComponent(repo)}&tag=${encodeURIComponent(tag)}`,
+    { method: "POST", headers: { "X-API-Key": API_KEY } },
+  );
+  const body = await res.text();
+  if (!res.ok) {
+    throw new Error(`pull ${DUMP_IMAGE} -> HTTP ${res.status} ${body.slice(0, 300)}`);
+  }
+  for (const line of body.split("\n").filter((l) => l.trim())) {
+    try {
+      const obj = JSON.parse(line);
+      if (obj.error) throw new Error(`pull ${DUMP_IMAGE} failed: ${obj.error}`);
+    } catch (e) {
+      if (e.message.startsWith("pull ")) throw e;
+    }
+  }
+}
+
+async function runDumpContainer(cmd, env) {
+  await ensureDumpImage();
+  const created = await docker(`/containers/create`, {
+    method: "POST",
+    body: JSON.stringify({
+      Image: DUMP_IMAGE,
+      Entrypoint: ["sh", "-c"],
+      Cmd: [cmd],
+      Env: env,
+      HostConfig: {
+        AutoRemove: false, // we read the logs before removing it ourselves
+        Binds: [`${BACKUP_VOLUME}:/data/backups`],
+        Dns: DNS,
+        DnsSearch: DNS_SEARCH,
+      },
+    }),
+  });
+
+  const id = created.Id;
+  try {
+    await docker(`/containers/${id}/start`, { method: "POST" });
+
+    const deadline = Date.now() + TIMEOUT_MS;
+    for (;;) {
+      const info = await docker(`/containers/${id}/json`);
+      if (!info.State.Running) {
+        const logs = await fetch(
+          `${DOCKER}/containers/${id}/logs?stdout=true&stderr=true&tail=40`,
+          { headers: { "X-API-Key": API_KEY } },
+        ).then((r) => r.text());
+        // Strip Docker's 8-byte stream framing and any stray control bytes.
+        const clean = logs
+          .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, "")
+          .trim();
+        return { code: info.State.ExitCode ?? 1, logs: clean };
+      }
+      if (Date.now() > deadline) {
+        throw new Error(`dump timed out after ${TIMEOUT_MS / 1000}s`);
+      }
+      await new Promise((r) => setTimeout(r, 3000));
+    }
+  } finally {
+    await docker(`/containers/${id}?force=true`, { method: "DELETE" }).catch(
+      () => {},
+    );
+  }
+}
+
+let BACKUP_VOLUME = process.env.BACKUP_VOLUME ?? null;
+
+async function main() {
+  const container = await findApiContainer();
+  if (!container) {
+    const message = `no running container matching label ${CONTAINER_LABEL}`;
+    if (ALLOW_MISSING) {
+      console.warn(`skipping pre-migrate backup: ${message}`);
+      return;
+    }
+    throw new Error(
+      `${message} — pass bootstrap=true only if this is the first deploy and ` +
+        `there is genuinely no data to lose`,
+    );
+  }
+
+  BACKUP_VOLUME = BACKUP_VOLUME ?? backupVolumeOf(container);
+  if (!BACKUP_VOLUME) {
+    throw new Error(
+      "could not determine the backup volume from the API container's mounts; " +
+        "set BACKUP_VOLUME explicitly",
+    );
+  }
+
+  const conn = parseDbUrl(DATABASE_URL);
+  const file = `pre-migrate-${safeTag(BACKUP_TAG)}-${timestamp()}.sql.gz`;
+  const out = `/data/backups/${file}`;
+
+  console.log(`database  : ${conn.host}:${conn.port}/${conn.database}`);
+  console.log(`volume    : ${BACKUP_VOLUME}`);
+  console.log(`image     : ${DUMP_IMAGE}`);
+  console.log(`writing   : ${out}`);
+
+  // --set-gtid-purged=OFF because this server is the replication SOURCE with
+  // GTID on. Without it the dump embeds SET @@GLOBAL.GTID_PURGED, which makes
+  // the file unrestorable onto the very server it came from.
+  //
+  // pipefail is essential: without it the exit status is gzip's, so a dump that
+  // failed on the first statement still produces a small, perfectly valid .gz —
+  // a "successful" backup containing nothing.
+  //
+  // The table count is asserted for the same reason: valid gzip is not evidence
+  // of a usable dump. It is echoed so the log records how much was captured.
+  //
+  // A failed attempt deletes its own output. Otherwise every failure leaves a
+  // truncated .sql.gz sitting in the volume, and the Operaciones restore screen
+  // lists it as a perfectly ordinary restore point.
+  const dump =
+    `set -o pipefail; ` +
+    `( mysqldump --host=${conn.host} --port=${conn.port} --user=root ` +
+    `--single-transaction --routines --triggers --no-tablespaces ` +
+    `--set-gtid-purged=OFF ${shq(conn.database)} | gzip -c > ${shq(out)} && ` +
+    `gzip -t ${shq(out)} && ` +
+    `TABLES=$(gunzip -c ${shq(out)} | grep -c 'CREATE TABLE') && ` +
+    `echo "tables captured: $TABLES" && ` +
+    `[ "$TABLES" -ge 1 ] ); ` +
+    `rc=$?; ` +
+    `if [ $rc -ne 0 ]; then rm -f ${shq(out)}; ` +
+    `echo "removed incomplete backup ${file}"; fi; ` +
+    `exit $rc`;
+
+  const { code, logs } = await runDumpContainer(dump, [
+    // Password via MYSQL_PWD, never argv — argv is readable through `ps`.
+    `MYSQL_PWD=${ROOT_PASSWORD}`,
+  ]);
+
+  if (logs) console.log(logs);
+  if (code !== 0) {
+    throw new Error(
+      `dump failed (exit ${code}) — refusing to migrate. See the output above.`,
+    );
+  }
+
+  console.log(`ok: ${file} written and verified in ${BACKUP_VOLUME}`);
+}
+
+main().catch((err) => {
+  console.error(`pre-migrate backup FAILED: ${err.message}`);
+  process.exit(1);
+});

deploy/scripts/pull-images.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Pull the api + web images onto the target host before the stack is applied.
+ *
+ * This exists because the deploy action's `pull: true` does NOT reliably
+ * refresh an already-cached tag on a standalone endpoint. Observed on galactus
+ * 2026-07-30: the registry held web:latest built from 3ff56e6, the host still
+ * had a web:latest cached from an earlier commit, the deploy reported success,
+ * and the running container served the OLD build. A moving tag like `latest`
+ * makes this silent — the stack file names the same string either way, so
+ * nothing downstream notices.
+ *
+ * Pulling explicitly, and failing the deploy if a pull fails, makes "the image
+ * the host runs" a thing the workflow controls rather than hopes for.
+ *
+ * Required env:
+ *   PORTAINER_URL, PORTAINER_API_KEY, PORTAINER_ENDPOINT_ID
+ *   REGISTRY, REGISTRY_USERNAME, REGISTRY_PASSWORD
+ *   IMAGES   comma-separated repositories, e.g. "owner/api,owner/web"
+ *   TAG      the tag to pull
+ *
+ * TLS: Portainer here is self-signed; the caller sets
+ * NODE_TLS_REJECT_UNAUTHORIZED=0 for this step.
+ */
+
+function required(name) {
+  const v = process.env[name];
+  if (!v) {
+    console.error(`missing required env: ${name}`);
+    process.exit(1);
+  }
+  return v;
+}
+
+const PORTAINER_URL = required("PORTAINER_URL").replace(/\/+$/, "");
+const API_KEY = required("PORTAINER_API_KEY");
+const ENDPOINT_ID = required("PORTAINER_ENDPOINT_ID");
+const REGISTRY = required("REGISTRY");
+const USERNAME = required("REGISTRY_USERNAME");
+const PASSWORD = required("REGISTRY_PASSWORD");
+const IMAGES = required("IMAGES").split(",").map((s) => s.trim()).filter(Boolean);
+const TAG = required("TAG");
+
+const DOCKER = `${PORTAINER_URL}/api/endpoints/${ENDPOINT_ID}/docker`;
+
+// Docker wants the credentials as base64url'd JSON in a header. Node's
+// "base64url" encoding omits the `=` padding, which Portainer's Go decoder
+// rejects outright ("Illegal base64 data at input byte N"), so build the
+// URL-safe alphabet by hand and KEEP the padding.
+const REGISTRY_AUTH = Buffer.from(
+  JSON.stringify({
+    username: USERNAME,
+    password: PASSWORD,
+    serveraddress: REGISTRY,
+  }),
+)
+  .toString("base64")
+  .replace(/\+/g, "-")
+  .replace(/\//g, "_");
+
+async function pull(repository) {
+  const image = `${REGISTRY}/${repository}`;
+  const url =
+    `${DOCKER}/images/create` +
+    `?fromImage=${encodeURIComponent(image)}&tag=${encodeURIComponent(TAG)}`;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "X-API-Key": API_KEY, "X-Registry-Auth": REGISTRY_AUTH },
+  });
+  const body = await res.text();
+  if (!res.ok) {
+    throw new Error(`pull ${image}:${TAG} -> HTTP ${res.status} ${body.slice(0, 300)}`);
+  }
+  // The endpoint streams newline-delimited JSON and answers 200 even when the
+  // pull itself failed — the failure only shows up as an {"error": ...} object
+  // in the stream, so the status code alone proves nothing.
+  const lines = body.split("\n").filter((l) => l.trim());
+  for (const line of lines) {
+    let obj;
+    try {
+      obj = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (obj.error) {
+      throw new Error(`pull ${image}:${TAG} failed: ${obj.error}`);
+    }
+  }
+  const last = lines.length ? JSON.parse(lines[lines.length - 1]) : {};
+  console.log(`${image}:${TAG} — ${last.status ?? "pulled"}`);
+}
+
+async function main() {
+  for (const repository of IMAGES) {
+    await pull(repository);
+  }
+  console.log("all images pulled");
+}
+
+main().catch((err) => {
+  console.error(`image pull FAILED: ${err.message}`);
+  process.exit(1);
+});

dev.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+#
+# Start the development servers (API + web).
+# Runs both in parallel and shuts both down on Ctrl-C.
+#
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+WEB_PORT=4500
+API_PORT=4501
+
+api_pid=""
+web_pid=""
+
+# Free a port by killing whatever is listening on it (stale dev servers).
+free_port() {
+  local port="$1"
+  local pids
+  pids="$(lsof -tiTCP:"$port" -sTCP:LISTEN 2>/dev/null || true)"
+  if [ -n "$pids" ]; then
+    echo "Freeing port $port (killing: $pids)"
+    kill $pids 2>/dev/null || true
+    sleep 1
+  fi
+}
+
+# Kill the child servers once, on Ctrl-C or exit.
+cleanup() {
+  trap - EXIT INT TERM
+  echo ""
+  echo "Shutting down dev servers..."
+  [ -n "$api_pid" ] && kill "$api_pid" 2>/dev/null || true
+  [ -n "$web_pid" ] && kill "$web_pid" 2>/dev/null || true
+}
+trap cleanup EXIT INT TERM
+
+free_port "$API_PORT"
+free_port "$WEB_PORT"
+
+echo "Starting API  -> http://localhost:$API_PORT"
+pnpm --filter @jorgecuadros/api start:dev &
+api_pid=$!
+
+echo "Starting web  -> http://localhost:$WEB_PORT"
+pnpm --filter @jorgecuadros/web dev &
+web_pid=$!
+
+# Wait for both. Ctrl-C fires the trap, which kills them.
+wait

docker-compose.yml

@@ -18,6 +18,25 @@ services:
       timeout: 5s
       retries: 10
 
+  minio:
+    image: minio/minio:RELEASE.2024-10-13T13-34-11Z
+    restart: unless-stopped
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:-jc_minio}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-jc_minio_dev}
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ["CMD-SHELL", "mc ready local || curl -f http://localhost:9000/minio/health/live || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
+
   api:
     build:
       context: .
@@ -26,6 +45,8 @@ services:
     depends_on:
       mysql:
         condition: service_healthy
+      minio:
+        condition: service_healthy
     environment:
       DATABASE_URL: mysql://jorgecuadros:jorgecuadros@mysql:3306/jorgecuadros
       SESSION_SECRET: ${SESSION_SECRET:?SESSION_SECRET must be set}
@@ -34,6 +55,10 @@ services:
       INGEST_DIR: /data/ingest
       BACKUP_DIR: /data/backups
       MIGRATION_ENV: dev
+      S3_ENDPOINT: http://minio:9000
+      S3_BUCKET: jorgecuadros-documents
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:-jc_minio}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-jc_minio_dev}
     volumes:
       - ingest_data:/data/ingest
       - backup_data:/data/backups
@@ -56,3 +81,4 @@ volumes:
   mysql_data:
   ingest_data:
   backup_data:
+  minio_data:

docker/api.Dockerfile

@@ -8,7 +8,9 @@ RUN corepack enable && corepack prepare pnpm@9.15.9 --activate
 
 FROM base AS deps
 # argon2's native addon has no musl prebuild -> compiles from source here.
-RUN apk add --no-cache python3 make g++
+# openssl so `prisma generate` in the build stage sees the same platform the
+# runtime stage does (see the binaryTargets note in schema.prisma).
+RUN apk add --no-cache python3 make g++ openssl
 COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
 COPY apps/api/package.json apps/api/package.json
 COPY apps/web/package.json apps/web/package.json
@@ -32,7 +34,29 @@ ENV NODE_ENV=production
 # (mysqldump), restores (mysql), and the re-import pipeline (python + mdbtools)
 # from inside the API container. Build deps are installed in a throwaway virtual
 # package so pandas/pyarrow build on musl, then dropped from the final layer.
-RUN apk add --no-cache python3 mdbtools mysql-client \
+# openssl is NOT optional: Prisma's query engine resolves its binary target at
+# runtime (linux-musl-openssl-3.0.x) and aborts with "Please manually install
+# OpenSSL" without it. Node bundles its own OpenSSL, so nothing else in this
+# image pulls the system package in.
+# mariadb-connector-c is REQUIRED, not incidental. Alpine's `mysql-client` is
+# MariaDB's client, and it ships with an EMPTY /usr/lib/mariadb/plugin — so it
+# cannot perform caching_sha2_password, which is MySQL 8.4's default and
+# effectively only auth method. Without this package every mysqldump/mysql call
+# from the container dies with:
+#   ERROR 1045: Plugin caching_sha2_password could not be loaded
+# That breaks the pre-migrate deploy backup AND the whole "Operaciones" admin
+# panel (backup, restore, sync, re-import all shell out to these binaries).
+#
+# tesseract-ocr + tesseract-ocr-data-spa + poppler-utils drive the statement
+# OCR intake (RECEIPT_CAPTURE_SPEC §2): poppler's `pdftoppm` rasterises each
+# scanned page and tesseract reads it, with the Spanish traineddata for the
+# accented labels on CFE/CESPT/Telnor bills. These are external binaries rather
+# than a native npm addon so the pnpm workspace stays free of a compiled
+# dependency. If they are absent the API still boots — the statements module
+# reports itself unavailable and only that feature is disabled — but statement
+# ingest is the point of shipping them.
+RUN apk add --no-cache python3 mdbtools mysql-client mariadb-connector-c openssl \
+      tesseract-ocr tesseract-ocr-data-spa poppler-utils \
  && apk add --no-cache --virtual .pybuild python3-dev build-base \
  && rm -rf /var/cache/apk/*
 
@@ -40,6 +64,23 @@ COPY --from=build /repo/node_modules node_modules
 COPY --from=build /repo/packages/database packages/database
 COPY --from=build /repo/apps/api/dist apps/api/dist
 COPY --from=build /repo/apps/api/package.json apps/api/package.json
+# Operational scripts, run on demand — never automatically. seed-user.mjs is the
+# only way to create the first sign-in account on a fresh database, and without
+# it in the image that had to be done from a developer's machine against a
+# production DATABASE_URL. Run it with:
+#   docker exec <api> node apps/api/scripts/seed-user.mjs
+# honouring SEED_EMAIL / SEED_PASSWORD / SEED_NAME. It upserts, so re-running is
+# safe — but note it RESETS the password of an existing account.
+COPY --from=build /repo/apps/api/scripts apps/api/scripts
+# node-linker=hoisted flattens EXTERNAL deps into /repo/node_modules, but the
+# workspace dependency is still linked per-package:
+#   apps/api/node_modules/@jorgecuadros/database -> ../../../../packages/database
+# Copying only /repo/node_modules therefore drops it and the API dies at boot
+# with "Cannot find module '@jorgecuadros/database'". Copy just the scope dir —
+# the rest of apps/api/node_modules is devDependencies (typescript) we don't
+# want in the runtime layer. The relative link resolves because packages/database
+# is copied to the same place above.
+COPY --from=build /repo/apps/api/node_modules/@jorgecuadros apps/api/node_modules/@jorgecuadros
 
 # Migration scripts + their own Python venv (ops.service.ts prefers this venv).
 COPY migration migration

docs/DEPLOY_AND_MIGRATIONS.md

@@ -0,0 +1,318 @@
+# Releasing, deploying, and changing the schema
+
+How a version gets from this repo onto a server, and the one rule that keeps
+rollbacks possible.
+
+## The short version
+
+Dispatch **Cut release** from the Actions tab and pick `patch`, `minor` or
+`major` (or `explicit` plus a number). It stamps every `package.json`, commits
+`chore(release): vX.Y.Z`, tags, and pushes both refs in one go. It refuses a
+version that already exists as a tag, and refuses a no-op bump.
+
+The equivalent by hand, if you would rather cut it locally:
+
+```bash
+pnpm version:set 1.2.0                       # stamp every package.json
+git commit -am "chore(release): v1.2.0"
+git tag v1.2.0 && git push origin master v1.2.0
+```
+
+Either way that push triggers `.gitea/workflows/build.yml`, which builds **both** images in
+one matrix run and publishes:
+
+| tag pushed | image tags produced |
+| --- | --- |
+| `v1.2.0` | `1.2.0`, `1.2`, `sha-<short>` |
+| push to `master` | `master`, `sha-<short>`, `latest` |
+
+Then dispatch a deploy from the Actions tab:
+
+- **galactus** (office server, standalone Docker) — *Deploy to galactus*
+- **cubex** (3-node Swarm) — *Deploy to Portainer*
+
+> **The `v` is not part of the image tag.** `docker/metadata-action`'s
+> `{{version}}` strips it. Git tag `v1.2.0`, dispatch `1.2.0`. Dispatching
+> `v1.2.0` deploys nothing that exists.
+
+**Cut release needs a `RELEASE_TOKEN` secret** — a Gitea PAT with
+`write:repository`. It does not use the built-in Actions token on purpose:
+whether a push made with that token re-triggers `build.yml` depends on the Gitea
+version, and a release that quietly publishes no images is worse than one that
+fails outright. If the build somehow does not start, `build.yml` has
+`workflow_dispatch` — run it against the new tag by hand.
+
+Because api and web are built from one matrix run, they cannot drift at build
+time. They *can* drift at deploy time if a stack is applied with only one image
+moved — the web footer shows both versions and flags a mismatch, and the deploy
+workflow's last step fails if the API does not report the tag you dispatched.
+
+## What a deploy actually does
+
+1. **db + minio** — `scope: full` only. Idempotent; data lives on named volumes.
+2. **Pre-migrate backup** — `deploy/scripts/pre-migrate-backup.mjs` runs
+   `mysqldump` *inside the still-running old API container*, via Portainer's
+   Docker API. The file lands in that container's `BACKUP_DIR` volume as
+   `pre-migrate-<tag>-<timestamp>.sql.gz`, which is exactly what the
+   **Operaciones** admin screen lists and can restore. A dump taken on the CI
+   runner would be unreachable by the only restore path the platform has.
+3. **`prisma migrate deploy`** — as a workflow *step*, never the container
+   `CMD`. If it were the CMD, N replicas would race each other applying the
+   same migration.
+4. **app** — the new api + web images.
+5. **Verify** — `GET /version` on the running API must report the dispatched
+   tag.
+
+Rollback is `tag: 1.1.9` re-dispatched. **That rolls back code only.** The
+schema stays where it is. Which brings us to the rule.
+
+## The rule: expand / contract
+
+Prisma has no down-migrations. There is no `prisma migrate down`, and there
+never will be. So a schema change that the *previous* release cannot tolerate
+turns a 30-second rollback into a restore-from-backup outage.
+
+**Every schema change must leave the previous release working.** Split anything
+destructive across two releases:
+
+| | Release N (expand) | Release N+1 (contract) |
+| --- | --- | --- |
+| Rename a column | add the new column, write to both, read the old | drop the old column |
+| Drop a column | stop reading and writing it in code | drop it |
+| Add a required column | add it nullable (or with a default), backfill | make it `NOT NULL` |
+| Split a table | create the new table, dual-write | stop writing the old, drop it |
+| Add an enum value | add the value; old code must not choke on unknowns | start emitting it |
+
+Ship N, let it soak, *then* ship N+1. If N has to be rolled back you just
+re-dispatch the old tag — the expanded schema still satisfies it.
+
+Restoring from the pre-migrate dump is the **emergency lever, not the routine
+path**, and on galactus it is worse than it sounds: galactus is the replication
+master, DDL replicates through the binlog, and restoring the master from a dump
+diverges every replica. GTIDs will not line up and each replica needs a full
+re-seed. Assume a restore is a multi-hour, whole-topology event.
+
+## Migration history
+
+`packages/database/prisma/migrations/0000_init/` is a **baseline**. It is the
+full schema as it stood on 2026-07-30, generated with:
+
+```bash
+prisma migrate diff --from-empty \
+  --to-schema-datamodel packages/database/prisma/schema.prisma --script
+```
+
+Until then the schema had only ever been applied with `prisma db push`, so no
+history existed and the schema state was disconnected from the app version.
+
+### One-time, on every database that already exists
+
+`0000_init` describes tables those databases already have, so `migrate deploy`
+would fail with **P3005 "the database schema is not empty"**. Mark it applied
+instead of applying it — this writes a `_prisma_migrations` row and changes no
+data:
+
+```bash
+DATABASE_URL=<the database> npx prisma@5 migrate resolve \
+  --applied 0000_init --schema packages/database/prisma/schema.prisma
+```
+
+Do this once per database (prod, dev, any local copy). Verify first that the
+live schema really does match the baseline — this should print an empty
+migration:
+
+```bash
+prisma migrate diff --from-url "$DATABASE_URL" \
+  --to-schema-datamodel packages/database/prisma/schema.prisma --script
+```
+
+If it prints actual statements, the live database has drifted from
+`schema.prisma`. Reconcile *before* baselining, or the first real migration
+will fail against a schema Prisma believes it already knows.
+
+### From here on
+
+```bash
+# edit schema.prisma, then:
+pnpm --filter @jorgecuadros/database exec prisma migrate dev --name add_foo
+```
+
+Commit the generated `migrations/<timestamp>_add_foo/` directory. `db push` is
+now a local-scratch tool only — using it against a database with history
+desynchronises it from `_prisma_migrations`.
+
+## galactus vs cubex
+
+`galactus` is standalone Docker (Portainer endpoint **3**), `cubex` is a 3-node
+Swarm (endpoint **2**). They need different compose files because **plain
+compose silently ignores Swarm's `deploy:` keys** rather than erroring:
+
+| | Swarm (`deploy/*.stack.yml`) | standalone (`deploy/galactus/*.compose.yml`) |
+| --- | --- | --- |
+| restart | `deploy.restart_policy` | `restart: unless-stopped` — **without this nothing comes back after a host reboot** |
+| placement | `node.labels.jorgecuadros_db == true` | dropped, one host |
+| ports | `{mode: ingress}` long syntax | `"3306:3306"` |
+| `depends_on` | ignored by Swarm | honoured, with `condition: service_healthy` |
+| volumes | named | named (unchanged — the pinning hazard was a Swarm problem) |
+
+Keep the two sets in sync when either changes.
+
+On both hosts, cross-stack traffic goes over the **host address**, not compose
+service DNS: db, minio and app are three separate stacks, so three separate
+networks. `DATABASE_URL` and `S3_ENDPOINT` name the host and its published
+port. Do not "simplify" them to `mysql:3306`.
+
+### galactus is addressed by MagicDNS, and containers need help resolving it
+
+galactus is Tailscale-only once it is installed in the office, so every URL
+names `galactus.tail01aa2.ts.net`. Its LAN IP is a DHCP lease and has already
+drifted once — never put a `192.168.4.x` address in a secret.
+
+Containers on galactus cannot resolve that name by default. The host runs
+systemd-resolved, whose `127.0.0.53` stub is unreachable from inside a
+container, so Docker falls back to the upstream resolver listed in
+`/run/systemd/resolve/resolv.conf` — the LAN router, which knows nothing about
+the tailnet. Routing to `100.x` works fine; only the *lookup* fails, and the
+symptom is Prisma **P1001 "can't reach database server"** on a container that
+otherwise started cleanly.
+
+`deploy/galactus/jorgecuadros-app.compose.yml` therefore pins the resolver:
+
+```yaml
+dns:        [100.100.100.100]        # Tailscale's fixed anycast MagicDNS address
+dns_search: [tail01aa2.ts.net]       # this tailnet's suffix
+```
+
+Both are overridable (`TAILSCALE_DNS`, `TAILNET_SUFFIX`) if the tailnet changes.
+Browser-facing origins need none of this — those names resolve on the client.
+
+## Replication
+
+galactus's MySQL is the **master**; every other MySQL in the estate is a
+replica. Consequences that bite:
+
+- `server-id` must be unique across the whole topology (prod `1`, cubex dev
+  `11`). A duplicate breaks replication silently.
+- GTID is on from first boot, so replicas attach with `SOURCE_AUTO_POSITION=1`.
+- `binlog_expire_logs_seconds` is raised to 60 days in the galactus compose file
+  (`MYSQL_BINLOG_EXPIRE_SECONDS`). MySQL 8.4 defaults to 30 days; a replica
+  offline longer than the retention needs a full re-seed.
+
+Still open, and **not** handled by anything in this repo:
+
+- No replication user with `REPLICATION SLAVE` granted exists yet.
+- Nothing sets `read_only` / `super_read_only` on the replicas, so a stray write
+  to a replica will diverge it.
+- The channel to the VPS crosses the public internet. It needs a tunnel or TLS —
+  do not publish raw 3306.
+
+## Seeding the first sign-in account
+
+A freshly migrated database has a schema and **no users**, so nobody can log in.
+`prisma migrate deploy` creates tables, never rows; nothing in the deploy path
+seeds an account, by design — creating an administrator should be a deliberate
+act, not a side effect of shipping code.
+
+`apps/api/scripts/seed-user.mjs` ships inside the API image. On the target host:
+
+```bash
+docker exec -e SEED_PASSWORD='<a strong password>' \
+  <api-container> node apps/api/scripts/seed-user.mjs
+```
+
+Defaults are `admin@jorgecuadros.local` / `ChangeMe!2026` / role `ADMIN`,
+overridable with `SEED_EMAIL`, `SEED_PASSWORD`, `SEED_NAME`. **Do not accept the
+default password on anything but a dev database** — it is published in this
+repo's README. The script upserts by email, so re-running is safe, but it also
+**resets the password of an existing account**.
+
+## The session cookie and TLS
+
+`SESSION_COOKIE_SECURE` controls the `Secure` flag on the session cookie. It
+defaults to on in production, and it must be explicitly `"false"` for a
+deployment served over plain HTTP.
+
+This is not cosmetic. express-session silently declines to emit a `Secure`
+cookie over an unencrypted connection: no `Set-Cookie` header is sent at all,
+`POST /auth/login` still answers `200` with the user object, no session is
+established, every subsequent request gets `403`, and the UI bounces back to
+`/login` in a loop. It looks like an auth bug and is really a transport
+mismatch.
+
+galactus runs with `SESSION_COOKIE_SECURE=false`, which is acceptable **only**
+because it is reachable exclusively over Tailscale — WireGuard already encrypts
+the wire, so the cookie never crosses an untrusted network. Turn it back on the
+moment the app is served over TLS or reachable off-tailnet. Behind a
+TLS-terminating reverse proxy, set `trust proxy` on the Nest app instead of
+disabling the flag.
+
+## The MySQL client inside the API image
+
+Alpine's `mysql-client` package is **MariaDB's** client, and it installs an
+empty `/usr/lib/mariadb/plugin`. It therefore cannot speak
+`caching_sha2_password`, which is MySQL 8.4's default and effectively only auth
+method, and every `mysqldump`/`mysql` call from the container fails with:
+
+```
+ERROR 1045: Plugin caching_sha2_password could not be loaded:
+  ... /usr/lib/mariadb/plugin/caching_sha2_password.so: No such file or directory
+```
+
+`mariadb-connector-c` supplies that plugin and is installed in
+`docker/api.Dockerfile` for exactly this reason — do not drop it as an unused
+dependency. It affects far more than the deploy backup: the entire
+**Operaciones** panel (backup, restore, sync, re-import) shells out to these
+binaries, so without it none of those work in a container either. The feature
+had only ever been exercised with the API running on a developer machine, where
+the Oracle client is installed, which is why this went unnoticed until the
+first containerised deploy.
+
+## The Operaciones panel needs its own database login
+
+The panel's four jobs all shell out to `mysqldump`/`mysql`, and they cannot do
+so as the application user. `mysqldump --single-transaction` issues
+`FLUSH TABLES`, which requires the **global** `RELOAD` privilege; the MySQL
+image grants the app user only `ALL PRIVILEGES ON jorgecuadros.*` plus
+`USAGE ON *.*`. `--skip-lock-tables` does not avoid it. BACKUP therefore failed
+outright, and SYNC and RE-IMPORT with it, because both take a safety backup
+first.
+
+The API is given an admin login out of band rather than permanently elevating
+the user it serves requests as:
+
+```
+OPS_DB_ADMIN_USER=root
+OPS_DB_ADMIN_PASSWORD=<MYSQL_ROOT_PASSWORD>
+```
+
+Both deploy workflows pass these into the app stack from the existing
+`MYSQL_ROOT_PASSWORD` secret. Host, port and database still come from
+`DATABASE_URL` — the override changes *who logs in*, never *which server*. With
+the pair unset the service falls back to the `DATABASE_URL` credentials and logs
+a warning, which is what local development wants.
+
+Two more things the panel's dumps now do, for the same reasons the pre-migrate
+backup does them (see `deploy/scripts/pre-migrate-backup.mjs`):
+
+- **`--set-gtid-purged=OFF`.** galactus is the replication *source* with GTID
+  on, so without this every dump embeds `SET @@GLOBAL.GTID_PURGED` and cannot be
+  restored onto the server it came from — which is precisely what the restore
+  screen exists to do.
+- **`set -o pipefail` and a `CREATE TABLE` count.** `mysqldump | gzip` reports
+  gzip's exit status, and a `mysqldump` that dies on its first statement still
+  produces a ~372-byte perfectly valid archive that passes `gzip -t`. Without
+  both checks a failed backup was recorded as a successful one and listed as an
+  ordinary restore point. A dump that fails now deletes its own output.
+
+## Known caveats in the deploy path
+
+- The pre-migrate backup step sets `NODE_TLS_REJECT_UNAUTHORIZED=0` because
+  Portainer serves a self-signed certificate. It is scoped to that one step,
+  which talks to nothing but Portainer. Replacing the certificate and dropping
+  the flag is the real fix.
+- The runner lives on cubex and must reach the target host's Portainer (9443)
+  **and** MySQL (3306). If it cannot reach 3306, run the migration by hand from
+  a host that can and dispatch with `skip_migrate: true`.
+- `bootstrap: true` lets the pre-migrate backup be skipped when no API container
+  exists yet. Use it for a first-ever deploy only — it is the one switch that
+  lets a migration run with no restore point.

docs/INSURANCE_FEATURES_SPEC.md

@@ -0,0 +1,786 @@
+# Insurance Features — Implementation Spec
+
+Source: Jorge Cuadros meeting notes, 2026-07-25/26 (`Seguros` section), plus a
+read-through of the current `policies/`, `reports/`, `storage/` and `auth/`
+code and a live query of the dev database. This is a forward spec for work
+**not yet built** — contrast with [`RENEWAL_NOTICES.md`](RENEWAL_NOTICES.md),
+which documents the legacy renewal-report chain that has *already* been
+migrated into the `aviso-renovacion` report.
+
+Companion doc: [`RECEIPT_CAPTURE_SPEC.md`](RECEIPT_CAPTURE_SPEC.md) covers the
+Utility Management half of the same meeting (PLAN.md step 11). This doc is the
+insurance half (PLAN.md step 12).
+
+## Why these four features are one spec
+
+The meeting produced four insurance asks. They are specified together because
+they share a spine — the `Policy` record and its expiry/settlement lifecycle:
+
+1. **Renewal notification emails** — automates the *outbound* half of a
+   policy's expiry (30 days before, 15 days before, 7 days after). The report
+   that produces the letter text already exists; nothing sends it.
+2. **Liquidación batch workflow** — the *settlement* half of the same
+   lifecycle. The per-policy fields are wired end to end; only the batch
+   print-and-mark step is missing.
+3. **Certificate / "Solicitud Atlas"** — a customer-facing artifact rendered
+   from the same policy record, delivered through the existing PHP portal.
+4. **Carrier API integration** — an *inbound* path that would populate the
+   same `Policy` rows automatically instead of by hand.
+
+1 and 2 are small additions on top of shipped code. 3 is half-buildable and
+half-blocked on infrastructure. 4 is fully blocked on vendor information.
+
+**Two of the four are much smaller than they sound**, and the spec says so up
+front so nobody re-estimates them as greenfield work: §1 needs a scheduler, a
+mail client and one mutation — the notice table, its idempotency key, and the
+letter body all exist. §2 needs one report and one endpoint.
+
+---
+
+## Ground truth (verified 2026-07-27, do not re-derive)
+
+Everything below was checked against the code and the dev DB
+(`192.168.4.212:3307`), not inferred from the meeting notes.
+
+### What exists
+
+| Thing | Where | State |
+|---|---|---|
+| `Policy.liquidated` / `liquidationNumber` / `liquidationDate` | `schema.prisma:165-167` | wired end to end (DTOs, `?liquidated=` filter, stats, form checkbox, detail label) |
+| `RenewalNotice` model + `@@unique([policyId, generation])` | `schema.prisma:201-217` | **0 rows** — never written by anything |
+| `aviso-renovacion` letter report | `reports.registry.ts:623-799` | shipped; read-only. Its `enviadas`/`pendientes` totals are permanently 0 because nothing writes `RenewalNotice` |
+| Letter render + PDF/CSV/XLSX/print outputs | `reports.types.ts:32`, `outputs.ts`, `ReportRunner.tsx:502` (`LetterLayout`) | shipped, reusable as-is |
+| S3-style optional-client service pattern | `storage.service.ts:28-57` | the pattern the mail client should copy |
+| Single-running-job guard | `ops.service.ts:171-176` | the pattern the cron sweep should copy |
+| Ability matrix (17 abilities) | `auth/abilities.ts` | single source of truth; web consumes the server-resolved map |
+
+### What does not exist
+
+- **No scheduler.** No `@nestjs/schedule`, bull/bullmq, node-cron or
+  `setInterval` in `apps/api`. `ops/` spawns detached child processes on user
+  request only.
+- **No mail code or dependency.** Nothing in any `package.json`, `.env.example`
+  or `docker-compose.yml`.
+- **`EmailTemplate` / `EmailCampaign` / `EmailLog`** (`schema.prisma:540-571`)
+  are dead migrated legacy tables — no FKs, no code touches them. **Leave them
+  alone**; `RenewalNotice` is the send log.
+- `express-session` uses the in-memory default store (`main.ts:28-39`), so
+  sessions die on API restart. Relevant to any customer-identity idea in §3.
+- Reports are gated by `AuthenticatedGuard` alone (`reports.controller.ts:28`)
+  — any logged-in user, including VIEWER, can run any report. Adding a
+  *mutation* to the reports area (§2) means it cannot live on that controller.
+
+### Live data shape
+
+| Measure | Value |
+|---|---|
+| Customers | 1,536 — **1,304 (85%) have a non-blank email** |
+| Customers holding ≥1 policy | 893 — **815 (91%) have an email** |
+| Policies | 2,396 (0 archived); 1,865 have `policyTo` |
+| Policies expiring in the next 12 months | 1,045 (≈87/month) |
+| Liquidated | 2,170; **pending 226** |
+| `liquidationNumber` / `liquidationDate` populated | 2,245 / 2,239 |
+| Installments | 4,724 — 1,849 with `paidDate`, 1,651 with `checkNumber` |
+| `renewal_notices` rows | 0 |
+
+Email volume for §1 sizing: ≈87 policies/month × 3 notices ≈ **260
+emails/month**, and 91% of policyholders are reachable. This is an email
+channel, not a print-fallback channel — but see §1's open question on the
+remaining 9%.
+
+### Two meeting terms have no referent in the data
+
+Do not guess at these. Negative greps re-run 2026-07-27 across `docs/`,
+`migration/` and `apps/`. (A third — "GDMX" — turned out to be a typo for
+`GMX`, confirmed with the user; see §4.)
+
+- **"Solicitud"** — 0 hits. Not a legacy report, form or table. ("Atlas" is a
+  carrier — `COMP = "ATLAS, S.A."` — not a report; see
+  [`RENEWAL_NOTICES.md`](RENEWAL_NOTICES.md).) The closest legacy artifact to a
+  certificate is the `* MENS`/`*MENSAJE` blob letter templates, one per line of
+  business, deliberately excluded from migration
+  (`LEGACY_DATABASES.md` → excluded tables).
+- **"Garantías"** — 0 hits for `garant`/`warranty`. No table, no column.
+
+For reference, both carriers named in the meeting *do* appear in the data:
+`GMX` in `mult.comp`, `m_empr.comp` and `gen1.comp`, and `ANA SEGUROS`
+verbatim (with an inconsistent `ANA` variant in `licencias.comp`) — which
+matches the ANA-autos / GMX-daños split described in §4.
+
+The only hit for `transferencia` anywhere is a bank-register UI label
+(`apps/web/src/app/banco/page.tsx:948`, a SCOTHIA movement type) — unrelated to
+policy settlement. "Número de transferencia" is therefore a **new** requirement
+mapping onto the existing `liquidationNumber` field, not a missed migration.
+
+### Two defects found while verifying this spec
+
+Both are pre-existing, both affect the features below, and both should be fixed
+as part of §2 rather than filed separately.
+
+**(a) `INCENDIO` and `M_EMPR` have no `policy_types` row, and 5 policies lost
+their ramo.** `policy_types` currently holds only `AUTO`, `LICENCIAS`, `MULT`.
+`transform_policies.py:111-115` configures `INCENDIO` and `M_EMPR` too, so the
+migration creates all five — but `policies_policyTypeId_fkey` is **`ON DELETE
+SET NULL`**, so deleting an (apparently unused) lookup row silently blanked the
+ramo on every policy pointing at it. The 5 `m_empr` policies now have
+`policyTypeId = NULL`:
+
+```
+3249481 / 3249872  vence 2014-03-26  pendiente
+3673 / 1200003673  vence 2013-03-30  pendiente
+7000017            sin vigencia      liquidada
+```
+
+Consequence: every ramo-parameterized query filters on
+`policyType: { name: … }` (`reports.registry.ts:703-707`), so these 5 are invisible
+to `aviso-renovacion` *and* would be invisible to §2's pending-liquidación
+report — including 4 that are genuinely pending. `INCENDIO` is a different
+story: the legacy `INCENDIO` table has exactly **1 row**, and it did not
+migrate (customer unresolved), so the ramo is legitimately empty — but the
+`aviso-renovacion` "Incendio" dropdown option still promises a report that can
+only ever return zero rows.
+
+Fix as part of §2: re-seed the two missing `policy_types` rows, re-point the 5
+orphans, and change the FK to `ON DELETE RESTRICT` so a lookup delete fails
+loudly instead of silently blanking data.
+
+**(b) The legacy settlement slots do not match the plan's assumption.**
+`MULT` and `INCENDIO` carry **two** slots (`LIQUIDADA`/`LIQUIDADA 2`,
+`NUM LIQUIDACION`/`NUM LIQUIDACION2`, `F LIQUIDA1`/`F LIQUIDA2`) — but
+`M EMPR` carries **four** (`liquidada` … `liquidada_4`,
+`num_liquidacion` … `num_liquidacion4`, `f_liquida1` … `f_liquida4`).
+Actual usage in the staged data:
+
+| Table | rows | slot 2 number | slot 2 date | slots 3-4 |
+|---|---|---|---|---|
+| `mult` | 773 | 41 (5.3%) | 39 | n/a |
+| `m_empr` | 5 | 0 | 0 | 0 |
+| `incendio` | 1 | 0 | 0 | n/a |
+
+So the second slot was used on ~5% of MULT policies and never anywhere else,
+and slots 3–4 were never used at all. `Policy` collapses this to one set, which
+means **≤41 rows lost a second settlement record** in migration. Design
+decision in §2.
+
+### Utilities ↔ Seguros reconciliation — resolved, not open
+
+The plan carried this as "two competing sources." It is not competitive; one of
+them is unusable.
+
+- **`SEGUROS 16_be.mdb: DATGRAL.[NUM UTIL]`** — 563 complete
+  `(num_id, num_util)` pairs. Validated by comparing the insurance customer's
+  own `NOMBRE` against the utilities customer it points at: **298/563 (53%)
+  match exactly**, the remainder being ordinary name variants (spouses,
+  married names, entity vs. person). This is a real link, and it is the key
+  `transform_customers.py` already uses.
+- **`UTILSEG`** (1,582 rows) — 379 rows carry both a `seguros` and a `util`
+  number. Under the obvious reading (`seguros` → seguros `DATGRAL.num_id`,
+  `util` → utilities `DATGRAL.num_id`) the row's own `NOMBRE` matches the
+  target master's name **58/1,024** and **70/932** of the time respectively —
+  i.e. essentially never. Spot-checking makes it plain:
+
+  ```
+  UTILSEG 'STEWART, KENNETH'   seguros=220 → 'ZEPEDA, JAIME RAUL'   util=441 → 'MENDOZA, SERGIO'
+  UTILSEG 'HANCOCK, STEVENS'   seguros=225 → 'RODRIGUEZ, MIKE'      util=403 → 'JOW, LILY/EVANS, LARRY'
+  UTILSEG 'HUDSON, RICHARD L.' seguros=227 → 'WELLES, ROBERT'       util=218 → 'ARTER, KAREN'
+  ```
+
+  And where the two sources overlap they contradict each other: of 218
+  `seguros` ids present in both, **170 (78%) point at a different utilities
+  customer**; only 48 pairs agree outright.
+
+**Rule: `DATGRAL.[NUM UTIL]` is authoritative. `UTILSEG` is a stale artifact of
+an older numbering and must not be used to reconcile customers.** This matters
+directly to [`RECEIPT_CAPTURE_SPEC.md`](RECEIPT_CAPTURE_SPEC.md) §4
+(customer-number recycling), which touches the same identity space — a
+recycling backfill that consulted `UTILSEG` would merge unrelated people.
+
+---
+
+## 1. Renewal notification emails
+
+### What Jorge asked for
+
+Automatic notice to the customer at **30 days before expiry, 15 days before,
+and 7 days after** — replacing the manual monthly run of the legacy
+`RENEW`/`RENEW2`/`RENEW3` report batch.
+
+### What's already built (do not re-build)
+
+- The letter itself: `aviso-renovacion` (`reports.registry.ts:623-799`) already
+  resolves customer, carrier, `policyTo`, premium, vehicle and the ramo-specific
+  `coveragesJson` keys (`cov.cobertura`, `cov.csl_limite`, `cov.gastos_medico`,
+  `cov.propiedades`, `cov.personas`, `cov.servicio_adicional`) into a
+  `__kind: "letter"` row. **Do not fork this copy** — one letter definition,
+  two render targets.
+- The send log: `RenewalNotice`, with `@@unique([policyId, generation])`
+  (`schema.prisma:216`) — **this is the idempotency mechanism and it is already
+  in place.** A sweep that upserts on that key cannot double-send, even on
+  re-run, redeploy or double-fire. No new dedup design is needed.
+- The cadence maps onto the existing `generation Int` with **no schema
+  change**: 30d-before = 1, 15d-before = 2, 7d-after = 3 — exactly the legacy
+  1st/2nd/3rd notice model.
+
+### 1.1 The scheduler
+
+Add `@nestjs/schedule`. One `@Cron` job, daily, early morning local time.
+
+```
+@Cron("0 6 * * *", { timeZone: "America/Tijuana" })
+async sweepRenewals()
+```
+
+Guard multi-replica double-fire the same way `ops.service.ts:171-176` guards
+concurrent jobs — a DB row, not an in-process flag. Reuse `OpsJob` with a new
+kind, or add a minimal `ScheduledRun` row; either way the guard must be a
+database write, because the API is deployed as a Swarm service and may run more
+than one replica.
+
+The sweep must also be **manually runnable** (an admin endpoint that invokes the
+same service method), so a missed day can be caught up without waiting 24h and
+so the job is testable without clock manipulation.
+
+### 1.2 The sweep query
+
+For each of the three offsets, select non-archived policies whose `policyTo`
+falls on the target date:
+
+| Generation | Target date | Meaning |
+|---|---|---|
+| 1 | `today + 30d` | primer aviso |
+| 2 | `today + 15d` | segundo aviso |
+| 3 | `today - 7d` | tercer aviso (vencida) |
+
+`archivedAt: null`, `policyTo` non-null. **Date comparison must be on the UTC
+date, not the timestamp** — `policyTo` is stored midnight-UTC (see the existing
+report's `Date.UTC(year, month - 1, 1)` bounds at `reports.registry.ts:700`),
+and a naive local-time comparison shifts the whole sweep by a day for
+`America/Tijuana`.
+
+For each hit: render the letter, send, then upsert `RenewalNotice` on
+`[policyId, generation]` with `sentAt`, `channel: EMAIL`, and the provider
+message id. **Upsert after a successful send, not before** — a failed send must
+leave the row absent so the next day's sweep retries it. A row that already has
+`sentAt` is skipped.
+
+Catch-up behaviour: because the query is date-*equality*, a day the job doesn't
+run is a day of notices silently skipped. Either make the sweep look at a
+window (`policyTo` between the target date and the last successful run's target
+date) or record the last successful sweep date and re-run the gap. **Recommend
+the window** — it needs no extra state beyond a `lastSweptAt` and it degrades
+correctly if the API is down for a week.
+
+### 1.3 The mail client
+
+`MailProvider` interface:
+
+```ts
+send(msg: { to: string; subject: string; html: string; attachments?: … })
+  => Promise<{ providerId: string }>
+```
+
+**Amazon SES is the first and intended implementation** — the user already runs
+SES for mass notification, so this reuses an established sending reputation
+rather than warming a new channel. Provider choice and budget are **settled,
+not open questions**; ≈260 emails/month is negligible against existing usage.
+
+Implement it with `@aws-sdk/client-sesv2`, mirroring `StorageService`
+(`storage.service.ts:28-57`) exactly:
+
+- env-driven config (`SES_REGION`, `SES_FROM`, `SES_ACCESS_KEY`,
+  `SES_SECRET_KEY`, optional `SES_CONFIGURATION_SET`), added to `.env.example`;
+- **null client when unconfigured, `ServiceUnavailableException` on use** — an
+  unconfigured mail setup must never crash API boot, same degradation as
+  document storage today;
+- a no-op/log implementation for dev, selected when SES env vars are absent.
+
+The interface stays swappable for testability, not for vendor escape.
+
+Persist the SES message id — add `providerMessageId String?` to `RenewalNotice`
+rather than overloading `notes`, so a bounce or complaint notification can be
+traced back to the notice that caused it. (`notes` stays free-text for staff.)
+
+### 1.4 Manual mark-as-sent
+
+The `aviso-renovacion` doc comment (`reports.registry.ts:617-621`) already
+anticipates this: staff who *mail* a paper notice need to record it.
+`RenewalNoticeChannel` (`MAIL` | `EMAIL`) exists for exactly this distinction.
+
+`POST /policies/:id/renewal-notices` — body `{ generation, channel, sentAt?,
+notes? }`, upserting on the same unique key. This closes the loop that makes
+the report's `enviadas`/`pendientes` totals meaningful for the first time.
+
+### 1.5 Bounces and unsubscribes
+
+Not in the meeting notes, but sending 260 mails/month to a 1,304-address list
+built from decades-old Access data will produce bounces. Minimum viable:
+record `providerMessageId`, and add a `Customer.emailOptOut Boolean @default(false)`
+checked by the sweep. Full SNS bounce-webhook handling is out of scope for the
+first build — but the opt-out flag is not, because there is no other way for a
+customer to stop the mail.
+
+### API surface
+
+| Method | Route | Ability |
+|---|---|---|
+| `POST` | `/policies/:id/renewal-notices` | `renewal:send` |
+| `POST` | `/renewals/sweep` (manual trigger of the cron body) | `renewal:send` |
+| `GET` | `/renewals/pending?days=` (what the next sweep would send) | read (AuthenticatedGuard) |
+
+### Abilities (new)
+
+| Ability | Min role | Notes |
+|---|---|---|
+| `renewal:send` | MANAGER | sends mail to customers on the office's behalf — a higher trust tier than ordinary data entry |
+
+Add to both the `Ability` union and `ABILITY_MIN` in `auth/abilities.ts` — that
+file is the single source of truth; `apps/web/src/lib/abilities.ts` only
+consumes the server-resolved map.
+
+### Open questions
+
+- Which SES region + verified identity/configuration set this sends under, and
+  whether it reuses existing IAM credentials or gets its own scoped
+  `ses:SendEmail` user.
+- The 9% of policyholders with no email (78 of 893) — silently skipped, or
+  surfaced as a "print these" worklist? Recommend the worklist: the existing
+  `aviso-renovacion` report already produces exactly those letters, so it costs
+  one filter parameter.
+- Spanish or English body? The legacy letters were Spanish; the customer base
+  is substantially US-resident. `Customer` has no language preference field.
+
+---
+
+## 2. Liquidación batch workflow
+
+### What Jorge asked for
+
+Print the pending set, then mark many policies settled at once with one
+transfer number — "liquidación de pólizas MULT", garantías excluded.
+
+### What's already built (do not re-build)
+
+`liquidated` / `liquidationNumber` / `liquidationDate` are wired end to end:
+`schema.prisma:165-167`, create+update DTOs (`policy.dto.ts:35-37,59-61`),
+the `?liquidated=` list filter (`policies.service.ts:148`), liquidada/pendiente
+counts in `stats()` (`:219,:237`), `headerData()` pass-through (`:316`), the
+"Liquidada" checkbox in `PolicyForm.tsx:250`, and the detail-page label
+(`polizas/[id]/page.tsx:323`).
+
+**Only the batch layer is missing.** 2,170 of 2,396 policies are already
+marked liquidated from migration; the live pending set is 226.
+
+### 2.1 Pending-liquidación report
+
+New entry in `reports.registry.ts`, `format: "tabular"` — gets print/PDF/CSV/XLSX
+free via the existing `/reportes/:slug` machinery.
+
+Parameterized **by ramo**, mirroring how `vigente` and `aviso-renovacion` already
+take a `policyType` select param. The workflow is *not* MULT-only: the legacy
+`TABLA LIQUIDA MF` scratch table served `MULT`, `INCENDIO` **and** `M EMPR`
+(`LEGACY_DATABASES_OBJECTS.md:4887-5017`).
+
+Params: ramo (with an "todos" option), aseguradora, date range on `policyFrom`.
+Columns: póliza, cliente, ramo, aseguradora, vigencia, prima neta, forma de pago.
+Totals: count + prima neta sum per currency (**never collapse MXN and USD** —
+same constraint as the billing module).
+
+⚠️ Fix defect (a) above before building this, or the report inherits the same
+blind spot: 4 of the 226 pending policies carry `policyTypeId = NULL` and would
+be missing from every ramo-filtered run *and* from the "todos" run if that is
+implemented as a union over known types rather than as "no filter."
+
+### 2.2 Batch settle endpoint
+
+`POST /policies/liquidate-batch` — body:
+
+```
+{ policyIds: string[], liquidationNumber: string, liquidationDate: string }
+```
+
+One `prisma.$transaction`. Rejects ids that are already `liquidated` (return
+them in the response rather than silently skipping, so the UI can say which).
+Writes an `ActivityLog` row per policy — this is a financial settlement marker
+being set across many records at once, and it is the one place in the app where
+a single click changes dozens of rows.
+
+**Ability: new `policy:liquidate` at MANAGER**, not the existing `policy:update`
+(STAFF). Reason: a STAFF user editing one policy's checkbox is data entry; a
+STAFF user settling 200 policies against one transfer number is a financial
+control. Recommend the new ability; note it as a question for Jorge only if he
+wants STAFF to keep doing it.
+
+### 2.3 Un-settle path
+
+The legacy had one (`MULT FAM X POLIZA Consulta`,
+`LEGACY_DATABASES_OBJECTS.md:5570-5573`). `POST /policies/liquidate-batch/undo`
+with the same shape, or `{ liquidationNumber }` to reverse a whole batch.
+Gated at MANAGER via the same `policy:liquidate`. Also logs.
+
+### 2.4 The two-slot decision (defect (b))
+
+`Policy` has one settlement slot; `MULT`/`INCENDIO` had two and `M EMPR` had
+four, with real usage on ≤41 MULT rows and nowhere else.
+
+**Recommendation: move settlement onto `PolicyPaymentInstallment`, do not add a
+second slot to `Policy`.** Reasons:
+
+- `PolicyPaymentInstallment` already exists, already has `paidDate` and
+  `checkNumber`, and already models "the *n*-th payment of this policy" — which
+  is exactly what the second settlement slot meant. 4,724 rows, 1,849 with a
+  paid date.
+- Adding `liquidated2`/`liquidationNumber2`/`liquidationDate2` reproduces the
+  legacy's hardcoded-repeated-columns mistake that this whole migration exists
+  to undo — and `M EMPR` proves it doesn't stop at two.
+- The `Policy`-level fields stay as the *rollup* ("this policy is fully
+  settled"), which is what the existing UI and `?liquidated=` filter already
+  mean. No breaking change.
+
+Concretely: add `liquidationNumber String?` + `liquidatedAt DateTime?` to
+`PolicyPaymentInstallment`; batch-settle writes the installment rows and sets
+`Policy.liquidated = true` when all installments are settled. Backfill the ≤41
+lost slot-2 values from `mult.num_liquidacion2` / `f_liquida2` in
+`transform_policies.py` at the same time.
+
+If Jorge wants the simpler thing instead, say so explicitly and accept that
+those 41 second settlements stay unmigrated.
+
+### 2.5 "Garantías excluded"
+
+Blocked — the term has no referent anywhere in the data (0 hits). Do not guess
+at a filter. Spec'd as: the batch report takes an explicit exclusion list or a
+flag once Jorge identifies what a "garantía" is in his data. Most likely
+candidates to ask about: a `forma_pago` value, an aseguradora, or a
+`coveragesJson` key.
+
+### API surface
+
+| Method | Route | Ability |
+|---|---|---|
+| `GET` | `/reports/liquidacion-pendiente?policyType=&provider=` | read |
+| `POST` | `/policies/liquidate-batch` | `policy:liquidate` |
+| `POST` | `/policies/liquidate-batch/undo` | `policy:liquidate` |
+
+Note the mutation lives on `PoliciesController`, **not** `ReportsController` —
+that controller is deliberately read-only and guarded by `AuthenticatedGuard`
+alone (`reports.controller.ts:28`), so any logged-in VIEWER reaches it.
+
+### Web
+
+Extend `/polizas` with a "Liquidación" tab: the pending list with checkboxes, a
+select-all-filtered action, and one dialog collecting número de transferencia +
+fecha. Print goes through the existing `/reportes/liquidacion-pendiente` runner
+rather than a bespoke print view.
+
+### Abilities (new)
+
+| Ability | Min role | Notes |
+|---|---|---|
+| `policy:liquidate` | MANAGER | batch settlement across many rows; distinct from `policy:update` (STAFF) |
+
+### Open questions
+
+- What "garantías" refers to (blocks the exclusion filter).
+- Two-slot settlement: installment-level (recommended) or a second `Policy` slot.
+- Should `policy:liquidate` be a new MANAGER ability, or is reusing
+  `policy:update` (STAFF) what the office actually wants?
+
+---
+
+## 3. Certificate / "Solicitud Atlas" + portal delivery
+
+### What Jorge asked for
+
+A "Solicitud Atlas" / insurance certificate, visible to customers on the
+website.
+
+### The blocked half
+
+**"Solicitud" has no referent** — 0 hits across 212 SEGUROS reports and 96
+UTILITIES reports; "Atlas" is a carrier, not a report. A *solicitud* is
+normally an **application form** (pre-policy, filled in by the applicant),
+which is a materially different artifact from a **certificate** (post-policy,
+proof of coverage issued to the insured). These need different data, different
+timing and different delivery.
+
+Do not build until Jorge confirms which one he means. The spec below covers the
+**certificate** reading, because that is what "visible to customers on the
+website" implies.
+
+### The buildable half — certificate rendering
+
+Reuse the letter machinery, exactly as `aviso-renovacion` does:
+
+- `format: "letter"` report (`reports.types.ts:32`), rendered by `LetterLayout`
+  (`ReportRunner.tsx:502`) on screen and by `outputs.ts` `renderPdf` for the
+  file.
+- Data needed, all already on `Policy` and its relations: customer name +
+  address, policy number, carrier, `policyFrom`/`policyTo`, and the
+  ramo-specific coverage keys already mapped in
+  [`RENEWAL_NOTICES.md`](RENEWAL_NOTICES.md) — plus `vehicles[0]` for auto and
+  the property address for MULT/INCENDIO/M_EMPR.
+- Parameter is a single policy, not a month — `/reports/certificado?policyId=`.
+  Staff-facing route: a "Certificado" button on `/polizas/[id]`.
+
+### The infrastructure half — portal delivery
+
+[`PLAN.md:16,20-24`](../PLAN.md) locks the customer portal
+(`my-jorgecuadros-web`, PHP/`mysqli`, its own `utility_dbo` DB) as **out of
+scope and unchanged**. This repo has no public route and no `CUSTOMER` role
+(`UserRole` = ADMIN/MANAGER/STAFF/VIEWER, `schema.prisma:43-48`), and its
+sessions are in-memory. Insurance therefore reaches customers as an **extension
+of the already-planned replication** (PLAN.md steps 8/9), not as a new public
+surface here.
+
+What this spec adds to that design, to be finalized when step 8 runs:
+
+- **Which policy fields join the replicated set** — recommend the certificate's
+  own field list and nothing more (policy number, carrier, ramo, vigencia,
+  customer link), explicitly excluding premiums, commissions, liquidation
+  status, `observations` and `notes`. The replicated side is the
+  internet-exposed one; it should never carry the office's margin data.
+- **Certificate as generated PDF, not portal-side rendering.** Render here,
+  upload to the existing S3/MinIO bucket via `StorageService`, replicate the
+  pointer. The portal is PHP and is not being modified; giving it a URL is
+  cheaper than giving it a template. This also means the certificate the
+  customer sees is byte-identical to the one staff printed.
+- Where in `utility_dbo` the pointer lands — depends on the portal's existing
+  policy-facing views (`fm2`/`fm3`/`fmt`, `full_coverage`, `mx_liability`,
+  `usa_liability`), and needs a read of the portal's PHP before it can be
+  stated.
+
+### Abilities
+
+None new. Certificate generation is a read; delivery is a replication concern.
+
+### Open questions
+
+- **What "Solicitud Atlas" actually is** — application form or certificate.
+  Blocks the whole section.
+- If it's an application form: who fills it in (staff on the customer's behalf,
+  or the customer on the portal), and does it need to exist as a record before
+  a `Policy` does? That would be a new model, not a report.
+- Does the certificate need a carrier logo/letterhead? The legacy `* MENS`
+  templates were per-carrier blobs; `outputs.ts` `renderPdf` has no image
+  support today.
+
+---
+
+## 4. Carrier API integration
+
+### What Jorge asked for
+
+Integration with **ANA Seguros** and **GMX**. ("GDMX" in the meeting notes was
+a typo — confirmed with the user 2026-07-27. The data's `GMX` is correct, and
+this is no longer an open question.)
+
+### Carrier research (2026-07-27) — what actually exists
+
+**The two carriers are one company.** ANA and GMX are both members of **Grupo
+Valore**, alongside Seguros Argos (vida) and Prevem Seguros (gastos médicos).
+ANA writes **autos**; GMX writes **daños** — which maps exactly onto the split
+in this database: ANA covers the `AUTO`/`LICENCIAS` book, GMX covers
+`MULT`/`INCENDIO`/`M_EMPR`. Practical consequence: **this is one commercial
+conversation, not two.** The group also shares infrastructure — GMX's own
+quoting micrositio is served from ANA's host
+(`server.anaseguros.com.mx/Micrositios/GRUPOVALOREGMXCOR/`), so one technical
+contact plausibly covers both.
+
+**ANA has a real, live web service.** `https://server.anaseguros.com.mx/ananetws/service.asmx`
+— a classic ASP.NET `.asmx` endpoint speaking SOAP 1.1 and 1.2, with its
+operation list published on the standard help page:
+
+| Purpose | Operations |
+|---|---|
+| Catálogos | `Marca`, `SubMarca`, `Modelo`, `MarcaMoto`, `SubMarcaMoto`, `Color`, `Categoria`, `CatVeh`, `CodigoPostal`, `Colonia`, `ColxCP`, `DelMun`, `EDOS`, `Bancos`, `FormaPago`, `TipoPersona`, `TipoIndem`, `RegimenFiscal`, `Nacionalidad`, `Ocupacion`, `Identificacion`, `GiroEmpresa`, `PropositoMotos`, `Vigencia` |
+| Cotización | `CalculaValor`, `CalculaMSI` |
+| Vehículo | `Vehiculo`, `VehiculoMoto`, `ValidaSerie` |
+| Recuperación / validación | `RecuperaCotizacion`, `ValidaAsegurado` |
+| Transacción | `Transaccion` |
+
+**GMX publishes no machine interface.** Its agent area
+(`gmx.com.mx/soy-agente/herramientas/`) lists only human portals — reporte de
+agentes, cobranzas, envío/descarga de facturas, documentos emitidos, reporte de
+siniestros, artículo 492. No API, no WSDL, no developer contact. The only
+number published is **(55) 5480-4000**.
+
+Neither carrier has a public developer portal or published documentation.
+Across this market, web service credentials are granted **by the carrier, at
+its discretion, to appointed agents on written request** — expect a lead time
+measured in weeks, not a signup form.
+
+### ⚠️ The critical mismatch — read before estimating this
+
+**The ANA service is a new-business quoting/issuance API. What this platform
+needs is an inbound feed of the office's *existing* book.** Every operation
+above serves "price and issue a policy that does not exist yet." Not one of
+them is "list the policies where I am the agent of record," which is what
+would populate `Policy` rows and keep them current.
+
+So the honest reading of the research is:
+
+- If Jorge's ask means **"stop re-typing new policies into two systems"** —
+  the ANA service can do that for autos, and it is genuinely buildable once
+  credentials arrive. GMX/daños would stay manual.
+- If Jorge's ask means **"keep our policy data in sync with the carrier
+  automatically"** — no evidence exists that either carrier offers it, and the
+  question to ask is specifically whether a *portfolio/cartera download*
+  service exists for an agent's own book. That question has not been asked yet.
+
+**Do not commit to this section until Jorge says which of the two he means.**
+The first is a moderate feature; the second may not be purchasable at all.
+
+Note also that nothing in this spec authorizes calling those endpoints. The
+operation list above comes from a published help page; actually invoking
+`CalculaValor` or `Transaccion` requires the agent credentials Jorge would
+obtain, and should not be attempted before then.
+
+### Legacy precedent
+
+Carrier config that exists in the legacy system: `gen1`/`gen2`
+(`LEGACY_DATABASES.md:1872-1892`) — 9 rows keyed by carrier with `RFC`,
+`CLAVE`, `FPAGO`, `MONED`, plus a 14-row agent list. It is the only
+carrier-keyed table anywhere, and it carries **no API metadata** — no endpoint,
+no credential, no identifier that looks like one. In the new schema the
+equivalent is `InsuranceProvider`, which today holds only a name.
+
+### Shape
+
+- `CarrierConnector` interface — `fetchPolicies(since: Date)`,
+  `fetchPolicy(number: string)`, returning a normalized DTO, one implementation
+  per carrier. **The ANA implementation cannot satisfy `fetchPolicies` from the
+  operations known today** (see the mismatch above); if the ask turns out to be
+  outbound issuance instead, the interface is the wrong shape and should become
+  `quote(...)` / `issue(...)` against `CalculaValor` / `Transaccion`.
+- SOAP, not REST, for ANA — `.asmx` with a WSDL. Node has no first-class SOAP
+  client in this stack; budget for `strong-soap`/`soap` plus the schema work,
+  and generate types from the WSDL rather than hand-writing envelopes.
+- Credentials and endpoint config per carrier: extend `InsuranceProvider` with
+  the connector's identifier and store secrets in env, keyed by that identifier
+  — never in the database row.
+- The catalog operations (`Marca`/`SubMarca`/`Modelo`/`CodigoPostal`/`Colonia`)
+  are useful **independently of any policy sync** — they would let the policy
+  form validate vehicle and address data against the carrier's own catalogs
+  instead of free text. That is the cheapest possible first use of these
+  credentials and a sensible pilot: read-only, no issuance risk, immediately
+  visible in `PolicyForm`.
+- **An import-staging + review step, never a direct write to `Policy`.** Same
+  principle as [`RECEIPT_CAPTURE_SPEC.md`](RECEIPT_CAPTURE_SPEC.md) §2, which
+  routes OCR results through a review queue instead of writing ledger rows: one
+  write path, one audit trail, and a human confirms anything a machine
+  proposed. A carrier feed that wrote `Policy` rows directly would also fight
+  the Access sync (`run_all.py --sync`), which owns every row carrying
+  provenance columns — an imported policy needs its own provenance
+  (`legacySourceDb = 'carrier:<name>'`) or the next sync will delete it as a
+  row that vanished from source.
+
+### Abilities (new)
+
+| Ability | Min role | Notes |
+|---|---|---|
+| `carrier:import` | MANAGER | trigger a fetch and approve imported policies |
+
+### Open questions
+
+- ~~Does "GDMX" mean `GMX`?~~ **Resolved 2026-07-27** — yes, a typo in the
+  meeting notes.
+- **Direction — the one that decides whether this is buildable.** Does Jorge
+  want to *stop re-typing new policies* (outbound quote/issue, which the ANA
+  service supports), or *keep existing policies in sync* (inbound portfolio
+  download, which nothing found suggests either carrier offers)?
+- What to ask Grupo Valore, in one call to **(55) 5480-4000** or the ANA agent
+  channel:
+  1. WSDL + test/production credentials for `server.anaseguros.com.mx/ananetws/service.asmx`,
+     and whether an agent appointment is a prerequisite.
+  2. Whether a **cartera / portfolio download** service exists for an agent's
+     own book — the question that decides the direction above.
+  3. Whether **GMX daños** has any machine interface at all, or whether its
+     agent portals are the only access. This is the more valuable half for this
+     office: GMX writes the `MULT`/`INCENDIO`/`M_EMPR` book.
+  4. Whether one set of Grupo Valore credentials spans both carriers, given the
+     shared hosting.
+- Does the office hold agent appointments with both ANA and GMX in good
+  standing? Credential grants are discretionary and appointment-gated.
+
+---
+
+## Build sequencing
+
+1. **§1 renewal emails** — highest value, schema already ready, no blocker
+   beyond the SES sending account. ≈260 mails/month against a 91%-reachable
+   policyholder base.
+2. **§2 liquidación batch** — small, builds on fields already wired. Do the two
+   defect fixes (missing `policy_types` rows + FK `ON DELETE RESTRICT`) as part
+   of it, since both distort its own report.
+3. **§3 certificate** — the report half is buildable now; portal delivery waits
+   on PLAN.md steps 8/9 infrastructure, and the whole section waits on what
+   "Solicitud" means.
+4. **§4 carrier APIs** — blocked on a single phone call, not on research.
+   ANA's SOAP service is real and its operation list is known; what is missing
+   is credentials and an answer on direction (§4's open questions). GMX appears
+   to have nothing machine-readable, which matters because GMX writes the
+   larger half of this office's book. Build last, and consider the catalog-only
+   pilot before anything else.
+
+§1 and §2 are independent of each other and can be built in parallel; both are
+independent of everything in `RECEIPT_CAPTURE_SPEC.md`.
+
+## New abilities across this spec
+
+| Ability | Min role | Section |
+|---|---|---|
+| `renewal:send` | MANAGER | §1 |
+| `policy:liquidate` | MANAGER | §2 |
+| `carrier:import` | MANAGER | §4 |
+
+No collision with the abilities proposed in `RECEIPT_CAPTURE_SPEC.md`
+(`statement:ingest`, `statement:review`, `bank:manage-accounts`,
+`customer:recycle`, `customer:purge`).
+
+## Open questions to take back to Jorge (collected)
+
+**§1 — renewal emails**
+- Which SES region + verified identity/configuration set, and whether to reuse
+  existing IAM credentials or create a scoped `ses:SendEmail` user.
+- The 78 policyholders with no email: skip silently, or produce a print
+  worklist? (Recommend the worklist.)
+- Spanish or English notice body?
+
+**§2 — liquidación**
+- What "garantías" refers to — blocks the exclusion filter.
+- Settlement on `PolicyPaymentInstallment` (recommended) vs. a second slot on
+  `Policy`; and whether to backfill the ≤41 lost MULT second settlements.
+- New `policy:liquidate` (MANAGER) vs. reusing `policy:update` (STAFF).
+
+**§3 — certificate**
+- What "Solicitud Atlas" is: application form or certificate. Blocks the section.
+- If application form: who fills it in, and does it precede the `Policy` record?
+- Does the certificate need carrier letterhead/logo?
+
+**§4 — carrier APIs** (all four go in one call to Grupo Valore, (55) 5480-4000)
+- Direction: outbound quote/issue (supported by ANA today) or inbound portfolio
+  sync (no evidence either carrier offers it)? This decides whether the feature
+  is buildable at all.
+- WSDL + credentials for `server.anaseguros.com.mx/ananetws/service.asmx`.
+- Does a cartera/portfolio download exist for an agent's own book?
+- Does GMX daños have any machine interface, or portals only? GMX writes the
+  `MULT`/`INCENDIO`/`M_EMPR` book — the bigger half for this office.
+- Does one Grupo Valore credential span both carriers?
+
+**Resolved — no longer open**
+- ~~Which of `UTILSEG` / `DATGRAL.[NUM UTIL]` is authoritative~~ → `NUM UTIL`;
+  `UTILSEG` is stale and must not be used (see Ground truth).
+- ~~OCR/mail provider and budget~~ → SES, settled before this spec was written.
+- ~~Does "GDMX" mean `GMX`~~ → yes, a typo in the meeting notes (2026-07-27).
+- ~~Do the carriers' APIs exist~~ → ANA: yes, a live SOAP service with a known
+  operation list. GMX: no published machine interface. Both are Grupo Valore,
+  so it is one relationship. See §4.
+
+## Sources (§4 carrier research, 2026-07-27)
+
+- [ANA Seguros web service (`ananetws/service.asmx`)](https://server.anaseguros.com.mx/ananetws/service.asmx)
+- [ANA Seguros — quiénes somos / Grupo Valore](https://anaseguros.com.mx/anaweb/ana_seguros.html)
+- [GMX Seguros — herramientas para agentes](https://www.gmx.com.mx/soy-agente/herramientas/)
+- [GMX quoting micrositio hosted on ANA's server](https://server.anaseguros.com.mx/Micrositios/GRUPOVALOREGMXCOR/cotizador.html)
+- [Agentemotor — how carriers grant web service credentials](https://www.agentemotor.com/blog/noticias-agentemotor/como-integrarte-a-las-aseguradoras-via-web-service-utilizando-agentemotor/)
+  (Colombian market, cited only for the credential-request pattern)

docs/RECEIPT_CAPTURE_SPEC.md

@@ -0,0 +1,912 @@
+# Receipt Capture ("Editor") & Related Net-New Features — Implementation Spec
+
+Source: Jorge Cuadros meeting notes, 2026-07-25/26 (`Utility Management` section)
+plus a business-logic read-through of `UTILITIES.accdb`'s legacy "Editor"
+workflow (`docs/LEGACY_DATABASES_OBJECTS.md`, `docs/LEGACY_DATABASES.md`).
+This is a forward spec for work **not yet built**, not a record of what
+exists — contrast with `RENEWAL_NOTICES.md`, which documents a legacy
+workflow already migrated.
+
+## Why these four features are one spec
+
+The meeting covered one legacy workflow (receipt capture, the "Editor") plus
+three requests that have no legacy precedent at all. They're specified
+together because they compose:
+
+1. **Receipt capture module** — the direct replacement for the legacy
+   "Editor" screens, extending what's already built in `billing/`.
+2. **PDF/OCR auto-capture** — a new intake path that feeds *into* module 1
+   (an OCR-confirmed statement becomes a captured receipt, not a separate
+   ledger).
+3. **Multi-bank chequera** — changes what a captured receipt's check number
+   reconciles against (module 1's check-reconciliation view needs to know
+   *which bank account* a check was drawn on).
+4. **Customer-number recycling** — changes how a customer is created, which
+   is the first step of capturing a receipt for them (module 1's customer
+   picker needs to respect whatever number a recycled customer was assigned).
+
+Each section below is independently buildable and independently useful, but
+1 should land before 2 (2 posts through 1's API), and 4 is fully
+independent of the other three.
+
+---
+
+## 1. Receipt capture module (the "Editor" replacement)
+
+### What's already built (do not re-build)
+
+`apps/api/src/billing/` + `apps/web` `MovementForm.tsx` already provide
+single-movement manual capture: `POST /billing` (`ledger:create`) creates one
+signed `Transaction` row with customer, domain, amount, currency, date,
+concept (`typeId`), period, reference, check number, and message; `POST
+/billing/:id/void` (`ledger:void`) reverses one. This is the direct
+equivalent of the legacy `DATOS AGUA`/`DATOS LUZ`/`DATOS TEL`/`DATOS CLAVE`
+per-service capture screens, already generalized into one form — **the
+per-service screens do not need to be rebuilt separately**; `domain` +
+`typeId` (from `TypeTransaction`) already carry that distinction, and the
+capture form can pre-select a concept when opened from a property's service
+tab.
+
+What's missing is everything the legacy system did *around* that single
+capture: batching many receipts against one check, separating out unpaid
+items, and reconciling a check's total against what was captured against it.
+
+### 1.1 Outstanding ("NOPAGO") workflow
+
+`Transaction.outstanding` already exists in the Prisma schema but nothing
+reads or writes it yet.
+
+- **`CreateMovementDto`** (`billing/movement.dto.ts`): add `outstanding?:
+  boolean`, default `false`. When `true`, the movement posts normally but is
+  excluded from "settled" balance views — mirrors the legacy `SALDOS ULTIMO
+  0` query, which already `HAVING NOPAGO = 0`s outstanding rows out of the
+  balance.
+- **`MovementForm.tsx`**: add an "Outstanding (sin fondos)" checkbox, shown
+  only for `domain = UTILITY` charge-direction rows (this is a per-service
+  charge concept, not a credit/payment concept).
+- **New endpoint** `POST /billing/:id/resolve-outstanding` (`ledger:create` —
+  same tier as capture, since resolving is completing a capture, not
+  reversing one). Body: `{ checkNumber: string, resolvedDate: string }`.
+  Sets `outstanding = false`, `checkNumber`, and updates `transactionDate` to
+  `resolvedDate` — this is the literal legacy behavior ("se actualiza
+  registro con fecha del día y el cheque a pagar y quitas outstanding").
+  Reject (400) if the row is already resolved or voided.
+- **New list filter**: `GET /billing?outstanding=true` (extend
+  `MovementParams`) — replaces the legacy `EDITA NO PAGO AGUA/LUZ/PHONE`
+  per-service outstanding screens with one filterable view (service already
+  filterable via `typeId`).
+- **Web**: an "Outstanding" tab or filter chip on `/estado-cuenta`
+  (Movimientos tab), each row showing a "Resolver" action that opens a small
+  form for check number + date.
+
+### 1.2 Batch capture by check
+
+Legacy staff key many customers' receipts against one check before cutting
+it, then verify the captured total matches the check amount
+(`CAPTURA AGUA`/`CAPTURA LUZ`/etc. feeding into `EDITA CHEQUE COUNT`/
+`REPORTE POR CHEQUE`). Model this as a **bulk-create, not a new persisted
+entity** — a check number is already a plain field on `Transaction`; there's
+no need for a `ReceiptBatch` table when grouping by `checkNumber` already
+answers every legacy query.
+
+- **New endpoint** `POST /billing/batch` (`ledger:create`). Body: `{
+  domain, typeId, transactionDate, currency, checkNumber, lines: [{
+  customerId, amount, reference, period, outstanding? }] }` — the
+  check-level fields are shared, only the per-customer fields repeat. Runs
+  as one Prisma `$transaction`, returns the created rows plus `{ total,
+  count }` so the UI can show the running total against the physical check
+  amount as staff add lines, exactly matching the legacy reconciliation
+  practice.
+- **Web**: a `/estado-cuenta/captura` (or `/estado-cuenta/lote`) page — a
+  service-type + check-number header, then a repeating row (customer picker
+  + reference + amount + outstanding toggle), a running total, and a single
+  submit. This is the actual "Editor" screen the meeting notes are asking
+  for; it should be reachable from a new nav entry under "Estado de cuenta"
+  or "Servicios."
+
+### 1.3 Check reconciliation view
+
+Direct replacement for `EDITA CHEQUE ALF/COUNT/NUM`, `REPORTE POR CHEQUE`,
+`REPORTE POR CHEQUE PARA ALFA`, and the `REPORTE CHEQUE COUNT` report named
+explicitly in the meeting notes.
+
+- **New endpoint** `GET /billing/by-check?checkNumber=...` — all
+  non-voided `Transaction` rows with that `checkNumber`, plus `{ total,
+  count }`. Trivial query, no new indexes needed beyond the existing
+  `checkNumber` column (add a plain index — it's currently unindexed).
+- **New report entry** in `reports.registry.ts`: `slug: "cheque-count"`,
+  `legacyName: "REPORTE CHEQUE COUNT"`, params `{ checkNumber: text }`,
+  columns customer/reference/period/concept/amount, reusing the by-check
+  query above. This gives it a printable form for free via the existing
+  `/reportes/:slug` machinery — no new page needed.
+
+### Abilities
+
+No new abilities required — everything above reuses `ledger:create` /
+`ledger:void` (already `STAFF` / `MANAGER`). Batch capture and outstanding
+resolution are both "capturing a receipt," same trust tier as the existing
+single-movement form.
+
+---
+
+## 2. PDF / OCR auto-capture
+
+> **BUILT — 2026-08-01.** Implemented and verified end to end against real
+> scanned statements. `apps/api/src/statements/` holds the module: a swappable
+> `OcrProvider` seam with a self-hosted Tesseract implementation, per-provider
+> parsers for CFE / CESPT / Telnor, a scoped matcher, and a review queue that
+> posts through `BillingService.createBatch` with `source: "OCR"`. Web:
+> the "Captura automática (OCR)" tab of the Captura screen (upload + batch
+> list) and `/recibos/:id` (review queue with the page image beside the
+> extracted fields). New abilities `statement:ingest` / `statement:review`, both
+> STAFF.
+>
+> Auto-capture is a *mode of* §1.2's capture screen, not a separate menu entry:
+> it is the same daily job with a scanner instead of a keyboard, and both modes
+> post through the same ledger path. `/estado-cuenta/lote` opens the manual tab,
+> `/recibos` the automatic one; both render `components/Captura.tsx`.
+>
+> Requires object storage (`S3_ENDPOINT` + credentials): the scans are kept as
+> blobs. `GET /statements/status` reports `ocrAvailable` and `storageAvailable`,
+> and the upload card hides itself unless both hold.
+>
+> **Measured, not assumed.** Ten real scans (46 pages of CFE, CESPT and Telnor
+> bills) drove every decision below. Against them the shipped parser identifies
+> the provider on **46/46**, reads an account reference on **43/46**, an amount
+> on **42/46**, and a due date on **44/46**. Matched against the dev database
+> that is **39/46 (85%) exact auto-match, 40/46 (87%) identified**. The
+> remainder are legitimate review cases: one account number shared by two
+> services, three phone numbers not yet on file, one clave not in the book, and
+> one page too poorly scanned to read.
+>
+> **The OCR-provider question is closed: self-hosted Tesseract.** It clears the
+> bar for a queue where a human confirms every row, and at 300+ pages/month/
+> company a per-page API would carry real recurring cost for accuracy that is
+> not the bottleneck. `OcrProvider` keeps a managed API (Textract, Document
+> Intelligence, Document AI) a one-line swap in `statements.module.ts` with no
+> schema change.
+>
+> **Four things the samples proved that this spec had wrong or unknown:**
+>
+> 1. **Clave catastral ≠ predial — gap 2 below is resolved.** `DATMEX.clave` is
+>    934 rows of `[A-Z]{2}[0-9]{6}` (`MM000012`, `KH220204`), the exact format
+>    printed as `Cve. Cat.` / `CLAVE CATASTRAL` on real CESPT bills
+>    (`KB078025`, `KA903009`). `DATMEX.predial` — what
+>    `PROPERTY_TAX.accountNumber` actually holds — is 1135 numeric rows with
+>    only **663 distinct values**, so it is not a per-property key at all and
+>    appears on no statement. The clave was never migrated; it now lives on
+>    `Property.cadastralKey` (property-level, because two different services
+>    both print it) and is the matcher's secondary key. Predial is left
+>    untouched. Predial statements match on the clave alone.
+> 2. **Gas is not a dead end — gap 3 below was wrong.** `DATMEX.gas` has 334
+>    filled rows, of which **160 are real numeric account numbers**
+>    (`900004807`); the other 174 are tank descriptors (`ESTACIONARIO`,
+>    `CILINDRO`). All 334 went to `notes`. The 160 are recovered into
+>    `GAS.meterNumber`; only the descriptor rows start cold.
+> 3. **Phone is one line per property, not three.** Of 1518 properties, 534
+>    have `phone1`, 18 have `phone2` and exactly **1** has `phone3`. The
+>    secondaries are alternate contacts, so `TELEPHONE` backfills from `phone1`
+>    only rather than fanning out. This answers the open question below.
+> 4. **Statements arrive bundled, and their printed names are stale.** One PDF
+>    holds many customers, one per page (Telnor's own `Pág 3 de 6` refers to
+>    its internal pagination, not the office's scan). And the name on a utility
+>    bill is the account registrant, not the current owner: a CESPT receipt for
+>    account `5365218` prints `ARNAIZ ROSAS ELSA AURORA` where the office's
+>    book — corroborated by the clave — has `CATT, RANDY`. **The matcher never
+>    reads the name.**
+>
+> **Two OCR traps worth keeping in mind if the parsers are ever extended:**
+> scanned logos read badly (a CESPT header came back as `E BAJA ES PAGO /
+> EALIFORNIA`), so provider detection falls back to layout anchors — but only
+> after *every* brand check has run, since a Telnor page contains words a CFE
+> structural rule would otherwise claim. And amounts must be parsed by
+> separator position: a real Telnor bill OCR'd as `$ 649,00`, which naive
+> comma-stripping turns into $64,900.
+>
+> **Not covered:** handwritten folder numbers. Staff pencil a customer number on
+> each bill (`9`, `405`, `406`); Tesseract read `405` as `205`. Handwriting is
+> a review hint at best and is deliberately not an input to matching.
+
+### Motivation (from the meeting)
+
+Each utility company (CFE, water, phone, gas...) sends 300+ individual
+statements a month, one per customer, currently keyed in by hand through the
+per-service capture screens — a high-volume, error-prone manual step. The
+ask: scan/receive the statements as PDF(s), have the system determine
+customer + amount automatically, and only require staff review rather than
+full manual entry.
+
+### Pipeline
+
+```
+Upload (1+ PDFs, one service kind per batch)
+  -> StorageService stores raw file(s)
+  -> Split into one document per statement (if a batch PDF bundles multiple)
+  -> OCR extraction (account/meter number, amount, period, due date)
+  -> Auto-match against PropertyService (accountNumber / meterNumber / route)
+  -> Review queue: high-confidence matches pre-filled, no-match/low-confidence flagged
+  -> Staff confirms (bulk-confirm high-confidence rows, hand-correct the rest)
+  -> Confirmed rows post through the SAME batch-capture path as §1.2
+  -> Source PDF page attached as a ServiceDocument on the matched property
+```
+
+The last two steps deliberately reuse §1.2's batch-capture endpoint rather
+than writing `Transaction` rows directly — OCR-sourced and hand-keyed
+receipts should go through one write path, one validation path, one audit
+trail.
+
+### Data model (new)
+
+```prisma
+enum StatementBatchStatus {
+  UPLOADED
+  PROCESSING
+  READY_FOR_REVIEW
+  COMPLETED
+  FAILED
+}
+
+enum StatementDocumentStatus {
+  PENDING_OCR
+  OCR_FAILED
+  NEEDS_REVIEW      // no confident match, or low OCR confidence
+  MATCHED           // confident auto-match, awaiting staff confirmation
+  CONFIRMED         // staff confirmed, not yet posted
+  POSTED            // posted as a Transaction
+  REJECTED          // staff rejected (duplicate, unreadable, wrong batch)
+}
+
+// `ServiceKind` needs one addition for this feature: `TELEPHONE`. It
+// doesn't exist today — phone numbers live on `Property.phone1/2/3`, not as
+// `PropertyService` rows. See "Matching logic" below for why OCR matching
+// needs it as a real service kind, and the backfill this implies.
+
+/// One upload session — e.g. "October CFE statements."
+model StatementBatch {
+  id           String                @id @default(uuid())
+  serviceKind  ServiceKind
+  status       StatementBatchStatus  @default(UPLOADED)
+  uploadedById String
+  fileCount    Int
+  createdAt    DateTime              @default(now())
+  documents    StatementDocument[]
+
+  @@map("statement_batches")
+}
+
+/// One statement (one customer, one period) after splitting the batch.
+model StatementDocument {
+  id                  String                    @id @default(uuid())
+  batchId             String
+  batch               StatementBatch            @relation(fields: [batchId], references: [id])
+  storageKey          String
+  status              StatementDocumentStatus   @default(PENDING_OCR)
+
+  // Raw OCR output, kept even after a manual correction so mismatches are
+  // auditable.
+  ocrRawText          String?                   @db.Text
+  ocrConfidence        Decimal?                 @db.Decimal(4, 3)
+
+  // Extracted (and, after review, staff-corrected) fields.
+  extractedAccountRef String?                   // RPU / phone / water account / zona fed / clave catastral / gas meter — see "Matching logic" for which PropertyService field this maps to per serviceKind
+  extractedAmount     Decimal?                  @db.Decimal(12, 2)
+  extractedPeriod     String?
+  extractedDueDate    DateTime?
+
+  // Match result.
+  matchedPropertyServiceId String?
+  matchedPropertyService   PropertyService?      @relation(fields: [matchedPropertyServiceId], references: [id])
+  matchedCustomerId        String?
+  matchedCustomer          Customer?             @relation(fields: [matchedCustomerId], references: [id])
+
+  reviewedById        String?
+  reviewedAt          DateTime?
+  postedTransactionId String?                   @unique
+  postedTransaction   Transaction?              @relation(fields: [postedTransactionId], references: [id])
+
+  createdAt           DateTime                  @default(now())
+
+  @@map("statement_documents")
+}
+```
+
+(`PropertyService`/`Customer`/`Transaction` gain the inverse relations.
+`ServiceDocument` is reused as-is for the confirmed receipt's permanent
+attachment — `StatementDocument.storageKey` and the eventual
+`ServiceDocument.storageKey` may point at the same object, or the confirm
+step copies it; either is fine, pick whichever is simpler at build time.)
+
+### Matching logic
+
+Match `extractedAccountRef` against **one specific `PropertyService` field,
+chosen by `serviceKind`** — never a fuzzy match across all of
+`accountNumber`/`meterNumber`/`route` at once, since that's how a water
+account number could accidentally collide with an unrelated phone number.
+Per the meeting notes' own field list:
+
+| Service (meeting note) | `ServiceKind` | Match against | Legacy source (`DATMEX`) | Status |
+|---|---|---|---|---|
+| CFE — RPU | `ELECTRIC` | `accountNumber` | `RPU` / `RPU2` / `RPU3` | ✅ populated today (`transform_properties.py`) |
+| Agua — Número de cuenta | `WATER` | `accountNumber` | `AGUA` | ✅ populated today |
+| Zona Fed — Número de Zona Federal | `FEDERAL_ZONE` | `accountNumber` | `ZFED` | ✅ populated today |
+| Tel — Número de teléfono | `TELEPHONE` *(new)* | `accountNumber` | `Property.phone1/2/3` (currently on `Property`, not `PropertyService`) | ⚠️ schema gap — see below |
+| Impuesto — Clave Catastral | `PROPERTY_TAX` | `accountNumber` | migrated from `PREDIAL`, **not** `CLAVE` | ⚠️ needs verification — see below |
+| Gas — Número de medidor | `GAS` | `meterNumber` | not populated — folded into free-text `notes` today | ⚠️ data gap — see below |
+
+Confidence rule of thumb once a field is confirmed populated, tune after
+seeing real statements:
+
+- Exact match on the scoped field → `MATCHED`, high confidence, pre-checked
+  for bulk-confirm.
+- No match, or the OCR confidence itself is low → `NEEDS_REVIEW`.
+- Multiple candidate matches (shouldn't happen if account numbers are
+  unique, but the legacy data has had duplication issues before — see
+  `docs/LEGACY_DATABASES_OBJECTS.md`'s `DUPLICADOS` report) → `NEEDS_REVIEW`
+  with all candidates surfaced, not an arbitrary pick.
+
+#### Three gaps this depends on — resolve before building the matcher
+
+Cross-checking the requested field list against `transform_properties.py`
+(the script that actually populated today's `property_services` table)
+surfaced three mismatches. OCR matching is only as good as the field it
+matches against, so these need to be closed first, not discovered mid-build:
+
+1. **No `TELEPHONE` service kind exists.** `ServiceKind` today is `WATER |
+   ELECTRIC | GAS | CABLE | PROPERTY_TAX | FEDERAL_ZONE | ALARM | OTHER` —
+   telephone was never unpivoted into `PropertyService` at all; the three
+   phone numbers live directly on `Property.phone1/phone2/phone3` (raw
+   contact fields, not billable-service rows), even though the legacy
+   ledger clearly bills phone as its own `TYPE OF TRX = "TELEPHONE"` (see
+   `EDITA NO PAGO PHONE`, `DATOS TEL`/`CAPTURA TEL` in the prior analysis).
+   **Fix:** add `TELEPHONE` to the `ServiceKind` enum, and backfill one
+   `PropertyService` row per non-null `Property.phone1/2/3` (`kind:
+   TELEPHONE, accountNumber: <the phone number>`) as a one-time migration
+   script companion to this feature — mirrors how `transform_properties.py`
+   already emits multiple `WATER` rows per property for secondary meters.
+
+2. **`PROPERTY_TAX.accountNumber` holds `PREDIAL`, not `CLAVE`.** The
+   meeting notes name "Clave Catastral" specifically, and the legacy
+   query/report names agree (`CAPTURA CLAVE`, `DATOS CLAVE`, `CLAVES
+   CATASTRALES`, `CATASTRO` — all filter on `DATMEX.CLAVE`). But
+   `transform_properties.py` line ~191 sets `PROPERTY_TAX.accountNumber =
+   DATMEX.PREDIAL`, a *different* column (`DATMEX` has both `CLAVE`
+   VARCHAR and `PREDIAL` DOUBLE). Two live possibilities: either `PREDIAL`
+   is the wrong field and the migration should have used `CLAVE`, or they're
+   two genuinely different numbers (e.g. clave catastral = the cadastral
+   lookup key stamped on the printed bill vs. predial = an internal
+   receipt/folio number) and `PropertyService` needs *both* — only one of
+   which (the clave catastral) is what OCR will actually read off a real
+   predial statement. **Needs a real predial receipt in hand (or Jorge's
+   confirmation) before deciding**; don't wire the matcher to `PREDIAL` on
+   the untested assumption it's the same thing.
+
+3. **`GAS.meterNumber` is never populated.** `transform_properties.py`
+   only ever sets `notes = DATMEX.GAS` for gas service rows — there's no
+   distinct meter-number column in the legacy `DATMEX` table for gas at
+   all (unlike electric/water, which have `RPU`/`MEDIDOR`). This matches
+   the earlier finding that "Gas – Número de medidor" has no legacy source
+   field. **This can't be backfilled from existing data** — the practical
+   fix is that gas OCR matching starts cold (every gas statement lands in
+   `NEEDS_REVIEW` until a human confirms it once), and *that first
+   confirmation* is what populates `PropertyService.meterNumber` for that
+   property going forward, so subsequent statements for the same meter
+   auto-match. Worth calling out in the review-queue UI ("first time
+   seeing this meter — confirm to enable auto-match next time").
+
+### OCR provider — open decision, don't build against one prematurely
+
+CFE (and most MX utility) bills are **fixed-layout, single-language,
+high-volume forms**, not arbitrary documents — this is closer to
+"template/anchor text extraction" (regex against OCR'd text for known
+labels like `RPU`, `No. de Cuenta`, `Total a pagar`) than to a full ML
+document-understanding problem. Recommend:
+
+- Define an `OcrProvider` interface (`extract(buffer, hints): Promise<{
+  text: string, fields: ExtractedFields, confidence: number }>`) so the
+  concrete engine is swappable.
+- Start with a self-hosted OCR (e.g. Tesseract) + hand-written per-company
+  extraction rules (one rule set per `ServiceKind`/provider, since CFE's
+  layout differs from the water company's). Cheap, no per-page cost, and the
+  layouts are stable enough that this is realistic.
+- Escalate to a managed document-extraction API (AWS Textract, Azure
+  Document Intelligence, Google Document AI) only if the self-hosted
+  accuracy proves too low in practice — all three fit behind the same
+  interface with no schema changes.
+- **This choice needs Jorge's input on budget/volume before committing** —
+  300+ pages/month/company is enough volume that a per-page-priced API has a
+  real recurring cost.
+
+### API surface
+
+- `POST /statements/batches` (`statement:ingest`) — multipart upload, one or
+  more PDFs + `serviceKind`. Creates the batch, kicks off async
+  split+OCR+match (background job, not inline in the request).
+- `GET /statements/batches` / `GET /statements/batches/:id` — status +
+  document list.
+- `GET /statements/batches/:id/documents?status=NEEDS_REVIEW` — the review
+  queue.
+- `PATCH /statements/documents/:id` (`statement:review`) — staff correction
+  of extracted fields or match.
+- `POST /statements/documents/:id/confirm` (`statement:review`) — single
+  confirm.
+- `POST /statements/batches/:id/confirm-matched` (`statement:review`) —
+  bulk-confirm every `MATCHED` document in one call.
+- `POST /statements/documents/:id/reject` (`statement:review`).
+- Confirming posts through §1.2's batch-capture internals (same service
+  method, not the HTTP endpoint) so it's one transaction per batch of
+  confirms, not N.
+- **Confirm also backfills the matched field when it was empty** — if
+  `matchedPropertyServiceId` was set by staff (not by an exact auto-match)
+  because the scoped field was blank on that `PropertyService` (the `GAS`
+  case above, and any one-off historical gap in the other kinds), write
+  `extractedAccountRef` into that service's `accountNumber`/`meterNumber`
+  as part of the confirm transaction. This is what makes the "first
+  confirmation teaches the matcher" behavior in gap 3 above actually work,
+  rather than requiring a separate manual data-entry pass.
+
+### Abilities (new)
+
+| Ability | Min role | Notes |
+|---|---|---|
+| `statement:ingest` | STAFF | upload a batch |
+| `statement:review` | STAFF | correct/confirm/reject; same tier as `ledger:create` since confirming *is* capturing |
+
+### Open questions
+
+- **Clave catastral vs. predial** (gap 2 above) — get a real predial
+  statement or Jorge's confirmation of whether `CLAVE` and `PREDIAL` are the
+  same number before wiring the `PROPERTY_TAX` matcher. Blocks that one
+  service kind, not the whole feature.
+- **Telephone as a service kind** (gap 1 above) — confirm the backfill
+  approach (one `PropertyService` row per populated `Property.phone1/2/3`)
+  is correct, and whether a property with all three phones populated should
+  really produce three separate billable "services," or whether phone
+  billing is actually 1-per-property regardless of how many numbers are on
+  file (would change the backfill to pick a primary number instead of
+  fanning out to three rows).
+- Multi-statement PDF splitting: does the source ever arrive as one PDF per
+  customer already (simplifies to "batch = folder of PDFs"), or as one
+  giant PDF per company per month that needs page-range splitting? Changes
+  whether a page-boundary detector is needed at all.
+- Retention: keep `StatementDocument.storageKey` (and the raw OCR text)
+  indefinitely for audit, or purge after posting since `ServiceDocument`
+  already holds the permanent copy? Recommend keep — cheap, and it's the
+  audit trail for "why did the system think this was customer X."
+
+---
+
+## 3. Multi-bank chequera
+
+> **BUILT — 2026-07-27.** Everything below is implemented and verified against
+> the dev database and browser. `Bank` / `BankAccount` exist, every
+> `BankTransaction` carries a required `bankAccountId`, and all 22,669 migrated
+> rows were backfilled onto the Utilities/Scotiabank MXN account by
+> `migration/backfill_bank_accounts.py` (now wired into `run_all.py`, both
+> modes, ahead of `transform_bank.py`). Every read path in `bank.service.ts` is
+> account-scoped — including both raw-SQL rollups in `summary()` and the
+> previously-unfiltered `facets()`. `/banco` gained an account picker,
+> `/banco/cuentas` manages banks and accounts under the new MANAGER
+> `bank:manage-accounts` ability, and `/inicio`'s chequera card now names the
+> account it is reading rather than implying a single register.
+>
+> **Verified end to end:** a second account (USD) was created through the API,
+> a movement captured into it, and the MXN register's totals confirmed
+> unchanged (22,669 movements, net 1,014,266.97) with zero cross-account leak
+> in list/stats/facets/summary. Missing `bankAccountId` returns 400, unknown
+> returns 404, capture into a closed account returns 400, and an attempt to
+> PATCH an account's `currency` is rejected by DTO whitelisting. The test
+> account was then deleted — the real Seguros bank is still the open question
+> below, so nothing was left behind guessing at it.
+>
+> **Two deviations from the design below**, both tightening it:
+> - `bank_transactions` also gained an `@@index([bankAccountId, transactionDate])`.
+>   Every read is now filtered by account and ordered/grouped by date; without
+>   it each of them is a full scan of the 22k-row table.
+> - `UpdateBankAccountDto` deliberately has **no `currency` field**. The
+>   movements already booked in an account are denominated in it, so editing it
+>   would silently re-denominate history instead of converting it. Currency is
+>   set once, at creation.
+>
+> Still open: which bank the Seguros USD account is actually at (see Open
+> questions). Until that answer arrives the office has exactly one chequera and
+> the UI behaves as it always did, just scoped explicitly.
+
+### Motivation
+
+Seguros uses a US bank account; Utilities uses a Mexican bank account. The
+current `BankTransaction` model (migrated from `SCOTHIA.mdb`) has no bank or
+currency dimension at all — it's a single implicit account, MXN-only, by
+design (see `PLAN.md` migration step 7 finding (c)). Need to support more
+than one register, each with its own bank and currency.
+
+Confirmed against the actual code, not just the schema comment: this is a
+real, deliberate, load-bearing assumption, not an oversight to patch around.
+`migration/transform_bank.py` has no bank/currency column to read in the
+first place — `DATOS I`/`DATOS E` are `fecha, tipo, num, concepto,
+ingreso/egreso, operado, notas, cantidad_en_letra`, nothing else. And
+`bank.service.ts`'s module doc-comment states outright: "SINGLE CURRENCY...
+`bank_transactions` has none, and every `amountInWords` on the egreso side
+is spelled out in PESOS. All figures in this module are MXN." Every method
+in that file — `where()`, `totalsFor()`, `facets()`, `summary()`, `stats()`,
+`createMovement()` — currently has zero notion of "which account." That's
+the actual surface area this feature touches, itemized below.
+
+### Data model changes
+
+```prisma
+model Bank {
+  id       String        @id @default(uuid())
+  name     String        @unique   // e.g. "Scotiabank", "Bank of America"
+  country  String?                 // "MX" | "US" — informational
+  accounts BankAccount[]
+
+  @@map("banks")
+}
+
+/// One physical chequera. Currency is fixed per account (real bank
+/// accounts don't mix currencies) — do NOT add a currency filter to
+/// BankTransaction itself; it inherits the account's currency.
+model BankAccount {
+  id           String            @id @default(uuid())
+  bankId       String
+  bank         Bank              @relation(fields: [bankId], references: [id])
+  label        String            // "Utilities operating (MXN)", "Seguros operating (USD)"
+  currency     Currency
+  businessLine TransactionDomain? // hint only, not enforced — a chequera can pay for more than one line
+  active       Boolean           @default(true)
+  movements    BankTransaction[]
+
+  @@map("bank_accounts")
+}
+```
+
+`BankTransaction` gains:
+
+```prisma
+model BankTransaction {
+  // ...existing fields...
+  bankAccountId String
+  bankAccount   BankAccount @relation(fields: [bankAccountId], references: [id])
+}
+```
+
+`bankAccountId` should be **required**, not optional — a bank movement
+without a known account isn't meaningfully reconcilable. This means the
+migration step below has to run before the column goes non-null.
+
+### Migration of existing data
+
+All 22,354 existing `BankTransaction` rows are SCOTHIA data — MXN, single
+bank. Before making `bankAccountId` required:
+
+1. Insert one `Bank` row for Scotiabank, one `BankAccount` row under it
+   (`label: "Utilities — Scotiabank (MXN)"`, `currency: MXN`,
+   `businessLine: UTILITY`).
+2. Backfill every existing `BankTransaction.bankAccountId` to that account's
+   id.
+3. Add the second account (`"Seguros — <bank TBD> (USD)"`) — **needs the
+   actual US bank name from Jorge**, plus whether historical Seguros bank
+   data exists anywhere to migrate (the current inventory has no Seguros
+   bank register file — only `SCOTHIA.mdb`, which is Utilities' own book,
+   per `PLAN.md`'s source inventory). If no historical USD register exists,
+   this account starts empty and only carries movements captured going
+   forward.
+
+The existing `@@unique([legacySourceTable, legacyId])` on `BankTransaction`
+needs no change — every legacy row only ever belongs to the one Scotiabank
+account being backfilled in step 2, so provenance uniqueness still holds
+per-row regardless of how many accounts exist afterward.
+
+### Code touch points (`bank.service.ts`, `bank.controller.ts`)
+
+This module currently has **no filterable dimension at all** beyond
+direction/cleared/date — every account-scoping change is additive, not a
+rewrite, but it touches every read method because two of them
+(`facets()`, `summary()`) bypass the Prisma query builder entirely and use
+hand-written `$queryRaw` template SQL:
+
+- **`where()`** — trivial, add `bankAccountId` to the `AND` array like any
+  other filter (Prisma builder, same pattern as `direction`/`cleared`).
+- **`totalsFor()`** — takes the already-built `where`, so it inherits the
+  scoping for free once `list()`/`stats()` pass a scoped `where` in.
+- **`facets()`** — currently `SELECT YEAR(transactionDate)... FROM
+  bank_transactions WHERE voidedAt IS NULL` with no account clause at all;
+  needs `AND bankAccountId = ${accountId}` interpolated into the raw SQL
+  (parameterized, not string-concatenated — this file already uses Prisma's
+  tagged-template `$queryRaw`, which parameterizes automatically as long as
+  the account id is passed as a template value, not spliced into the string
+  by hand).
+- **`summary()`** — same issue, in *two* raw queries (the yearly rollup and
+  the monthly rollup when a year is selected) — both need the same
+  `AND bankAccountId = ${accountId}` clause. Miss one and the "Resumen"
+  tab's year list and its drill-down would scope to different accounts,
+  which is a worse bug than not scoping at all (looks correct, silently
+  wrong).
+- **`stats()`** — currently calls `totalsFor({})` (empty filter = every
+  row). Needs `totalsFor({ bankAccountId })`; same for the `count`/`bounds`/
+  `pending`/`transferred` aggregates alongside it.
+- **`createMovement()` / `voidMovement()`** — `createMovement` needs
+  `bankAccountId` added to the `data` object (from the new required DTO
+  field below); `voidMovement` needs no change — it already operates by row
+  `id`, and a voided row's account never changes.
+
+### API surface changes
+
+- `bank.controller.ts`: every route (`list`, `summary`, `stats`, `facets`)
+  gains a required `?bankAccountId=` query param, threaded through to the
+  service methods above. **Required, not optional with an "all accounts"
+  default** — summing MXN and USD registers together would repeat the exact
+  currency-collapsing mistake the billing module's header comment
+  explicitly warns against (912 customers with both-currency ledgers).
+  There is no meaningful "no account selected" state once accounts exist,
+  only "no account selected *yet*" while the UI loads its default.
+- New `bank/accounts` sub-resource: `GET /bank/accounts` (list, any
+  authenticated user — the account picker needs this before anything else
+  can render), `POST /bank/accounts` / `PATCH /bank/accounts/:id`
+  (`bank:manage-accounts`, MANAGER — creating/editing accounts is rarer and
+  higher-stakes than posting movements).
+- `CreateBankMovementDto` gains a required `bankAccountId: string`.
+
+### Web
+
+- `bank/page.tsx`'s own doc-comment currently states "Single currency
+  (MXN) — the source has no currency column" as a design fact; that
+  comment (and the assumption behind it) needs to be removed/rewritten as
+  part of this change, not just the UI.
+- `/banco` gains an account selector (tabs or a dropdown) at the top,
+  scoping both the "Movimientos" and "Resumen por periodo" tabs — mirrors
+  how `/estado-cuenta` already scopes by currency without ever summing
+  across it. Every existing call site in `lib/api.ts`
+  (`listBankMovements`, `getBankStats`, `getBankSummary`, `getBankFacets`,
+  `createBankMovement`) needs the new `bankAccountId` parameter threaded
+  through, and `lib/types.ts`'s `CreateBankMovementInput` gains the field.
+- New `/banco/cuentas` (or a section under `/catalogos`) for managing banks
+  and accounts, gated the same way `/catalogos` already gates lookup
+  management.
+
+### Abilities (new)
+
+| Ability | Min role | Notes |
+|---|---|---|
+| `bank:manage-accounts` | MANAGER | create/edit `Bank`/`BankAccount` rows |
+
+### Open questions
+
+- Confirm the actual US bank name/details for the Seguros account.
+- Does Seguros have *any* historical bank register data to migrate, or does
+  this start from zero on cutover?
+- Should `businessLine` on `BankAccount` be enforced (a UTILITY account
+  can't post an INSURANCE movement) or left as a soft hint? Recommend soft —
+  the legacy single account already mixed concerns per `PLAN.md`'s finding
+  that `TABLA RAMODOS` wasn't a clean business-line split.
+
+---
+
+## 4. Customer-number recycling
+
+### Motivation
+
+The physical folder system is organized by `Customer` number
+(`DATGRAL.[NUM id]` in the legacy data, currently only preserved as a
+`CustomerLegacyRef` string, not a first-class field). When a customer
+cancels, doesn't renew, or goes a year with no activity, staff currently
+*manually* hunt for such customers, purge their folder, and reuse the
+number for a new customer. The ask: keep the physical-folder-compatible
+sequential numbering, but automate the search for reusable numbers and
+auto-assign the lowest free one at creation — a Claude Code equivalent of
+"find the first empty spot."
+
+### Data model changes
+
+```prisma
+model Customer {
+  // ...existing fields...
+  customerNumber   Int?      @unique   // the physical-folder number; null = not yet assigned (shouldn't happen post-migration) or released
+  numberReleasedAt DateTime?           // non-null once the number has been freed for reuse; customerNumber is cleared at the same time (see below)
+}
+
+enum NumberReleaseReason {
+  CANCELLED       // explicit non-renewal / service cancellation
+  INACTIVITY      // >= 1 year with no ledger activity
+  MANUAL
+}
+
+/// Audit trail for a recycled number, surviving the Customer row it came
+/// from being archived/purged. customerId is nullable so history remains
+/// readable even if the originating customer is later hard-deleted.
+model CustomerNumberHistory {
+  id             String               @id @default(uuid())
+  customerNumber Int
+  customerId     String?
+  customer       Customer?            @relation(fields: [customerId], references: [id])
+  assignedAt     DateTime
+  releasedAt     DateTime?
+  releaseReason  NumberReleaseReason?
+  releasedById   String?
+
+  @@index([customerNumber])
+  @@map("customer_number_history")
+}
+```
+
+### Backfill
+
+At implementation time, backfill `customerNumber` from the existing
+`CustomerLegacyRef` rows where `sourceSystem = "utilities" AND sourceTable =
+"DATGRAL"` (the legacy `NUM id` — already migrated, just not promoted to a
+first-class column). Insurance-only customers (no utilities `DATGRAL` row)
+won't have a legacy number; decide at build time whether they get one
+retroactively assigned or stay `null` until they need one (recommend: assign
+one on demand, the first time anyone needs to give them a physical folder —
+not retroactively for all 510 insurance-only customers at once).
+
+**This backfill isn't a straight cast of every `legacyId` to `Int`.**
+Checked against `migration/transform_customers.py`: for a utilities
+`DATGRAL` row, `legacyId` is set to `nid or f"rownum_{len(customers)}"` —
+`nid` is the real `NUM id` only when the source row actually had one;
+**~140 utilities rows had a blank `NUM id`** (the same "blank name" data
+quality issue the same script recovers names for) and got a synthetic
+`rownum_N` placeholder instead, which is not a physical-folder number and
+must not be cast into `customerNumber`. Insurance-side refs have the same
+pattern (`insrow_N` placeholders). The backfill query needs an explicit
+numeric filter (`legacyId REGEXP '^[0-9]+$'`, or equivalent), and every row
+that fails it is exactly the "insurance-only or blank-`NUM id`" case that
+falls through to on-demand assignment above, not an error to chase down.
+
+`customers.service.ts`'s `list()`/`detail()` `select` blocks don't include
+`customerNumber` today (only `name`, `nameSource`, contact fields, counts)
+— it needs adding to both, plus to the `/clientes` list-page columns and
+the customer detail header, since staff read this number constantly for
+the physical folder. `list()`'s search (`where.OR`) already matches
+`legacyRefs.some.legacyId.contains` as a fallback for finding someone by
+their old number; once `customerNumber` is first-class, add a direct
+`{ customerNumber: Number(query) }` branch when the query parses as an
+integer, so a numeric search hits the fast indexed column instead of the
+join.
+
+### Eligibility detection (the automation)
+
+This is explicitly framed as **surfacing candidates for staff review, not
+auto-purging** — the actual release/reuse decision stays a human action,
+matching how the office works today; only the *search* is automated.
+
+- **New endpoint** `GET /customers/recycling-candidates` — customers where
+  either:
+  - `CANCELLED`: no active `Policy` (not archived, `policyTo` in the past
+    with no renewal) **and** no active `PropertyService`, or
+  - `INACTIVITY`: `MAX(Transaction.transactionDate)` across all their
+    transactions is more than 1 year ago (or no transactions at all and
+    `customerSince` is more than 1 year ago).
+  
+  This can be a plain query (no new job/queue needed — it's a read, not a
+  mutation) run on-demand when staff open a "Clientes para reciclar" screen,
+  the same way `/billing/balances` is computed live rather than
+  materialized.
+- **New endpoint** `POST /customers/:id/release-number`
+  (`customer:recycle`, MANAGER). Body: `{ reason: NumberReleaseReason }`.
+  - Closes the open `CustomerNumberHistory` row (`releasedAt = now,
+    releaseReason, releasedById`).
+  - Sets `Customer.customerNumber = null`, `numberReleasedAt = now`.
+  - **Archives** the customer (`archivedAt = now`) — does **not** hard-delete
+    or scrub PII by default. See the purge question below.
+
+### Auto-assignment at creation
+
+- **`customers.service.ts` create path**: before insert, compute
+  `SELECT MIN(n) candidate FROM (SELECT customerNumber+1 AS n FROM
+  customers) WHERE n NOT IN (SELECT customerNumber FROM customers WHERE
+  customerNumber IS NOT NULL)` — i.e., the lowest positive integer not
+  currently held by any customer (released numbers, being `NULL` again,
+  automatically qualify; no separate "available pool" table needed, which
+  keeps this consistent with "vacancy = not currently claimed" rather than
+  a second source of truth that can drift). Simplify at build time with
+  whatever the DB makes cheapest (a gaps-and-islands query, or maintaining a
+  running `MAX` + a small released-numbers cache — pick based on real
+  customer-count scale, which is ~1,700, trivially small for a live scan).
+  Open a new `CustomerNumberHistory` row (`assignedAt = now`) for the new
+  assignment.
+- **Concurrency**: `customers.service.ts`'s `create()` today is a single
+  unguarded `prisma.customer.create()` — no transaction, no locking, which
+  is fine for arbitrary fields but not for a "pick the lowest unclaimed
+  integer" computation, where two staff creating a customer at the same
+  moment can both compute the same candidate number before either insert
+  lands. The `customerNumber` unique constraint turns that race into a
+  Prisma unique-violation error rather than silent data corruption, but the
+  create path needs to actually handle it — wrap the compute-and-insert in
+  a `prisma.$transaction` and retry once on a unique-constraint failure
+  (catch `P2002` on `customerNumber`, recompute, re-insert), rather than
+  letting the second staff member's creation just fail.
+- **Web**: `/clientes/nuevo` (`CustomerForm.tsx`) shows the assigned number
+  as soon as the form loads (read-only, "Número de cliente: 214
+  (reciclado)" if it's a reused slot, so staff know to expect the old
+  physical folder) — server-assigns it on submit, doesn't let staff type an
+  arbitrary one, which is what prevents the collisions manual assignment
+  risks today. `CreateCustomerDto` deliberately gains **no** `customerNumber`
+  field — the whole point is the client can't set it.
+
+### The purge question — needs Jorge's decision
+
+The office's paper-world habit is literally "purge their history, info,
+etc." when recycling a folder. This codebase's established convention is
+the opposite — **never hard-delete migrated/business data**, only archive
+(`archivedAt`), specifically so mistakes are reversible and there's always
+an audit trail (see `Customer.archivedAt`, `Policy.archivedAt`,
+`Property.archivedAt`, and the `OpsJob`/`ActivityLog` audit models already
+in the schema).
+
+Recommend: **archive by default, never hard-delete.** The `customerNumber`
+release already solves the actual operational need (the number is free to
+reuse); keeping the old customer's data around under a freed number costs
+nothing and preserves history for the inevitable case where "definitely
+cancelled" turns out to be wrong. If Jorge specifically wants literal
+data purge (e.g. for a data-retention/privacy policy reason, not just
+paper-world habit), that should be a **separate, explicit, `ADMIN`-only**
+action (`customer:purge`) taken well after release — not bundled into
+`release-number` — so the two decisions ("this number is reusable" vs.
+"permanently destroy this person's records") aren't accidentally coupled.
+
+### Abilities (new)
+
+| Ability | Min role | Notes |
+|---|---|---|
+| `customer:recycle` | MANAGER | flag a candidate reviewed, release their number, archive the record |
+| `customer:purge` | ADMIN | **only if** Jorge wants literal PII destruction, kept separate from release |
+
+### Open questions
+
+- Confirm the "1 year of no activity" clock: measured from last
+  `Transaction.transactionDate`, or should a customer with an *expired but
+  never-renewed* policy count as cancelled immediately rather than waiting
+  out the year? (Spec above treats these as two independent triggers,
+  `CANCELLED` vs. `INACTIVITY` — confirm that's the right split.)
+- Does Jorge want true data purge at all, or is archive-and-hide
+  sufficient? (See above — recommend archive-only unless there's a
+  compliance reason for real deletion.)
+- Should insurance-only customers (no legacy `NUM id`) share the same
+  numbering sequence as utilities customers, or get their own? Recommend
+  one shared sequence — it's one physical-folder system per the notes, not
+  two.
+
+---
+
+## Build sequencing
+
+1. **§1.1 + §1.2 + §1.3 (receipt capture completion)** — smallest, builds
+   directly on existing `billing/` code, no new tables. Ship first; it's
+   also a prerequisite for §2.
+2. **§4 (customer-number recycling)** — independent of the others,
+   touches `customers/` only. Can be built in parallel with §1.
+3. **§3 (multi-bank chequera)** — independent of §1/§2, touches `bank/`
+   only. Needs the US bank name from Jorge before the migration step can
+   run; the schema/API work can start before that answer arrives.
+4. **§2 (PDF/OCR auto-capture)** — largest, depends on §1 being done (it
+   posts through the batch-capture path) and on the OCR-provider decision.
+   Build last, and prototype the extraction accuracy against a handful of
+   real CFE statements before committing to the provider choice.
+
+## Open questions to take back to Jorge (collected)
+
+- ~~OCR provider/budget for §2~~ — **CLOSED**: self-hosted Tesseract, chosen on
+  measured accuracy against real scans (see §2's BUILT note). No per-page cost.
+- ~~Whether source PDFs arrive pre-split per customer or bundled~~ —
+  **CLOSED**: bundled, one customer per page. Split per page.
+- ~~Whether "Clave Catastral" and the `PREDIAL`-sourced
+  `PROPERTY_TAX.accountNumber` are the same number~~ — **CLOSED**: they are
+  different. `clave` is the cadastral key and is now on
+  `Property.cadastralKey`; `predial` is not unique and is not printed on
+  statements.
+- ~~Whether phone billing is one service per number or one per property~~ —
+  **CLOSED**: effectively one (534 / 18 / 1 across phone1/2/3), backfilled
+  from `phone1`.
+- **Still open (§2):** whether the CFE amount staff should owe is the rounded
+  headline (`$268`, what the barcode encodes and what is paid at the window) or
+  the exact `Total` in the breakdown (`$268.88`). The parser currently takes
+  the barcode figure, which matches what the office actually pays; worth one
+  confirmation from Jorge.
+- The actual bank name/currency/details for the Seguros USD account, and
+  whether any historical Seguros bank data exists to migrate (§3).
+- Whether `BankAccount.businessLine` should be enforced or a soft hint
+  (§3).
+- The exact "1 year inactivity" / "cancelled" recycling triggers (§4).
+- Whether customer-number recycling should ever include *true* data purge,
+  or archive-and-reuse-the-number is sufficient (§4).

docs/RENEWAL_NOTICES.md

@@ -0,0 +1,139 @@
+# Insurance Renewal Notices ("Atlas" reports)
+
+Staff refer to this report in the UI as "the Atlas report", but **Atlas
+isn't a report — it's a carrier**: `ATLAS, S.A.` is one of the insurance
+companies (`COMP` column) SEGUROS brokers policies for, alongside
+`QUALITAS, S.A.` and others. The legacy frontend (`SEGUROS 16.mdb`) never
+parameterized carrier or coverage tier in its renewal-notice report — it
+cloned the entire report + query chain once per carrier per coverage
+variant instead. This doc explains that clone pattern and the underlying
+workflow so the new platform can replace ~40 cloned Access objects with
+one parameterized feature.
+
+## Why this needed extra tooling
+
+`objects.json`/`LEGACY_DATABASES_OBJECTS.md` (see `migration/catalog_objects.py`)
+only capture report *names* — DAO's catalog interface doesn't expose a
+report's `RecordSource` or control layout, only the full Access object
+model does, and that model refused to load here
+(`"The Visual Basic for Applications project in the database is corrupt"`,
+a common failure mode for old .mdb files opened in a newer Access build).
+
+The workaround: `Application.SaveAsText(acReport, name, path)` exports a
+report's complete design as plain text without touching the VBA project.
+The raw (binary-blob-stripped) exports for the ATLAS renewal reports are
+committed in [`migration/legacy_report_defs/`](../migration/legacy_report_defs/):
+
+- `AMPL_R_RENEW_X_MES_NEW_ATLAS_13.txt` — Auto/Amplia (full coverage)
+- `AMPL_RENEW_X_MES_NEW_ATLAS_2013.txt` — Auto/Amplia, alternate batch
+- `RC_RENEW_X_MES_NEW_ATLAS_13.txt` — Auto/RC (liability only)
+- `RCR_RENEW_X_MES_NEWATLAS_2013.txt` — Auto/RC, renewal-of-renewal variant
+- `LIC_RENEW_X_VENCE_ATLAS_2013.txt` — Driver's-license insurance
+
+(`PrtDevMode`/`PrtMip`/`OleData`/`GUID` binary properties — printer
+settings and object GUIDs, no business meaning — were stripped so the
+files are readable text instead of multi-hundred-KB hex dumps.)
+
+## The report chain
+
+Each report is bound to a query that layers 2–3 other queries, filtered to
+one carrier, with two typed parameters staff fill in every run:
+
+```
+Report: AMPL R RENEW X MES NEW ATLAS 13
+  RecordSource -> Query: AMPL R RENEW CALC ATLAS 13
+    FROM [AMPL R CALC VIG], [AMPL R MENS]     (in-force calc view + installment schedule)
+    WHERE COMP = "ATLAS, S.A."
+      AND DatePart("m",[HASTA]) = [TECLEE MES DE VENCIMIENTO (1 A 12)]   -- typed param
+      AND DatePart("yyyy",[HASTA]) = [TECLEE AÑO DE VENCIMIENTO (1999)]  -- typed param
+```
+
+```
+Report: LIC RENEW X VENCE ATLAS 2013
+  RecordSource -> Query of the SAME NAME (query and report share a name)
+    FROM [LIC MENS], LIC INNER JOIN DATGRAL ... INNER JOIN [VIGENT CASA] ...
+    WHERE DatePart("m",[hasta]) = [TECLEE MES DE VENCIMIENTO 1 A 12]
+      AND DatePart("yyyy",[hasta]) = [TECLE AÑO VENCIMIENTO (1999)]
+      AND LIC.COMP = "ATLAS, S.A."
+```
+
+Staff pick a line of business, type the expiry month + year, and the
+report prints one notice per matching policy for that carrier that month.
+On screen the report is captioned **"AVISO DE RENOVACION"** (auto lines)
+or **"R E N E W A L   N O T I C E"** (license-insurance line). Every page
+prints the notice **twice** (identical top-half/bottom-half sections) —
+one copy to mail, one for the office file.
+
+## The multi-notice (reminder) workflow
+
+Renewal reminders escalate through **three generations**, each its own
+report clone, with a matching `CONTROL ...` companion report (a
+send/checklist log):
+
+| Generation | Report suffix | Control/log report |
+|---|---|---|
+| 1st notice | `RENEW` / (bare) | `CONTROL <LOB> RENEW X MES` |
+| 2nd notice | `RENEW2` | `CONTROL <LOB> RENEW2 X MES` (or `X MES` sibling) |
+| 3rd notice | `RENEW3` | `CONTROL <LOB> RENEW3 X MES` |
+
+This pattern repeats per line of business: `AMPL`/`AMPL R` (auto full
+coverage), `RC`/`RC R` (auto liability), `LIC` (driver's license), `RCR`,
+`MF`/`MF2`/`MF3` (home/multi-risk), `MCA2`, `ME`, `INCEN` (fire) — none of
+it is visible from the table schema alone, only from the report/query
+names (see `docs/LEGACY_DATABASES_OBJECTS.md`, "What the Reports actually
+reveal").
+
+## What's hardcoded vs. what's real policy data
+
+The extracted designs show the letter body mixes two very different kinds
+of content:
+
+1. **Per-policy data**, pulled live from the query: customer id, policy
+   number, vehicle (make/model/body/engine), expiry date.
+2. **Static label text baked into the report design**, re-typed by hand
+   every time a batch was cloned for a new rate or carrier — e.g. (from
+   `AMPL_R_RENEW_X_MES_NEW_ATLAS_13.txt`):
+   - `"COLLISION DEDUCTIBLE $ 500.00 Dls.  THEFT DEDUCTIBLE $ 1000.00 Dls. ..."`
+   - `"New Renewal annual Premium $ 365.25 Dls."`
+   - `"Total Annual Premium $ 405.25 Dls"`
+   - the whole CSL/medical-coverage recommendation and rental-car upsell
+     paragraphs
+
+None of those dollar figures are formulas — they're literal text, which is
+*why* there are so many near-duplicate reports: a new coverage tier or
+rate meant cloning the whole report and hand-editing the labels, rather
+than changing a parameter.
+
+The underlying **data these figures should come from already exists** on
+the source tables and is preserved (unmapped-but-captured) in
+`Policy.coveragesJson` after migration — confirmed against
+`docs/LEGACY_DATABASES.md`'s table appendix:
+
+| Legacy column | Sanitized `coveragesJson` key | Meaning |
+|---|---|---|
+| `COBERTURA` | `cobertura` | Coverage days/territory tier (30/40/50/365) |
+| `CSL LIMITE` | `csl_limite` | Combined single limit (liability) |
+| `GASTOS MEDICO` | `gastos_medico` | Medical coverage amount |
+| `SERVICIO ADICIONAL` | `servicio_adicional` (LICENCIAS: `servicio_adiconal`, a source typo) | Add-on service flag |
+| `PROPIEDADES` | `propiedades` | Property-damage coverage amount |
+| `PERSONAS` | `personas` | Per-person liability amount |
+
+(`Policy.netPremium`/`total`/`currency` are already first-class columns —
+see `packages/database/prisma/schema.prisma`.)
+
+**Migration implication:** a rebuilt renewal notice should render these
+from data (one parameterized template), not from report design text. See
+`RenewalNotice` in `schema.prisma` and the `aviso-renovacion` entry in
+`apps/api/src/reports/reports.registry.ts` for the first cut at this.
+
+## Caveats
+
+- Only the ATLAS variants were extracted verbatim; the QUALITAS and
+  "generic" (no-carrier-suffix) clones weren't pulled but are presumed
+  structurally identical modulo the `COMP` filter and hardcoded figures.
+- `coveragesJson` key names above are derived from
+  `migration/extract.py`'s `sanitize_column_name` (lowercase,
+  non-alphanumeric → `_`) applied to the *source* column names in
+  `docs/LEGACY_DATABASES.md`, not verified against a live migrated
+  database (no staged output was present in this environment). Confirm
+  against real data before wiring a template to these keys.

migration/backfill_bank_accounts.py

@@ -0,0 +1,192 @@
+"""
+One-off schema+data step for the multi-bank chequera
+(docs/RECEIPT_CAPTURE_SPEC.md §3).
+
+`bank_transactions.bankAccountId` is REQUIRED in the Prisma schema, so
+`prisma db push` cannot introduce it on a table that already holds 22k rows.
+This script does the ordered dance that push can't:
+
+  1. create `banks` / `bank_accounts` (same DDL Prisma generates)
+  2. seed the one account every existing row belongs to — Scotiabank MXN,
+     the office's Utilities chequera, which is all `SCOTHIA.mdb` ever was
+  3. add `bankAccountId` NULLable, backfill every row to that account,
+     then promote it to NOT NULL and attach the FK + index
+
+On a database that predates the feature, run it BEFORE `prisma db push`; push
+then sees no drift. On a fresh environment push creates the tables itself and
+this only seeds the rows. Either way `transform_bank.py` needs the account to
+exist, so `run_all.py` runs it first. Idempotent — safe to re-run, and
+re-running once a second account exists does NOT re-point rows (the backfill
+only touches NULLs).
+
+    ./.venv/bin/python backfill_bank_accounts.py --env dev
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from dbenv import connect
+from sync import parse_mode
+
+# The account every migrated SCOTHIA row belongs to. Its id is derived, not
+# random, so a re-run against a half-applied database finds the same row and
+# `transform_bank.py` can resolve it by label without a lookup table.
+SCOTIABANK = "Scotiabank"
+UTILITIES_ACCOUNT = "Utilities — Scotiabank (MXN)"
+
+
+def table_exists(c, name: str) -> bool:
+    c.execute(
+        "SELECT COUNT(*) FROM information_schema.tables "
+        "WHERE table_schema = DATABASE() AND table_name = %s",
+        (name,),
+    )
+    return c.fetchone()[0] > 0
+
+
+def column_exists(c, table: str, column: str) -> bool:
+    c.execute(
+        "SELECT COUNT(*) FROM information_schema.columns "
+        "WHERE table_schema = DATABASE() AND table_name = %s AND column_name = %s",
+        (table, column),
+    )
+    return c.fetchone()[0] > 0
+
+
+def constraint_exists(c, table: str, name: str) -> bool:
+    c.execute(
+        "SELECT COUNT(*) FROM information_schema.table_constraints "
+        "WHERE table_schema = DATABASE() AND table_name = %s AND constraint_name = %s",
+        (table, name),
+    )
+    return c.fetchone()[0] > 0
+
+
+def index_exists(c, table: str, name: str) -> bool:
+    c.execute(
+        "SELECT COUNT(*) FROM information_schema.statistics "
+        "WHERE table_schema = DATABASE() AND table_name = %s AND index_name = %s",
+        (table, name),
+    )
+    return c.fetchone()[0] > 0
+
+
+def main():
+    # `--sync` is accepted and ignored: this step is idempotent by nature, so
+    # it behaves identically in both modes and can sit in run_all's two lists.
+    env, _sync_mode = parse_mode()
+    conn = connect(env)
+    c = conn.cursor()
+    print(f"[bank-accounts] target env: {env}")
+
+    # --- 1. tables ----------------------------------------------------------
+    if not table_exists(c, "banks"):
+        c.execute(
+            """
+            CREATE TABLE `banks` (
+              `id`      VARCHAR(191) NOT NULL,
+              `name`    VARCHAR(191) NOT NULL,
+              `country` VARCHAR(191) NULL,
+              PRIMARY KEY (`id`),
+              UNIQUE KEY `banks_name_key` (`name`)
+            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+            """
+        )
+        print("  created banks")
+
+    if not table_exists(c, "bank_accounts"):
+        c.execute(
+            """
+            CREATE TABLE `bank_accounts` (
+              `id`           VARCHAR(191) NOT NULL,
+              `bankId`       VARCHAR(191) NOT NULL,
+              `label`        VARCHAR(191) NOT NULL,
+              `currency`     ENUM('USD','MXN') NOT NULL,
+              `businessLine` ENUM('UTILITY','INSURANCE','TRUST') NULL,
+              `active`       TINYINT(1) NOT NULL DEFAULT 1,
+              PRIMARY KEY (`id`),
+              KEY `bank_accounts_bankId_fkey` (`bankId`),
+              CONSTRAINT `bank_accounts_bankId_fkey` FOREIGN KEY (`bankId`)
+                REFERENCES `banks` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE
+            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
+            """
+        )
+        print("  created bank_accounts")
+
+    # --- 2. seed the Utilities/Scotiabank chequera --------------------------
+    c.execute("SELECT id FROM banks WHERE name = %s", (SCOTIABANK,))
+    row = c.fetchone()
+    if row:
+        bank_id = row[0]
+    else:
+        bank_id = str(uuid.uuid4())
+        c.execute(
+            "INSERT INTO banks (id, name, country) VALUES (%s, %s, %s)",
+            (bank_id, SCOTIABANK, "MX"),
+        )
+        print(f"  seeded bank {SCOTIABANK}")
+
+    c.execute("SELECT id FROM bank_accounts WHERE label = %s", (UTILITIES_ACCOUNT,))
+    row = c.fetchone()
+    if row:
+        account_id = row[0]
+    else:
+        account_id = str(uuid.uuid4())
+        c.execute(
+            "INSERT INTO bank_accounts (id, bankId, label, currency, businessLine, active) "
+            "VALUES (%s, %s, %s, 'MXN', 'UTILITY', 1)",
+            (account_id, bank_id, UTILITIES_ACCOUNT),
+        )
+        print(f"  seeded account {UTILITIES_ACCOUNT}")
+    print(f"  account id: {account_id}")
+
+    # --- 3. column, backfill, promote to NOT NULL ---------------------------
+    if not column_exists(c, "bank_transactions", "bankAccountId"):
+        c.execute("ALTER TABLE `bank_transactions` ADD COLUMN `bankAccountId` VARCHAR(191) NULL")
+        print("  added bank_transactions.bankAccountId (nullable)")
+
+    c.execute(
+        "UPDATE bank_transactions SET bankAccountId = %s WHERE bankAccountId IS NULL",
+        (account_id,),
+    )
+    print(f"  backfilled {c.rowcount} movement(s) to {UTILITIES_ACCOUNT}")
+
+    c.execute("SELECT COUNT(*) FROM bank_transactions WHERE bankAccountId IS NULL")
+    orphans = c.fetchone()[0]
+    if orphans:
+        raise SystemExit(f"abort: {orphans} bank_transactions still have no account")
+
+    c.execute("ALTER TABLE `bank_transactions` MODIFY `bankAccountId` VARCHAR(191) NOT NULL")
+
+    if not index_exists(c, "bank_transactions", "bank_transactions_bankAccountId_transactionDate_idx"):
+        c.execute(
+            "CREATE INDEX `bank_transactions_bankAccountId_transactionDate_idx` "
+            "ON `bank_transactions` (`bankAccountId`, `transactionDate`)"
+        )
+        print("  created (bankAccountId, transactionDate) index")
+
+    if not constraint_exists(c, "bank_transactions", "bank_transactions_bankAccountId_fkey"):
+        c.execute(
+            "ALTER TABLE `bank_transactions` "
+            "ADD CONSTRAINT `bank_transactions_bankAccountId_fkey` FOREIGN KEY (`bankAccountId`) "
+            "REFERENCES `bank_accounts` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE"
+        )
+        print("  attached bankAccountId FK")
+
+    conn.commit()
+
+    c.execute(
+        "SELECT a.label, a.currency, COUNT(t.id), COALESCE(SUM(t.amount), 0) "
+        "FROM bank_accounts a LEFT JOIN bank_transactions t ON t.bankAccountId = a.id "
+        "GROUP BY a.id, a.label, a.currency ORDER BY a.label"
+    )
+    print("=== Multi-bank chequera ready ===")
+    for label, currency, n, total in c.fetchall():
+        print(f"  {label:36} {currency}  {n:6} movimientos  neto {total}")
+    print("  validation: OK")
+    conn.close()
+
+
+if __name__ == "__main__":
+    main()