Merge pull request 'fix(ext-ci): use browser_download_url + curl -f + ZIP magic check (XPI silently corrupt)' (#20) from dev into main

.forgejo/workflows/build.yml

@@ -6,18 +6,197 @@ on:
 
 # Requires repo secret RELEASE_TOKEN — a Forgejo PAT with scopes:
 #   - write:package, read:package  (for docker push to git.fabledsword.com)
-#   - write:release                (for future release-cutting workflows)
+#   - write:release                (for ext-<version> release asset cache)
 #   - write:issue                  (for future issue-management automation)
 # The injected GITHUB_TOKEN cannot be used — it lacks write:package.
 
 jobs:
-  build-web:
+  # Sign-or-fetch-from-cache: signs the extension via AMO if no ext-<version>
+  # Forgejo release exists yet, otherwise downloads the cached signed XPI.
+  # Result is uploaded as an Actions artifact for build-web to consume.
+  #
+  # Why this lives in build.yml (not a separate workflow): the merge-commit's
+  # docker image tagged `:latest` MUST carry the XPI. A separate sign workflow
+  # racing build.yml leaves `:latest` without the XPI for ~5min (until the
+  # commit-back triggers another build). Inline ordering eliminates the race.
+  # Cache strategy: Forgejo Release Assets — picked 2026-05-25 over Generic
+  # Packages (cleaner API surface) and commit-back-to-side-branch (no extra
+  # branch to manage). AMO blocks re-signing the same version (returns 409),
+  # so signing is intentionally one-shot per version bump.
+  sign-extension:
+    if: github.ref == 'refs/heads/main'
     runs-on: python-ci
     container:
       image: git.fabledsword.com/bvandeusen/ci-python:3.14
     steps:
       - uses: actions/checkout@v4
 
+      - name: Resolve extension version
+        id: extver
+        run: |
+          VERSION=$(grep -E '"version"' extension/package.json | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Resolved extension version: $VERSION"
+
+      - name: Check Forgejo release-asset cache
+        id: cache
+        env:
+          TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          set -eu
+          VERSION=${{ steps.extver.outputs.version }}
+          STATUS=$(curl -s -o release.json -w "%{http_code}" \
+            -H "Authorization: token $TOKEN" \
+            "https://git.fabledsword.com/api/v1/repos/bvandeusen/FabledCurator/releases/tags/ext-$VERSION" || echo 000)
+          echo "Tag lookup HTTP status: $STATUS"
+          # JSON parsing via python (ci-python:3.14 has stdlib json; jq is
+          # not in the image and adding it per ci-requirements.md is not
+          # warranted for a single consumer — operator-flagged 2026-05-26
+          # after a sign job failed with `jq: not found`).
+          if [ "$STATUS" = "200" ]; then
+            ASSET_ID=$(python3 -c "import json; r=json.load(open('release.json')); xpis=[a for a in r.get('assets', []) if a.get('name','').endswith('.xpi')]; print(xpis[0]['id'] if xpis else '')")
+            if [ -n "$ASSET_ID" ]; then
+              echo "cached=true" >> "$GITHUB_OUTPUT"
+              echo "asset_id=$ASSET_ID" >> "$GITHUB_OUTPUT"
+              echo "Cached XPI exists at ext-$VERSION (asset id $ASSET_ID); skipping AMO sign"
+            else
+              echo "cached=false" >> "$GITHUB_OUTPUT"
+              echo "Release ext-$VERSION exists but has no .xpi asset; will re-sign + re-upload"
+            fi
+          else
+            echo "cached=false" >> "$GITHUB_OUTPUT"
+            echo "No release named ext-$VERSION; will sign via AMO and upload"
+          fi
+
+      # No "download cached XPI in sign-extension" step: build-web
+      # fetches directly from the Forgejo ext-<version> release asset
+      # (removed 2026-05-26 alongside the actions/upload-artifact
+      # removal — sign-extension's job is just to ensure the cache
+      # exists on Forgejo; the build-web side reads it independently).
+
+      - name: Sign via AMO (cache miss)
+        if: steps.cache.outputs.cached != 'true'
+        run: |
+          cd extension && npm install --no-save --no-audit --no-fund && npm run sign
+        env:
+          WEB_EXT_API_KEY: ${{ secrets.MOZILLA_AMO_JWT_KEY }}
+          WEB_EXT_API_SECRET: ${{ secrets.MOZILLA_AMO_JWT_SECRET }}
+
+      - name: Upload signed XPI to ext-<version> release (cache miss)
+        if: steps.cache.outputs.cached != 'true'
+        env:
+          TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          set -eux
+          VERSION=${{ steps.extver.outputs.version }}
+          # AMO renames signed XPIs with its internal addon-id-safe-string;
+          # canonicalize to fabledcurator-<version>.xpi so the FC server's
+          # whitelist (backend/app/frontend.py expects 'fabledcurator-*.xpi')
+          # keeps working.
+          SIGNED=$(ls extension/web-ext-artifacts/*.xpi | head -1)
+          XPI="extension/web-ext-artifacts/fabledcurator-$VERSION.xpi"
+          cp "$SIGNED" "$XPI"
+          # Find-or-create the ext-<version> release. Track whether WE
+          # created it so an upload failure below can roll back (don't
+          # leave an empty release tombstone that the next run's
+          # cache-check mistakes for a partial-failure state).
+          STATUS=$(curl -s -o release.json -w "%{http_code}" \
+            -H "Authorization: token $TOKEN" \
+            "https://git.fabledsword.com/api/v1/repos/bvandeusen/FabledCurator/releases/tags/ext-$VERSION" || echo 000)
+          if [ "$STATUS" = "200" ]; then
+            CREATED_BY_US=false
+          else
+            curl -s -X POST -H "Authorization: token $TOKEN" -H "Content-Type: application/json" \
+              -d "{\"tag_name\":\"ext-$VERSION\",\"name\":\"Extension $VERSION (signed XPI cache)\",\"body\":\"Internal cache for the signed XPI consumed by build.yml's build-web job. Not a user-facing FC release.\",\"target_commitish\":\"main\"}" \
+              -o release.json \
+              "https://git.fabledsword.com/api/v1/repos/bvandeusen/FabledCurator/releases"
+            CREATED_BY_US=true
+          fi
+          RELEASE_ID=$(python3 -c "import json; print(json.load(open('release.json'))['id'])")
+          test -n "$RELEASE_ID"
+          # Rollback-on-failure: if the asset upload fails AND we just
+          # created the release in this run, delete it. Prevents an empty
+          # ext-<version> release from poisoning the next workflow run
+          # (operator-flagged 2026-05-26 — without rollback the next run
+          # saw 'release exists, no asset → cache miss → sign' which AMO
+          # then rejected with 409 'Version already exists').
+          rollback_if_we_created() {
+            if [ "$CREATED_BY_US" = "true" ]; then
+              echo "Rolling back: deleting just-created release $RELEASE_ID"
+              curl -s -X DELETE -H "Authorization: token $TOKEN" \
+                "https://git.fabledsword.com/api/v1/repos/bvandeusen/FabledCurator/releases/$RELEASE_ID" || true
+              curl -s -X DELETE -H "Authorization: token $TOKEN" \
+                "https://git.fabledsword.com/api/v1/repos/bvandeusen/FabledCurator/tags/ext-$VERSION" || true
+            fi
+          }
+          trap 'rollback_if_we_created' EXIT
+          HTTP_CODE=$(curl -s -X POST -H "Authorization: token $TOKEN" \
+            -F "attachment=@$XPI" \
+            -o /dev/null -w "%{http_code}" \
+            "https://git.fabledsword.com/api/v1/repos/bvandeusen/FabledCurator/releases/$RELEASE_ID/assets?name=fabledcurator-$VERSION.xpi")
+          if [ "$HTTP_CODE" != "201" ] && [ "$HTTP_CODE" != "200" ]; then
+            echo "Asset upload failed with HTTP $HTTP_CODE"
+            exit 1
+          fi
+          # Upload succeeded — clear the rollback trap.
+          trap - EXIT
+          echo "Uploaded fabledcurator-$VERSION.xpi to ext-$VERSION release"
+
+      # No actions/upload-artifact step: Forgejo Actions (and our
+       # act_runner) doesn't support upload-artifact@v4+ (GHES limitation
+       # surfaced 2026-05-26). Instead build-web reads the signed XPI
+       # straight from the ext-<version> Forgejo release we just uploaded
+       # to. Same source of truth; no double-store.
+
+  build-web:
+    needs: [sign-extension]
+    # sign-extension is main-only; on dev it's skipped, build-web still runs.
+    if: always() && (needs.sign-extension.result == 'success' || needs.sign-extension.result == 'skipped')
+    runs-on: python-ci
+    container:
+      image: git.fabledsword.com/bvandeusen/ci-python:3.14
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download signed XPI from Forgejo release asset (main only)
+        if: github.ref == 'refs/heads/main'
+        env:
+          TOKEN: ${{ secrets.RELEASE_TOKEN }}
+        run: |
+          set -eux
+          VERSION=$(grep -E '"version"' extension/package.json | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
+          # Look up the ext-<version> release; extract the .xpi asset's
+          # browser_download_url (Forgejo's /releases/assets/<id> endpoint
+          # returns ASSET METADATA, not the binary blob — operator-flagged
+          # 2026-05-26: my prior code curl'd the metadata endpoint without
+          # -f and wrote the resulting 404-page-not-found text into
+          # fabledcurator-*.xpi, which Firefox then rejected as "corrupt").
+          # browser_download_url is the canonical binary endpoint and is
+          # also publicly accessible (no token needed) but we pass the
+          # token anyway for symmetry with private-repo support.
+          curl -sf -H "Authorization: token $TOKEN" \
+            "https://git.fabledsword.com/api/v1/repos/bvandeusen/FabledCurator/releases/tags/ext-$VERSION" \
+            -o release.json
+          DOWNLOAD_URL=$(python3 -c "import json; r=json.load(open('release.json')); xpis=[a for a in r.get('assets', []) if a.get('name','').endswith('.xpi')]; print(xpis[0]['browser_download_url'])")
+          test -n "$DOWNLOAD_URL"
+          echo "Downloading XPI from: $DOWNLOAD_URL"
+          mkdir -p frontend/public/extension
+          DEST="frontend/public/extension/fabledcurator-$VERSION.xpi"
+          # -f = fail on HTTP error (prevents silent corruption like the
+          # 2026-05-26 incident); -L = follow redirects.
+          curl -sfL -H "Authorization: token $TOKEN" -o "$DEST" "$DOWNLOAD_URL"
+          # Sanity check: the binary should start with the ZIP magic (PK\x03\x04).
+          # If it's anything else, the next docker build will ship a corrupt XPI.
+          MAGIC=$(head -c 2 "$DEST" | od -An -c | tr -d ' \n')
+          if [ "$MAGIC" != "PK" ]; then
+            echo "ERROR: downloaded XPI does not start with ZIP magic 'PK' (got '$MAGIC')"
+            echo "File contents preview:"
+            head -c 200 "$DEST"
+            exit 1
+          fi
+          cp "$DEST" "frontend/public/extension/fabledcurator-latest.xpi"
+          ls -la frontend/public/extension/
+
       - name: Determine tag
         id: tag
         run: |

.forgejo/workflows/extension.yml

@@ -1,15 +1,19 @@
 name: extension
+# Lint-only workflow. The sign-and-publish dance moved into build.yml's
+# `sign-extension` job (2026-05-25) — `:latest` now always bundles the XPI
+# because sign-extension runs as a build-web dependency in the SAME workflow,
+# eliminating the prior race between build.yml and a separate extension.yml.
+# Signed XPIs are cached in Forgejo Release Assets named `ext-<version>`.
 on:
   push:
     branches: [dev, main]
-    # Self-retriggering: include the workflow file itself so edits to
-    # this workflow (filename-glob fixes, env tweaks, etc.) run the
-    # sign-and-publish dance on next push without needing a manual
-    # Forgejo dispatch. Side-effect commits (`ext: publish signed XPI`)
-    # only touch frontend/public/extension/ so they DON'T re-trigger.
     paths:
       - 'extension/**'
       - '.forgejo/workflows/extension.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'extension/**'
   workflow_dispatch:
 
 jobs:
@@ -23,74 +27,3 @@ jobs:
         run: cd extension && npm install --no-save --no-audit --no-fund
       - name: Lint
         run: cd extension && npm run lint
-
-  sign-and-publish:
-    needs: lint
-    if: github.ref == 'refs/heads/main'
-    runs-on: python-ci
-    container:
-      image: node:22-bookworm-slim
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          token: ${{ secrets.RELEASE_TOKEN }}
-      - name: Install web-ext + git
-        run: |
-          apt-get update && apt-get install -y --no-install-recommends git ca-certificates
-          cd extension && npm install --no-save --no-audit --no-fund
-      - name: Sign XPI
-        run: cd extension && npm run sign
-        env:
-          WEB_EXT_API_KEY: ${{ secrets.MOZILLA_AMO_JWT_KEY }}
-          WEB_EXT_API_SECRET: ${{ secrets.MOZILLA_AMO_JWT_SECRET }}
-      - name: Commit signed XPI to frontend/public/extension/
-        run: |
-          set -ex
-          # AMO renames signed XPIs using its internal addon-id-safe-string
-          # (e.g. 997017ca3e104e30a75a-1.0.1.xpi), NOT our gecko ID. Match
-          # any *.xpi in the artifacts dir — fresh CI runner means there's
-          # exactly one — and rename it on copy so the FC server's
-          # whitelist (backend/app/frontend.py expects 'fabledcurator-*.xpi')
-          # keeps working.
-          # Diagnostic instrumentation 2026-05-25: a prior run (id 1731)
-          # reported success without producing an `ext: publish signed XPI`
-          # commit on main. Tracing the cwd, artifacts dir, version
-          # extraction, staging state, and push response so the next run's
-          # log explains the gap.
-          echo "=== cwd ==="
-          pwd
-          echo "=== ref / branch ==="
-          echo "ref: ${GITHUB_REF:-unset}  sha: ${GITHUB_SHA:-unset}"
-          git log --oneline -3 || true
-          echo "=== artifacts dir ==="
-          ls -la extension/web-ext-artifacts/ 2>&1 || echo "(dir missing)"
-          XPI=$(ls extension/web-ext-artifacts/*.xpi 2>/dev/null | head -1)
-          echo "XPI=$XPI"
-          if [ -z "$XPI" ]; then
-            echo "No XPI produced by web-ext sign — exiting"
-            exit 1
-          fi
-          VERSION=$(grep -E '"version"' extension/package.json | head -1 | sed -E 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')
-          echo "VERSION=$VERSION"
-          DEST="frontend/public/extension/fabledcurator-${VERSION}.xpi"
-          echo "DEST=$DEST"
-          mkdir -p frontend/public/extension
-          # Wipe any prior versions so the directory doesn't grow each release.
-          rm -f frontend/public/extension/fabledcurator-*.xpi
-          cp "$XPI" "$DEST"
-          cp "$XPI" "frontend/public/extension/fabledcurator-latest.xpi"
-          echo "=== frontend/public/extension/ after copy ==="
-          ls -la frontend/public/extension/
-          git config user.name  "FC extension CI"
-          git config user.email "noreply@fabledsword.com"
-          git add frontend/public/extension/
-          echo "=== git status after add ==="
-          git status --short
-          echo "=== diff --cached --stat ==="
-          git diff --cached --stat || true
-          if git diff --cached --quiet; then
-            echo "No changes to commit (frontend/public/extension/ matches HEAD)"
-          else
-            git commit -m "ext: publish signed XPI fabledcurator-${VERSION}.xpi"
-            git push -v origin HEAD:main
-          fi

alembic/versions/0019_import_batch_refreshed.py

@@ -0,0 +1,38 @@
+"""import_batch.refreshed counter for deep-scan sidecar re-application
+
+Revision ID: 0019
+Revises: 0018
+Create Date: 2026-05-25
+
+Adds a `refreshed` counter to `import_batch`, mirroring the existing
+`imported`/`skipped`/`failed`/`attachments` columns. Deep scan now
+re-applies sidecar metadata to already-imported files (the IR feature
+that didn't make the FC port the first time); a "refreshed" outcome
+increments this counter so the UI can surface "X new, Y refreshed"
+instead of the misleading "Scan complete — no new files" message.
+
+server_default=0 backfills existing rows in place — no UPDATE needed.
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0019"
+down_revision: Union[str, None] = "0018"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "import_batch",
+        sa.Column(
+            "refreshed", sa.Integer(),
+            nullable=False, server_default=sa.text("0"),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("import_batch", "refreshed")

backend/app/api/import_admin.py

@@ -53,6 +53,7 @@ async def status():
                 "imported": active.imported,
                 "skipped": active.skipped,
                 "failed": active.failed,
+                "refreshed": active.refreshed,
                 "started_at": active.started_at.isoformat(),
             }
         return jsonify(payload)

backend/app/models/import_batch.py

@@ -26,6 +26,10 @@ class ImportBatch(Base):
     skipped: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
     failed: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
     attachments: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    # Deep-scan only: count of already-imported files whose sidecar metadata
+    # got re-applied this run (post/source/provenance upsert). Stays 0 on
+    # quick-scan batches. See `Importer.import_one(deep_scan=True)`.
+    refreshed: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
 
     status: Mapped[str] = mapped_column(String(16), nullable=False, default="running", index=True)
     # running | complete | cancelled

backend/app/services/importer.py

@@ -51,7 +51,14 @@ class SkipReason(StrEnum):
 
 @dataclass(frozen=True)
 class ImportResult:
-    status: str  # 'imported'|'skipped'|'failed'|'superseded'|'attached'
+    # 'imported'   — new ImageRecord row created
+    # 'superseded' — existing ImageRecord row got the new file (larger) + sidecar
+    # 'attached'   — non-media saved as PostAttachment
+    # 'refreshed'  — deep scan re-applied sidecar / filled NULL phash / NULL
+    #                artist on an already-imported row (no new ImageRecord)
+    # 'skipped'    — no work done (true duplicate, too small, etc.)
+    # 'failed'     — pipeline error
+    status: str
     image_id: int | None = None
     skip_reason: SkipReason | None = None
     error: str | None = None
@@ -151,6 +158,49 @@ class Importer:
         self.settings = settings
         self.deep = deep
         self.attachments = AttachmentStore(images_root)
+        # phash near-dup candidate cache. Archive imports call _import_media
+        # per-member; without this cache the per-member SELECT *FROM
+        # image_record WHERE phash IS NOT NULL fetch repeats N times and a
+        # large library × many-member archive blew past soft_time_limit
+        # (300s) — operator-flagged 2026-05-25. Loaded lazily on first
+        # need, appended to on every imported/superseded outcome, never
+        # invalidated mid-Importer (Importer instances are per-task /
+        # per-archive-import so cross-instance staleness is harmless).
+        self._phash_candidates: list[tuple] | None = None
+
+    def _phash_candidates_cache(self) -> list[tuple]:
+        """Cached `(phash, width, height, id)` rows from image_record.
+        Loaded on first call, appended-to on subsequent imported/
+        superseded outcomes. Soft-timeout pattern: an archive with N
+        members + a library of M existing rows used to do N × M-row
+        fetches (operator-flagged 2026-05-25); now it's exactly one.
+
+        The per-task lifecycle of Importer (instantiated fresh by
+        import_media_file) bounds the cache's staleness window: cross-
+        process changes (other workers importing concurrently) won't
+        be reflected, but that's the same race the un-cached version
+        had — `find_similar` is best-effort anyway."""
+        if self._phash_candidates is None:
+            rows = self.session.execute(
+                select(
+                    ImageRecord.phash,
+                    ImageRecord.width,
+                    ImageRecord.height,
+                    ImageRecord.id,
+                ).where(ImageRecord.phash.is_not(None))
+            ).all()
+            self._phash_candidates = [
+                (r.phash, r.width or 0, r.height or 0, r.id) for r in rows
+            ]
+        return self._phash_candidates
+
+    def _phash_cache_append(self, phash, width, height, image_id) -> None:
+        """Append a freshly-imported row to the cache so subsequent
+        members of the same archive can match against it."""
+        if self._phash_candidates is not None and phash is not None:
+            self._phash_candidates.append(
+                (phash, width or 0, height or 0, image_id)
+            )
 
     def import_one(self, source: Path) -> ImportResult:
         """Dispatch by kind. Media → normal pipeline. Archive → extract
@@ -349,18 +399,7 @@ class Importer:
                     error=f"PIL load failed during phash compute: {exc}",
                 )
             if phash is not None:
-                cand_rows = self.session.execute(
-                    select(
-                        ImageRecord.phash,
-                        ImageRecord.width,
-                        ImageRecord.height,
-                        ImageRecord.id,
-                    ).where(ImageRecord.phash.is_not(None))
-                ).all()
-                candidates = [
-                    (c.phash, c.width or 0, c.height or 0, c.id)
-                    for c in cand_rows
-                ]
+                candidates = self._phash_candidates_cache()
                 rel, match_id = find_similar(
                     phash, width or 0, height or 0,
                     candidates, self.settings.phash_threshold,
@@ -394,6 +433,7 @@ class Importer:
         )
         self.session.add(record)
         self.session.flush()
+        self._phash_cache_append(phash, width, height, record.id)
 
         # Folder→artist (anchored to attribution_path).
         artist = None
@@ -417,13 +457,27 @@ class Importer:
     ) -> ImportResult:
         """Deep scan: backfill phash/provenance/artist on an
         already-imported record. METADATA ONLY — never re-runs the pHash
-        near-dup / supersede path. NULL-only, idempotent."""
+        near-dup / supersede path. NULL-only on phash/artist, additive on
+        sidecar Post/Source/ImageProvenance (via _apply_sidecar).
+        Idempotent: a second deep-scan over the same file finds nothing
+        to refresh and is a no-op.
+
+        Returns status="refreshed" so the UI can surface the work done
+        instead of the prior misleading "skipped/duplicate_hash" reading.
+        Operator-flagged 2026-05-25 — IR has had this; FC inherited it
+        as a no-op skip during the original port and the UI showed deep
+        scan as "completed with no changes" even when sidecar metadata
+        actually got re-applied to N existing rows.
+        """
         if existing.phash is None and not is_video(source):
             try:
                 with Image.open(source) as im:
                     ph = compute_phash(im)
                 if ph is not None:
                     existing.phash = ph
+                    # Promoted from NULL to non-NULL → cache is now stale
+                    # (this row would newly qualify for the candidates set).
+                    self._phash_candidates = None
             except Exception as exc:
                 log.warning("deep rephash failed for %s: %s", source, exc)
 
@@ -436,10 +490,7 @@ class Importer:
 
         self._apply_sidecar(existing, attribution_path, artist)
         self.session.commit()
-        return ImportResult(
-            status="skipped", skip_reason=SkipReason.duplicate_hash,
-            image_id=existing.id, error="deep: re-derived",
-        )
+        return ImportResult(status="refreshed", image_id=existing.id)
 
     def attach_in_place(
         self,
@@ -523,18 +574,7 @@ class Importer:
             except Exception:
                 phash = None
             if phash is not None:
-                cand_rows = self.session.execute(
-                    select(
-                        ImageRecord.phash,
-                        ImageRecord.width,
-                        ImageRecord.height,
-                        ImageRecord.id,
-                    ).where(ImageRecord.phash.is_not(None))
-                ).all()
-                candidates = [
-                    (c.phash, c.width or 0, c.height or 0, c.id)
-                    for c in cand_rows
-                ]
+                candidates = self._phash_candidates_cache()
                 rel, match_id = find_similar(
                     phash, width or 0, height or 0,
                     candidates, self.settings.phash_threshold,
@@ -569,6 +609,7 @@ class Importer:
             record.artist_id = artist.id
         self.session.add(record)
         self.session.flush()
+        self._phash_cache_append(phash, width, height, record.id)
 
         # Sidecar provenance (best-effort). When `source` is passed, link
         # the post to that subscription Source instead of creating a new
@@ -784,6 +825,10 @@ class Importer:
         # created_at intentionally preserved; updated_at auto-bumps.
         self.session.flush()
         self.session.commit()
+        # The phash candidate cache (used to avoid N+1 selects during
+        # archive imports) is now stale for `existing.id` — the row's
+        # phash/dimensions changed. Invalidate; the next call re-fetches.
+        self._phash_candidates = None
 
         # Sidecar enrichment from the new (larger) file's location.
         # _apply_sidecar resolves artist from the sidecar itself if the

backend/app/tasks/import_file.py

@@ -29,10 +29,12 @@ IMAGES_ROOT = Path("/images")
 def _map_result_to_status(result):
     """(ImportTask.status, should_requeue_ml_and_thumb) for an ImportResult.
     'superseded' = the kept row's file/ML changed → complete + re-derive.
-    'attached' = a non-art file preserved → complete, no ML/thumb."""
+    'attached' = a non-art file preserved → complete, no ML/thumb.
+    'refreshed' = deep scan refreshed sidecar/phash on an existing row →
+    complete, no ML/thumb re-derive (file/pixels unchanged)."""
     if result.status in ("imported", "superseded"):
         return ("complete", True)
-    if result.status == "attached":
+    if result.status in ("attached", "refreshed"):
         return ("complete", False)
     if result.status == "skipped":
         return ("skipped", False)
@@ -138,6 +140,15 @@ def _do_import(session, task, import_task_id: int) -> dict:
         task.result_image_id = result.image_id
         counter_col_name = "imported"
         counter_col = ImportBatch.imported
+    elif result.status == "refreshed":
+        # Deep-scan rederive: existing row got phash/artist/sidecar
+        # refreshed. Task is complete (no further work), but counted in
+        # `refreshed` not `imported` so the UI can surface the actual
+        # work done. operator-flagged 2026-05-25.
+        task.status = "complete"
+        task.result_image_id = result.image_id
+        counter_col_name = "refreshed"
+        counter_col = ImportBatch.refreshed
     elif result.status == "attached":
         task.status = "complete"
         counter_col_name = "attachments"

backend/app/tasks/scan.py

@@ -59,16 +59,25 @@ def scan_directory(self, triggered_by: str = "manual",
         session.flush()
         batch_id = batch.id
 
-        # Skip-set: any source_path that already has a non-failed ImportTask
-        # row. Re-running scan_directory must not re-enqueue files the
-        # importer has already handled (or is currently handling); doing so
-        # creates duplicate work and inflates the queue. Failed prior tasks
-        # are eligible for retry.
+        # Skip-set behavior splits by mode (operator-flagged 2026-05-25):
+        #
+        # quick: any non-failed prior ImportTask (active OR finished) is
+        #   skipped — quick scan only does new-file enqueue, so re-touching
+        #   already-imported files is wasted work.
+        #
+        # deep: ONLY currently-in-flight tasks (pending/queued/processing)
+        #   are skipped. Completed and skipped tasks ARE re-queued because
+        #   deep scan exists precisely to re-touch already-imported files
+        #   (refresh sidecar metadata, fill NULL phash, fill NULL artist
+        #   via Importer._deep_rederive). Matches IR's deep-scan behavior.
+        active_statuses = ["pending", "queued", "processing"]
+        if mode == "deep":
+            skip_statuses = active_statuses
+        else:
+            skip_statuses = active_statuses + ["complete", "skipped"]
         non_failed_existing = set(session.execute(
             select(ImportTask.source_path).where(
-                ImportTask.status.in_(
-                    ["pending", "queued", "processing", "complete", "skipped"]
-                ),
+                ImportTask.status.in_(skip_statuses),
             )
         ).scalars().all())
 

backend/app/utils/sidecar.py

@@ -4,6 +4,7 @@ No per-platform branching: a small common key set with fallbacks; the
 full JSON is kept in raw so anything unmapped is recoverable later.
 """
 
+import re
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from pathlib import Path
@@ -21,10 +22,28 @@ class SidecarData:
     raw: dict
 
 
+# gallery-dl prefixes media filenames with `NN_` for in-post ordering
+# (`01_HOLLOW-ICHIGO.png`, `02_HOLOW ICHIGO.zip`) but writes the sidecar
+# under the attachment's stem WITHOUT that ordering prefix
+# (`HOLLOW-ICHIGO.json`). Strip the prefix when looking for sidecars.
+# Confirmed against real Patreon downloads 2026-05-26 — without this
+# strip, every gallery-dl post-level sidecar was invisible to FC since
+# FC-3 shipped (24 deep-refresh calls produced 0 Posts in operator's DB).
+_NUMBERING_PREFIX = re.compile(r"^\d+_(.+)$")
+
+
 def find_sidecar(media: Path) -> Path | None:
+    # Attachment-level sidecars (image.jpg.json, image.json).
     for cand in (media.with_suffix(".json"), Path(str(media) + ".json")):
         if cand.is_file():
             return cand
+    # gallery-dl post-numbered convention: strip the `NN_` prefix from
+    # the stem and look for that.json in the same directory.
+    m = _NUMBERING_PREFIX.match(media.stem)
+    if m:
+        cand = media.parent / f"{m.group(1)}.json"
+        if cand.is_file():
+            return cand
     return None
 
 

extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "FabledCurator",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Export cookies from supported platforms to FabledCurator and add creators as sources in one click.",
 
   "browser_specific_settings": {

extension/package.json

@@ -1,13 +1,13 @@
 {
   "name": "fabledcurator-extension",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "private": true,
   "description": "Firefox extension for FabledCurator",
   "scripts": {
-    "lint":  "web-ext lint --source-dir=.",
-    "start": "web-ext run --source-dir=. --firefox=firefox",
-    "build": "web-ext build --source-dir=. --overwrite-dest",
-    "sign":  "web-ext sign --source-dir=. --channel=unlisted --api-key=$WEB_EXT_API_KEY --api-secret=$WEB_EXT_API_SECRET"
+    "lint":  "web-ext lint --source-dir=. --no-config-discovery --ignore-files package.json package-lock.json web-ext-artifacts node_modules README.md .gitignore",
+    "start": "web-ext run --source-dir=. --no-config-discovery --ignore-files package.json package-lock.json web-ext-artifacts node_modules README.md .gitignore --firefox=firefox",
+    "build": "web-ext build --source-dir=. --no-config-discovery --ignore-files package.json package-lock.json web-ext-artifacts node_modules README.md .gitignore --overwrite-dest",
+    "sign":  "web-ext sign --source-dir=. --no-config-discovery --ignore-files package.json package-lock.json web-ext-artifacts node_modules README.md .gitignore --channel=unlisted --api-key=$WEB_EXT_API_KEY --api-secret=$WEB_EXT_API_SECRET"
   },
   "devDependencies": {
     "web-ext": "^8.0.0"

extension/web-ext-config.cjs

@@ -1,13 +0,0 @@
-module.exports = {
-  sourceDir: '.',
-  artifactsDir: './web-ext-artifacts',
-  ignoreFiles: [
-    'package.json',
-    'package-lock.json',
-    'web-ext-config.cjs',
-    'web-ext-artifacts',
-    'node_modules',
-    'README.md',
-    '.gitignore',
-  ],
-};

frontend/src/components/settings/ImportTriggerPanel.vue

@@ -10,6 +10,9 @@
           {{ store.activeBatch.scan_mode === 'deep' ? 'Deep scanning' : 'Scanning' }}
           {{ store.activeBatch.source_path || '/import' }} —
           imported {{ store.activeBatch.imported }},
+          <template v-if="store.activeBatch.scan_mode === 'deep'">
+            refreshed {{ store.activeBatch.refreshed || 0 }},
+          </template>
           skipped {{ store.activeBatch.skipped }},
           failed {{ store.activeBatch.failed }} /
           {{ store.activeBatch.total_files }} files
@@ -26,11 +29,12 @@
       <p class="text-body-2 mb-3">
         <span v-if="!store.activeBatch">
           <strong>Quick scan</strong> walks <code>/import</code> and enqueues
-          new files only (skips paths already on a non-failed ImportTask).
-          <strong>Deep scan</strong> additionally chains a phash backfill
-          across the existing library — use after bulk-imports to catch
-          near-duplicates that slipped through. Both modes route non-media
-          + sidecar pairs through PostAttachment capture.
+          new files only.
+          <strong>Deep scan</strong> additionally re-walks already-imported
+          files so updated sidecar metadata (post title/date/attribution) and
+          previously-NULL phashes / artist links get refreshed. Use after
+          bulk-downloading fresh sidecars for existing content. Both modes
+          route non-media + sidecar pairs through PostAttachment capture.
         </span>
         <span v-else>
           An active batch is in progress. Wait for it to finish, or click

frontend/src/stores/import.js

@@ -66,21 +66,42 @@ export const useImportStore = defineStore('import', () => {
       // batch flashes 'running' for <100ms then 'complete' before the
       // first refreshStatus() lands; UI never sees the active state).
       const label = mode === 'deep'
-        ? 'Deep scan triggered (pHash backfill chained)'
+        ? 'Deep scan triggered (re-applying sidecar metadata + filling NULL phash/artist on existing rows)'
         : mode === 'verify' ? 'Library verify triggered' : 'Quick scan triggered'
       window.__fcToast?.({ text: label, type: 'success' })
       await refreshStatus()
-      // Re-poll twice over ~5s to catch quick-finalize transitions and
-      // surface a result toast either way. Skip the "no new files" hint
-      // for 'verify' since it doesn't walk the import_root.
+      // Re-poll twice over ~5s and produce an HONEST follow-up toast.
+      // Operator-flagged 2026-05-25: the prior "no new files" message was
+      // misleading because deep scan IS doing work (refresh) even when
+      // there are no new files to import. Surface the real workload count
+      // (imported + refreshed + queued) instead. For quick scan + zero
+      // queued work, fall back to "up to date" instead of the old
+      // implementation-detail-leaking message.
       setTimeout(async () => {
         await refreshStatus()
         await loadTasks(true)
-        if (!activeBatch.value && mode !== 'verify') {
+        if (activeBatch.value || mode === 'verify') return
+        // Batch finalized quickly; figure out what actually happened.
+        // The task list was just refreshed; the freshest row(s) carry
+        // the batch outcome.
+        const batchId = tasks.value[0]?.batch_id
+        const sameBatch = batchId
+          ? tasks.value.filter(t => t.batch_id === batchId)
+          : []
+        const refreshedCount = sameBatch.filter(t => t.status === 'complete' && t.result_image_id).length
+        const newImported = sameBatch.filter(t => t.status === 'complete' && t.result_image_id && !t.error).length
+        if (mode === 'deep' && sameBatch.length > 0) {
           window.__fcToast?.({
-            text: 'Scan complete — no new files (everything already on an ImportTask row)',
+            text: `Deep scan finished — ${sameBatch.length} file(s) processed`,
             type: 'info',
           })
+        } else if (mode === 'quick' && sameBatch.length > 0) {
+          window.__fcToast?.({
+            text: `Quick scan finished — ${newImported} new file(s) queued`,
+            type: 'info',
+          })
+        } else {
+          window.__fcToast?.({ text: 'Library is up to date', type: 'info' })
         }
       }, 2000)
     } catch (e) {

frontend/src/views/ArtistView.vue

@@ -45,69 +45,92 @@
         >Credential health · FC-3b</v-chip>
       </div>
 
-      <section v-if="store.overview.cooccurring_tags.length" class="fc-artist__sec">
-        <h2 class="fc-h2">Frequent tags</h2>
-        <div class="fc-artist__tags">
-          <v-chip
-            v-for="t in store.overview.cooccurring_tags" :key="t.id"
-            size="small" @click="openTag(t.id)"
-          >{{ t.name }} <span class="fc-artist__tagc">{{ t.count }}</span></v-chip>
-        </div>
-      </section>
+      <!-- Tabs split (2026-05-25): Settings was previously slotted at the
+           bottom of the page after the infinite-scroll image grid, which
+           made it effectively unreachable for any artist with more than
+           a couple of pages of content. The Settings tab now hosts
+           destructive admin actions (artist+content cascade-delete) and
+           any future per-artist management UI. v-tabs is `position:
+           sticky; top: 64px` (under the 64px AppShell TopNav) so it
+           stays parked while the gallery scrolls. -->
+      <v-tabs
+        v-model="tab" color="accent" class="mb-4"
+        style="position: sticky; top: 64px; z-index: 4;
+               background: rgb(var(--v-theme-surface));"
+      >
+        <v-tab value="overview">Overview</v-tab>
+        <v-tab value="settings">Settings</v-tab>
+      </v-tabs>
 
-      <section v-if="store.overview.activity.length" class="fc-artist__sec">
-        <h2 class="fc-h2">Activity</h2>
-        <svg class="fc-artist__spark" :viewBox="`0 0 ${sparkW} ${sparkH}`"
-             preserveAspectRatio="none" role="img" aria-label="posts over time">
-          <polyline :points="sparkPoints" fill="none"
-                    stroke="rgb(var(--v-theme-accent))" stroke-width="2" />
-        </svg>
-      </section>
+      <v-window v-model="tab">
+        <v-window-item value="overview">
+          <section v-if="store.overview.cooccurring_tags.length" class="fc-artist__sec">
+            <h2 class="fc-h2">Frequent tags</h2>
+            <div class="fc-artist__tags">
+              <v-chip
+                v-for="t in store.overview.cooccurring_tags" :key="t.id"
+                size="small" @click="openTag(t.id)"
+              >{{ t.name }} <span class="fc-artist__tagc">{{ t.count }}</span></v-chip>
+            </div>
+          </section>
 
-      <section v-if="store.overview.sources.length" class="fc-artist__sec">
-        <div class="fc-artist__sec-head">
-          <h2 class="fc-h2">Sources</h2>
-          <RouterLink
-            :to="`/subscriptions?artist_id=${store.overview.id}`"
-            class="fc-artist__manage"
-          >Manage subscriptions →</RouterLink>
-        </div>
-        <v-table density="compact">
-          <thead>
-            <tr><th>Platform</th><th>URL</th><th class="text-right">Images</th></tr>
-          </thead>
-          <tbody>
-            <tr v-for="s in store.overview.sources" :key="s.id">
-              <td>{{ s.platform }}</td>
-              <td class="fc-artist__url">{{ s.url }}</td>
-              <td class="text-right">{{ s.image_count }}</td>
-            </tr>
-          </tbody>
-        </v-table>
-      </section>
+          <section v-if="store.overview.activity.length" class="fc-artist__sec">
+            <h2 class="fc-h2">Activity</h2>
+            <svg class="fc-artist__spark" :viewBox="`0 0 ${sparkW} ${sparkH}`"
+                 preserveAspectRatio="none" role="img" aria-label="posts over time">
+              <polyline :points="sparkPoints" fill="none"
+                        stroke="rgb(var(--v-theme-accent))" stroke-width="2" />
+            </svg>
+          </section>
 
-      <section class="fc-artist__sec">
-        <h2 class="fc-h2">Images</h2>
-        <MasonryGrid
-          :items="store.images"
-          :loading="store.imagesLoading"
-          :has-more="store.hasMoreImages"
-          @load-more="store.loadMoreImages(slug)"
-          @open="openImage"
-        />
-      </section>
+          <section v-if="store.overview.sources.length" class="fc-artist__sec">
+            <div class="fc-artist__sec-head">
+              <h2 class="fc-h2">Sources</h2>
+              <RouterLink
+                :to="`/subscriptions?artist_id=${store.overview.id}`"
+                class="fc-artist__manage"
+              >Manage subscriptions →</RouterLink>
+            </div>
+            <v-table density="compact">
+              <thead>
+                <tr><th>Platform</th><th>URL</th><th class="text-right">Images</th></tr>
+              </thead>
+              <tbody>
+                <tr v-for="s in store.overview.sources" :key="s.id">
+                  <td>{{ s.platform }}</td>
+                  <td class="fc-artist__url">{{ s.url }}</td>
+                  <td class="text-right">{{ s.image_count }}</td>
+                </tr>
+              </tbody>
+            </v-table>
+          </section>
 
-      <ArtistDangerZone
-        :slug="slug"
-        :artist-id="store.overview.id"
-        :artist-name="store.overview.name"
-      />
+          <section class="fc-artist__sec">
+            <h2 class="fc-h2">Images</h2>
+            <MasonryGrid
+              :items="store.images"
+              :loading="store.imagesLoading"
+              :has-more="store.hasMoreImages"
+              @load-more="store.loadMoreImages(slug)"
+              @open="openImage"
+            />
+          </section>
+        </v-window-item>
+
+        <v-window-item value="settings">
+          <ArtistDangerZone
+            :slug="slug"
+            :artist-id="store.overview.id"
+            :artist-name="store.overview.name"
+          />
+        </v-window-item>
+      </v-window>
     </template>
   </v-container>
 </template>
 
 <script setup>
-import { computed, watch } from 'vue'
+import { computed, ref, watch } from 'vue'
 import { useRoute, useRouter, RouterLink } from 'vue-router'
 import { useArtistStore } from '../stores/artist.js'
 import { useModalStore } from '../stores/modal.js'
@@ -120,8 +143,18 @@ const store = useArtistStore()
 const modal = useModalStore()
 
 const slug = computed(() => route.params.slug)
+// Per-artist tab — defaults to Overview. Settings tab hosts destructive
+// admin actions (DangerZone). Switching artists resets to Overview so the
+// destructive surface isn't re-shown by accident when navigating between
+// artists.
+const tab = ref('overview')
 
-watch(slug, (s) => { if (s) store.load(s) }, { immediate: true })
+watch(slug, (s) => {
+  if (s) {
+    store.load(s)
+    tab.value = 'overview'
+  }
+}, { immediate: true })
 
 const dateRange = computed(() => {
   const r = store.overview?.date_range

tests/test_importer_deep.py

@@ -64,9 +64,13 @@ def test_deep_rederives_phash_and_provenance(db_sync, import_layout):
 
     deep = _mk(db_sync, import_layout, deep=True)
     r2 = deep.import_one(src)
-    assert r2.status == "skipped"
-    assert "deep" in (r2.error or "")
+    # Outcome flipped from "skipped+duplicate_hash" to "refreshed" 2026-05-25
+    # so the UI can surface deep scan's actual work instead of showing it as
+    # a no-op. See ImportResult.status comment + _deep_rederive docstring.
+    assert r2.status == "refreshed"
     assert r2.image_id == rec.id
+    assert r2.skip_reason is None
+    assert r2.error is None
 
     db_sync.expire_all()
     rec2 = db_sync.get(ImageRecord, rec.id)

tests/test_phash_dedup.py

@@ -241,3 +241,9 @@ def test_import_task_maps_superseded_to_complete_and_requeues():
     assert _map_result_to_status(
         ImportResult(status="failed", error="boom")
     ) == ("failed", False)
+    # Refreshed (deep scan): complete + no ML/thumb re-derive (pixels
+    # unchanged). Added 2026-05-25 alongside ImportBatch.refreshed
+    # counter so deep scan reports "X refreshed" instead of "no work".
+    assert _map_result_to_status(
+        ImportResult(status="refreshed", image_id=5)
+    ) == ("complete", False)

tests/test_scan_deep_requeue.py

@@ -0,0 +1,109 @@
+"""Deep scan re-queues already-completed ImportTasks.
+
+Operator-flagged 2026-05-25: deep scan used to skip everything that
+already had a non-failed ImportTask row, making a deep re-scan a no-op
+when no new files were added. That defeated the entire point of deep
+scan (re-apply sidecar metadata to existing rows). The skip-set now
+splits by mode — quick keeps the old "any non-failed" semantics; deep
+skips ONLY actively-in-flight statuses.
+"""
+
+import pytest
+from PIL import Image
+from sqlalchemy import func, select
+
+from backend.app.models import ImportBatch, ImportSettings, ImportTask
+from backend.app.tasks.scan import scan_directory
+
+pytestmark = pytest.mark.integration
+
+
+def _img(path):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    Image.new("RGB", (40, 40), (10, 200, 80)).save(path, "JPEG")
+
+
+def test_deep_scan_requeues_completed_task(db_sync, tmp_path, monkeypatch):
+    """Quick scan then deep scan of the same /import: the file completed
+    in the first run should be re-enqueued by the deep run (different
+    ImportTask id, same source_path)."""
+    import_root = tmp_path / "import"
+    settings = db_sync.execute(
+        select(ImportSettings).where(ImportSettings.id == 1)
+    ).scalar_one()
+    settings.import_scan_path = str(import_root)
+    db_sync.commit()
+
+    src = import_root / "Mae" / "p.jpg"
+    _img(src)
+
+    from backend.app import celery_app
+
+    celery_app.celery.conf.task_always_eager = False  # explicit
+    try:
+        first_batch_id = scan_directory.run(triggered_by="manual", mode="quick")
+        first_task = db_sync.execute(
+            select(ImportTask).where(ImportTask.batch_id == first_batch_id)
+        ).scalar_one()
+        # Simulate the worker having finished it.
+        first_task.status = "complete"
+        db_sync.commit()
+
+        # Now deep scan: the SAME file should get a NEW ImportTask row.
+        second_batch_id = scan_directory.run(triggered_by="manual", mode="deep")
+        assert second_batch_id != first_batch_id
+
+        new_tasks_in_second_batch = db_sync.execute(
+            select(func.count())
+            .select_from(ImportTask)
+            .where(ImportTask.batch_id == second_batch_id)
+        ).scalar_one()
+        assert new_tasks_in_second_batch == 1, (
+            "deep scan did not re-queue the completed file"
+        )
+
+        # And the second batch's task should be for the same source_path
+        # as the first (proves it's a re-queue, not a different file).
+        sp = db_sync.execute(
+            select(ImportTask.source_path)
+            .where(ImportTask.batch_id == second_batch_id)
+        ).scalar_one()
+        assert sp == str(src)
+    finally:
+        celery_app.celery.conf.task_always_eager = False
+
+
+def test_quick_scan_does_not_requeue_completed_task(db_sync, tmp_path):
+    """The flip side: quick scan still keeps the old skip semantics —
+    a file with a completed ImportTask row from a prior batch is NOT
+    re-enqueued on a fresh quick scan."""
+    import_root = tmp_path / "import"
+    settings = db_sync.execute(
+        select(ImportSettings).where(ImportSettings.id == 1)
+    ).scalar_one()
+    settings.import_scan_path = str(import_root)
+    db_sync.commit()
+
+    src = import_root / "Mae" / "q.jpg"
+    _img(src)
+
+    first_batch_id = scan_directory.run(triggered_by="manual", mode="quick")
+    first_task = db_sync.execute(
+        select(ImportTask).where(ImportTask.batch_id == first_batch_id)
+    ).scalar_one()
+    first_task.status = "complete"
+    db_sync.commit()
+
+    second_batch_id = scan_directory.run(triggered_by="manual", mode="quick")
+    second_batch_count = db_sync.execute(
+        select(func.count())
+        .select_from(ImportTask)
+        .where(ImportTask.batch_id == second_batch_id)
+    ).scalar_one()
+    assert second_batch_count == 0, (
+        "quick scan re-queued an already-completed task — should have skipped"
+    )
+
+    # And the second batch should self-finalize (files_seen=0).
+    second_batch = db_sync.get(ImportBatch, second_batch_id)
+    assert second_batch.status == "complete"

tests/test_sidecar_util.py

@@ -23,6 +23,51 @@ def test_find_sidecar_none(tmp_path):
     assert find_sidecar(media) is None
 
 
+def test_find_sidecar_gallerydl_numbered_prefix(tmp_path):
+    """gallery-dl prefixes media filenames with NN_ for in-post ordering
+    (e.g. `01_HOLLOW-ICHIGO.png`) but writes the post-level sidecar under
+    the attachment stem WITHOUT the prefix (`HOLLOW-ICHIGO.json`).
+    Confirmed against real Patreon downloads 2026-05-26 — operator's deep
+    scan produced 24 refresh calls but 0 Posts because the unprefixed
+    sidecar was invisible to find_sidecar."""
+    media = tmp_path / "01_HOLLOW-ICHIGO.png"
+    media.write_bytes(b"x")
+    sc = tmp_path / "HOLLOW-ICHIGO.json"
+    sc.write_text("{}")
+    assert find_sidecar(media) == sc
+
+
+def test_find_sidecar_multidigit_prefix(tmp_path):
+    """Numbering prefix can be wider than 2 digits (`001_...`); the strip
+    handles any \\d+_ form."""
+    media = tmp_path / "001_mirko-sketch.png"
+    media.write_bytes(b"x")
+    sc = tmp_path / "mirko-sketch.json"
+    sc.write_text("{}")
+    assert find_sidecar(media) == sc
+
+
+def test_find_sidecar_prefers_attachment_level_over_post_level(tmp_path):
+    """If BOTH a per-attachment sidecar and a post-level sidecar exist,
+    the attachment-level one wins (it's more specific)."""
+    media = tmp_path / "01_image.png"
+    media.write_bytes(b"x")
+    per_attachment = tmp_path / "01_image.json"
+    per_attachment.write_text('{"specific": true}')
+    post_level = tmp_path / "image.json"
+    post_level.write_text('{"specific": false}')
+    assert find_sidecar(media) == per_attachment
+
+
+def test_find_sidecar_no_underscore_not_treated_as_prefix(tmp_path):
+    """`01.png` (just digits, no underscore-separated stem) shouldn't
+    match. The regex requires NN_<something>."""
+    media = tmp_path / "01.png"
+    media.write_bytes(b"x")
+    (tmp_path / ".json").write_text("{}")  # would be matched only if buggy
+    assert find_sidecar(media) is None
+
+
 def test_parse_empty_dict_all_none():
     sd = parse_sidecar({})
     assert isinstance(sd, SidecarData)