Implement family dataspace onboarding

docs/examples.md

@@ -66,3 +66,40 @@ operation. Outbox consumers should treat `event_id` as the delivery id and
 for event in service.outbox_events():
     print(event.event_type, event.aggregate_id, event.correlation_id)
 ```
+
+## Onboard A Family Dataspace
+
+```python
+from user_engine.domain import FamilyDataspaceRequest, FamilyMemberSpec, FamilyRole
+
+owner = service.me(owner_claims, correlation_id="corr-owner")
+onboarding = service.onboard_family_dataspace(
+    owner.actor,
+    FamilyDataspaceRequest(
+        tenant="tenant:worsch-family",
+        family_scope_id="family:worsch",
+        family_display_name="Worsch Family",
+        application_id="app.personal-dataspace",
+        oidc_client_id="personal-dataspace-client",
+        protected_system_id="dataspace.personal.worsch",
+        member_specs=(
+            FamilyMemberSpec(
+                primary_email="child@example.test",
+                display_name="Child Member",
+                role=FamilyRole.CHILD,
+            ),
+        ),
+    ),
+    correlation_id="corr-family-onboard",
+)
+
+accepted = service.accept_family_invitation(
+    child_claims,
+    onboarding.invitations[0].invitation.invitation_id,
+    correlation_id="corr-child-accept",
+)
+```
+
+`accepted.identity_context` is the canon-facing context for the SSO adapter.
+`accepted.claims_projection` is the application-visible profile projection for
+the personal dataspace.