Publish curated Ludarium source from e15d06f97e5204dd853ef3d25e326d8c6d49936f

.gitea/workflows/public-validation.yml

@@ -11,7 +11,7 @@ jobs:
   source:
     name: source
     if: ${{ gitea.event_name != 'pull_request' || gitea.event.pull_request.head.repo.full_name == gitea.repository }}
-    runs-on: ubuntu-latest
+    runs-on: linux-validation
     timeout-minutes: 45
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

README.md

@@ -1,5 +1,8 @@
 # Ludarium
 
+<p align="center"><strong>Your game archive, searchable and accountable.</strong></p>
+<p align="center"><a href="#explore-the-interface">Interface</a> · <a href="#what-you-can-do">Features</a> · <a href="#quick-start">Quick start</a> · <a href="#architecture">Architecture</a></p>
+
 **A local-first, self-hosted catalog for game archives.** Ludarium turns read-only folders of ROMs,
 disc images and archived Windows installers into a searchable library with provenance, integrity
 evidence and an explicit review queue. It is built for Unraid, but the supplied Compose deployment
@@ -7,6 +10,14 @@ also works on a regular Docker host.
 
 ![Ludarium home screen with an empty, privacy-safe example archive](docs/screenshots/living-archive-audit/audit-home-desktop.png)
 
+## Explore the interface
+
+These captures show a deliberately empty, privacy-safe example archive. Your own files and metadata appear only after you add read-only library mounts and scan them.
+
+| Searchable library | Review queue |
+| --- | --- |
+| ![Ludarium library without imported private files](docs/screenshots/living-archive-audit/audit-library-desktop.png) | ![Ludarium review queue](docs/screenshots/living-archive-audit/audit-attention-desktop.png) |
+
 ## What you can do
 
 - discover and fingerprint files without renaming, moving or executing them;
@@ -65,6 +76,25 @@ for the content you index and for complying with the rules that apply to it.
   no credentials are configured.
 - Report vulnerabilities privately using [`SECURITY.md`](SECURITY.md).
 
+## Architecture
+
+```mermaid
+flowchart LR
+    Libraries[Read-only archive mounts] --> Scanner[Inventory and fingerprints]
+    Scanner --> Review[Explicit review queue]
+    Review --> Catalog[(PostgreSQL catalog)]
+    Catalog --> Web[React library and collections]
+    Catalog --> Exports[Portable catalog exports]
+```
+
+The cataloging pipeline only reads mounted source libraries. PostgreSQL stores identities, provenance, collections and review state; cache, exports and optional player data use separate writable locations. This separation lets you re-scan or restore the catalog without changing original game files.
+
+## When an archive appears empty
+
+Check the container's read-only library mounts and file permissions, then inspect scan progress and the reported format confidence. A mounted directory can be accessible without containing a recognized game format. Review uncertain candidates before correcting metadata or resolving duplicate groups.
+
+Preserve manual decisions and application state during upgrades. Keep a backup of the catalog in addition to the original archive: rescanning source files does not recreate your notes, collections and review decisions. Exporting a launcher catalog does not grant rights to redistribute its games or binaries.
+
 ## Development
 
 The backend targets .NET 10, the UI uses React 19 and Vite, and controller helpers use Python's standard

public-source.allowlist

@@ -43,6 +43,8 @@ deploy/verify-release-identity.sh
 deploy/verify-source-manifest.sh
 docs/PUBLIC_SOURCE_BOUNDARY.md
 docs/screenshots/living-archive-audit/audit-home-desktop.png
+docs/screenshots/living-archive-audit/audit-library-desktop.png
+docs/screenshots/living-archive-audit/audit-attention-desktop.png
 fixtures/**
 global.json
 public-source.allowlist