Add README.md files for web-app-bookwyrm, web-app-postmarks, and web-app-socialhome roles

Introduce integration test to ensure all web-app-* roles contain a README.md (required for Web App Desktop visibility)

See: https://chatgpt.com/share/68b6be49-7b78-800f-a3ff-bf922b4b083f

roles/web-app-bookwyrm/README.md

@@ -0,0 +1,25 @@
+# BookWyrm
+
+## Description
+
+Host your own social reading platform with **BookWyrm**. This role deploys BookWyrm via Docker Compose, wires domains and ports, and offers optional OIDC integration so your readers can sign in through your central identity provider.
+
+## Overview
+
+This role provisions a BookWyrm application stack with Docker. It supports PostgreSQL and Redis, sets sensible environment defaults, and exposes an application container plus a dedicated Celery worker. A reverse proxy (provided elsewhere in your stack) fronts the service for public access.
+
+## Features
+
+- **Fully Dockerized Deployment:** Builds and runs BookWyrm containers (app + worker) using Docker Compose.
+- **Production-friendly Settings:** Environment templating for database, Redis, and security-relevant settings (e.g., `SECRET_KEY`).
+- **Optional OIDC:** Can integrate with your OIDC provider (e.g., Keycloak) directly or behind oauth2-proxy (depending on your flavor).
+- **Volumes for Data & Media:** Persistent volumes for BookWyrm data and media assets.
+- **Redis & Celery Worker:** Background tasks processed by Celery; Redis used for broker and cache.
+- **Desktop Integration Hooks:** Compatible with your Web App Desktop listing when the role includes this README.
+- **Matomo/CSS/Desktop Flags:** Standard feature flags are available for consistent theming/analytics across apps in your ecosystem.
+
+## Further Resources
+
+- [BookWyrm (GitHub)](https://github.com/bookwyrm-social/bookwyrm)
+- [BookWyrm Documentation](https://docs.joinbookwyrm.com/)
+- [OpenID Connect (Wikipedia)](https://en.wikipedia.org/wiki/OpenID_Connect)

roles/web-app-postmarks/README.md

@@ -0,0 +1,21 @@
+# Postmarks
+
+## Description
+
+Run **Postmarks**, a small mail-service client, via Docker Compose—ideal as a utility component for apps that need SMTP interactions in your stack.
+
+## Overview
+
+This role installs and configures the Postmarks client container with basic domain wiring. It is designed to run behind your standard reverse proxy and to interoperate with other applications that rely on SMTP functionality.
+
+## Features
+
+- **Containerized Client:** Simple Docker Compose deployment for the Postmarks tool.
+- **SMTP-Oriented Usage:** Suited for scenarios where applications need to interact with a mail service.
+- **Minimal Footprint:** Small, focused utility component that fits neatly into larger stacks.
+- **Desktop Integration Hooks:** This README ensures the role is discoverable in your Web App Desktop.
+
+## Further Resources
+
+- [Postmarks (GitHub)](https://github.com/ckolderup/postmarks)
+- [Simple Mail Transfer Protocol (RFC 5321)](https://www.rfc-editor.org/rfc/rfc5321)

roles/web-app-socialhome/README.md

@@ -0,0 +1,22 @@
+# SocialHome
+
+## Description
+
+Deploy **SocialHome**, a federated social network focused on content hubs and federation. This role provides a Docker-based scaffold and domain wiring so you can bring SocialHome into your Infinito.Nexus stack.
+
+## Overview
+
+This role sets up a SocialHome application using Docker Compose with basic domain and port wiring. It follows your standard role layout and prepares the service to run behind your existing reverse proxy. The current version is a scaffold intended to be expanded with database/cache services and app-specific settings.
+
+## Features
+
+- **Dockerized Scaffold:** Baseline Docker Compose integration and role structure to get you started quickly.
+- **Domain & Port Wiring:** Integrates cleanly with your central domain/ports configuration.
+- **Ready for Federation:** Intended to support ActivityPub-based federation once the application is fully wired.
+- **Extensible Configuration:** Room for adding database, cache, worker processes, and environment tuning.
+- **Desktop Integration Hooks:** This README ensures inclusion in the Web App Desktop overview.
+
+## Further Resources
+
+- [SocialHome Project](https://socialhome.network/)
+- [ActivityPub (W3C)](https://www.w3.org/TR/activitypub/)

tests/integration/test_web_app_roles_have_readme.py

@@ -0,0 +1,66 @@
+import unittest
+from pathlib import Path
+from typing import List, Optional
+
+
+def find_repo_root(start: Path) -> Optional[Path]:
+    """
+    Walk up from `start` until we find a directory containing 'roles'.
+    Returns the repo root (the directory that contains 'roles') or None.
+    """
+    for parent in [start] + list(start.parents):
+        if (parent / "roles").is_dir():
+            return parent
+    return None
+
+
+def web_app_role_dirs(root: Path) -> List[Path]:
+    """Return all role directories that match roles/web-app-*."""
+    roles_dir = root / "roles"
+    return sorted([p for p in roles_dir.glob("web-app-*") if p.is_dir()])
+
+
+class TestWebAppRolesHaveReadme(unittest.TestCase):
+    """
+    Ensures every role under roles/web-app-* contains a README.md.
+
+    Why: The README is required for the role to be shown in the Web App Desktop.
+    """
+
+    @classmethod
+    def setUpClass(cls):
+        here = Path(__file__).resolve()
+        repo_root = find_repo_root(here.parent)
+        if repo_root is None:
+            raise RuntimeError(
+                f"Could not locate the repository root from {here}. "
+                "Expected to find a 'roles/' directory in one of the parent folders."
+            )
+        cls.repo_root = repo_root
+        cls.roles = web_app_role_dirs(repo_root)
+
+    def test_roles_directory_present(self):
+        self.assertTrue(
+            (self.repo_root / "roles").is_dir(),
+            f"'roles' directory not found at: {self.repo_root}",
+        )
+
+    def test_every_web_app_role_has_readme(self):
+        missing = []
+        for role_dir in self.roles:
+            with self.subTest(role=role_dir.name):
+                readme = role_dir / "README.md"
+                if not readme.is_file():
+                    missing.append(role_dir)
+
+        if missing:
+            formatted = "\n".join(f"- {p.relative_to(self.repo_root)}" for p in missing)
+            self.fail(
+                "The following roles are missing a README.md:\n"
+                f"{formatted}\n\n"
+                "A README.md is required so the role can be displayed in the Web App Desktop."
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()