chore: add mailing list dev seed and docs (CM-1318)

Signed-off-by: Uroš Marolt <uros@marolt.me>

Author: themarolt

services/apps/mailing_list_integration/README.md

@@ -4,8 +4,8 @@ Ingests public mailing lists (e.g. lore.kernel.org / LKML-style) into CDP,
 following the same worker pattern as `services/apps/git_integration`:
 FastAPI lifespan + async poll worker + asyncpg + aiokafka.
 
-Status: under construction (CM-1318). See the plan/step tracker referenced
-in the PR for build progress.
+Status: hardcoded lists only, no onboarding UI (CM-1318). See the plan/step
+tracker referenced in the PR for build progress.
 
 ## Architecture (planned)
 
@@ -33,3 +33,43 @@ endpoint on host port `8086`.
 
 Other targets: `make lint`, `make format`, `make test`, `make rebuild`. See
 `make help` for the full list.
+
+## Onboarding a list (dev, hardcoded)
+
+There is no UI yet — a list is onboarded by inserting its rows directly.
+`dev/seed.sql` does this for one example list (`lore.kernel.org/git`):
+
+```bash
+psql "$CROWD_DB_WRITE_URI" -f dev/seed.sql
+```
+
+It creates a `public.integrations` row (`platform='groupsio'`), a
+`mailinglist.lists` row pointing at an existing segment, and a
+`mailinglist."listProcessing"` row in state `pending` — which the worker's
+`acquire_onboarding_list()` will pick up on its next poll. Edit the `name`
+and `"sourceUrl"` values in the file to onboard a different lore list.
+
+## End-to-end verification
+
+1. Apply `backend/src/database/migrations/V1784048135__mailinglist-schema.sql`
+   and run `dev/seed.sql` against the target Postgres.
+2. Start Kafka and a `data_sink_worker` consumer on the `data-sink-worker` topic.
+3. `make run` (or `uv run uvicorn crowdmail.server:app`) — worker polls, mirrors
+   the seeded list via `public-inbox-clone`, parses new commits, and:
+   - inserts rows into `integration.results` with `state='pending'` and
+     `data.type='activity'`,
+   - emits one Kafka message per result (`process_integration_result`,
+     `platform=groupsio`),
+   - advances `mailinglist."listProcessing"."lastProcessedHeads"` and sets
+     `state='completed'`.
+4. Confirm `data_sink_worker` consumes the message, resolves the integration's
+   `platform='groupsio'`, and creates the member (email-based verified
+   `username`+`email` identities) and activity.
+5. `GET http://localhost:8086/` returns the FastAPI health check.
+
+## Out of scope (CM-1318)
+
+- Onboarding UI/backend to create `integrations` + `mailinglist.lists` rows
+  (this is what `dev/seed.sql` stands in for).
+- Whether `member_join`/`member_leave` activities are derivable from lore, or
+  only `message` initially.

services/apps/mailing_list_integration/dev/seed.sql

@@ -0,0 +1,45 @@
+-- Dev seed: one hardcoded mailing list (CM-1318), no onboarding UI yet.
+-- Run against a local CDP postgres. Picks an arbitrary existing segment —
+-- replace the subquery with a real segmentId for anything beyond local testing.
+
+BEGIN;
+
+WITH target_segment AS (
+    SELECT id AS "segmentId" FROM segments ORDER BY "createdAt" LIMIT 1
+),
+new_integration AS (
+    INSERT INTO public.integrations (
+        id, platform, status, settings, "tenantId", "createdAt", "updatedAt"
+    )
+    SELECT
+        uuid_generate_v4(),
+        'groupsio',
+        'done',
+        '{}'::jsonb,
+        '875c38bd-2b1b-4e91-ad07-0cfbabb4c49f', -- DEFAULT_TENANT_ID
+        NOW(),
+        NOW()
+    RETURNING id AS "integrationId"
+),
+new_list AS (
+    INSERT INTO mailinglist.lists (
+        id, name, "sourceUrl", "segmentId", "integrationId", "createdAt", "updatedAt"
+    )
+    SELECT
+        uuid_generate_v4(),
+        'kernel/git',
+        'https://lore.kernel.org/git',
+        target_segment."segmentId",
+        new_integration."integrationId",
+        NOW(),
+        NOW()
+    FROM target_segment, new_integration
+    RETURNING id AS "listId"
+)
+INSERT INTO mailinglist."listProcessing" (
+    "listId", state, priority, "lastProcessedHeads", "createdAt", "updatedAt"
+)
+SELECT "listId", 'pending', 2, '{}'::jsonb, NOW(), NOW()
+FROM new_list;
+
+COMMIT;