Merge pull request 'Model providers: OpenAI/xAI/Ollama + run several at once' (#237) from multi-provider-openai-xai-ollama into main

Extends the #215 abstraction:
- OpenAICompatibleLLMProvider / OpenAICompatibleEmbeddingProvider — one impl (via
  the official openai SDK) covers OpenAI, xAI (api.x.ai/v1), Ollama
  (…:11434/v1), OpenRouter, etc.; they differ only by base_url, key, and model.
- Registry factory: build_llm_providers() / build_embedding_providers() return
  every provider whose credentials are configured, so you can run several
  concurrently. get_llm_provider(name)/get_embedding_provider(name) select by
  name, falling back to default_*_provider, then Null.
- Per-provider env config (ANTHROPIC_*, OPENAI_*, XAI_*, OLLAMA_*) +
  DEFAULT_LLM_PROVIDER / DEFAULT_EMBEDDING_PROVIDER; documented in .env.example.
  Defaults keep AI off (empty registry).

Embeddings now have real backends (OpenAI/Ollama), still separate from the LLM
since Anthropic offers no embeddings endpoint. Tests cover multi-provider
selection, default resolution, disabled-without-credentials, and null fail-loud.
Full suite 87 passed.

Relates to #215.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Justin Paul <justin@jpaul.me>

CLAUDE.md

@@ -19,6 +19,7 @@ These are product invariants, not preferences. Do not violate them, and flag any
 5. **Sources are first-class.** Don't model citations as free-text afterthoughts. A `Source` is a reusable entity; a `Citation` links it to a specific fact.
 6. **Only legal data sources.** Ship scrapers/connectors only for permissible sources (FamilySearch API, Find A Grave, WikiTree, BLM/GLO, USGS, public-domain newspapers, public county records). Never add connectors for paywalled/terms-prohibited sites (Ancestry, MyHeritage, 23andMe).
 7. **Everything is configurable via environment.** Auth, mail, object storage, database, model providers, scrapers — all twelve-factor. No hard-coded endpoints or keys.
+8. **Full CRUD on every object.** Every stored entity (person, name, event, relationship, source, citation, media, tree, …) must support create, read, **update**, and delete — in the API *and* the UI. Historical research is constant correction and new information, so nothing is write-once. Any new feature or data type ships with all four operations; an entity you can create but not edit is a bug.
 
 ## Tech stack
 

backend/Dockerfile

@@ -21,7 +21,11 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 COPY app ./app
 COPY alembic.ini ./alembic.ini
 COPY migrations ./migrations
+COPY docker-entrypoint.sh ./docker-entrypoint.sh
+RUN chmod +x ./docker-entrypoint.sh
 
 EXPOSE 8000
 
+# The entrypoint runs migrations first when RUN_MIGRATIONS=1, then the command.
+ENTRYPOINT ["./docker-entrypoint.sh"]
 CMD ["uv", "run", "--no-dev", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/app/api/deps.py

@@ -10,6 +10,8 @@ from app.core.db import get_session
 from app.integrations.mailer.base import Mailer
 from app.integrations.mailer.console import ConsoleMailer
 from app.integrations.mailer.smtp import SMTPMailer
+from app.integrations.models.base import EmbeddingProvider, LLMProvider
+from app.integrations.models.null import NullEmbeddingProvider, NullLLMProvider
 from app.integrations.objectstore.base import ObjectStore
 from app.integrations.objectstore.s3 import S3ObjectStore
 from app.models.user import User
@@ -40,6 +42,18 @@ async def get_current_user(request: Request, session: SessionDep) -> User:
 CurrentUser = Annotated[User, Depends(get_current_user)]
 
 
+async def get_current_user_or_none(request: Request, session: SessionDep) -> User | None:
+    """Optional auth for public read endpoints — never raises. Returns the user
+    when a valid session is present, else None (anonymous viewer)."""
+    raw_token = extract_session_token(request)
+    if raw_token is None:
+        return None
+    return await auth_service.resolve_session_user(session, raw_token=raw_token)
+
+
+CurrentUserOrNone = Annotated[User | None, Depends(get_current_user_or_none)]
+
+
 def get_mailer() -> Mailer:
     settings = get_settings()
     if settings.mailer == "smtp" and settings.smtp_host:
@@ -55,3 +69,68 @@ def get_objectstore() -> ObjectStore:
 
 
 ObjectStoreDep = Annotated[ObjectStore, Depends(get_objectstore)]
+
+
+def build_llm_providers() -> dict[str, LLMProvider]:
+    """Every LLM provider whose credentials are configured, keyed by name. Run
+    several at once; pick one with get_llm_provider(name)."""
+    from app.integrations.models.anthropic_provider import AnthropicLLMProvider
+    from app.integrations.models.openai_compat import OpenAICompatibleLLMProvider
+
+    s = get_settings()
+    providers: dict[str, LLMProvider] = {}
+    if s.anthropic_api_key:
+        providers["anthropic"] = AnthropicLLMProvider(
+            api_key=s.anthropic_api_key, model=s.anthropic_model, max_tokens=s.llm_max_tokens
+        )
+    if s.openai_api_key:
+        providers["openai"] = OpenAICompatibleLLMProvider(
+            api_key=s.openai_api_key, base_url=s.openai_base_url, model=s.openai_model,
+            max_tokens=s.llm_max_tokens,
+        )
+    if s.xai_api_key:
+        providers["xai"] = OpenAICompatibleLLMProvider(
+            api_key=s.xai_api_key, base_url=s.xai_base_url, model=s.xai_model,
+            max_tokens=s.llm_max_tokens,
+        )
+    if s.ollama_enabled:
+        providers["ollama"] = OpenAICompatibleLLMProvider(
+            api_key=None, base_url=s.ollama_base_url, model=s.ollama_model,
+            max_tokens=s.llm_max_tokens,
+        )
+    return providers
+
+
+def get_llm_provider(name: str | None = None) -> LLMProvider:
+    """The named LLM provider, or the configured default, or Null if unconfigured."""
+    providers = build_llm_providers()
+    return providers.get(name or get_settings().default_llm_provider) or NullLLMProvider()
+
+
+LLMProviderDep = Annotated[LLMProvider, Depends(get_llm_provider)]
+
+
+def build_embedding_providers() -> dict[str, EmbeddingProvider]:
+    from app.integrations.models.openai_compat import OpenAICompatibleEmbeddingProvider
+
+    s = get_settings()
+    providers: dict[str, EmbeddingProvider] = {}
+    if s.openai_api_key:
+        providers["openai"] = OpenAICompatibleEmbeddingProvider(
+            api_key=s.openai_api_key, base_url=s.openai_base_url,
+            model=s.openai_embedding_model, dimensions=s.embedding_dimensions,
+        )
+    if s.ollama_enabled:
+        providers["ollama"] = OpenAICompatibleEmbeddingProvider(
+            api_key=None, base_url=s.ollama_base_url,
+            model=s.ollama_embedding_model, dimensions=s.embedding_dimensions,
+        )
+    return providers
+
+
+def get_embedding_provider(name: str | None = None) -> EmbeddingProvider:
+    providers = build_embedding_providers()
+    return providers.get(name or get_settings().default_embedding_provider) or NullEmbeddingProvider()
+
+
+EmbeddingProviderDep = Annotated[EmbeddingProvider, Depends(get_embedding_provider)]

backend/app/api/v1/__init__.py

@@ -5,10 +5,15 @@ from fastapi import APIRouter
 from app.api.v1 import (
     auth,
     citations,
+    cleanup,
     events,
     gedcom,
     media,
+    members,
+    names,
     persons,
+    proposals,
+    public,
     relationships,
     sources,
     trees,
@@ -20,9 +25,14 @@ api_router.include_router(auth.router)
 api_router.include_router(users.router)
 api_router.include_router(trees.router)
 api_router.include_router(persons.router)
+api_router.include_router(names.router)
 api_router.include_router(events.router)
 api_router.include_router(relationships.router)
 api_router.include_router(sources.router)
 api_router.include_router(citations.router)
 api_router.include_router(media.router)
 api_router.include_router(gedcom.router)
+api_router.include_router(cleanup.router)
+api_router.include_router(public.router)
+api_router.include_router(members.router)
+api_router.include_router(proposals.router)

backend/app/api/v1/auth.py

@@ -1,9 +1,10 @@
 from fastapi import APIRouter, HTTPException, Request, Response, status
 
-from app.api.deps import MailerDep, SessionDep, extract_session_token
+from app.api.deps import CurrentUser, MailerDep, SessionDep, extract_session_token
 from app.core.config import get_settings
 from app.schemas.auth import (
     LoginRequest,
+    PasswordChange,
     PasswordResetConfirm,
     PasswordResetRequest,
     RegisterRequest,
@@ -79,3 +80,15 @@ async def reset_password(data: PasswordResetConfirm, session: SessionDep) -> Non
     await auth_service.reset_password(
         session, raw_token=data.token, new_password=data.new_password
     )
+
+
+@router.post("/change-password", status_code=status.HTTP_204_NO_CONTENT)
+async def change_password(
+    data: PasswordChange, session: SessionDep, current: CurrentUser
+) -> None:
+    await auth_service.change_password(
+        session,
+        user=current,
+        current_password=data.current_password,
+        new_password=data.new_password,
+    )

backend/app/api/v1/citations.py

@@ -3,7 +3,7 @@ import uuid
 from fastapi import APIRouter, status
 
 from app.api.deps import CurrentUser, SessionDep
-from app.schemas.source import CitationCreate, CitationRead
+from app.schemas.source import CitationCreate, CitationRead, CitationUpdate
 from app.services import citation_service, tree_service
 
 router = APIRouter(prefix="/trees", tags=["citations"])
@@ -31,6 +31,25 @@ async def list_citations(
     return [CitationRead.model_validate(c) for c in citations]
 
 
+@router.patch("/{tree_id}/citations/{citation_id}", response_model=CitationRead)
+async def update_citation(
+    tree_id: uuid.UUID,
+    citation_id: uuid.UUID,
+    data: CitationUpdate,
+    session: SessionDep,
+    current: CurrentUser,
+) -> CitationRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    citation = await citation_service.update_citation(
+        session,
+        actor=current,
+        tree=tree,
+        citation_id=citation_id,
+        changes=data.model_dump(exclude_unset=True),
+    )
+    return CitationRead.model_validate(citation)
+
+
 @router.delete("/{tree_id}/citations/{citation_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_citation(
     tree_id: uuid.UUID, citation_id: uuid.UUID, session: SessionDep, current: CurrentUser

backend/app/api/v1/cleanup.py

@@ -0,0 +1,111 @@
+import uuid
+
+from fastapi import APIRouter, File, UploadFile
+
+from app.api.deps import CurrentUser, SessionDep
+from app.schemas.cleanup import (
+    CleanupResult,
+    DeceasedApply,
+    DeceasedCandidate,
+    GenderApply,
+    GenderProposal,
+    NameApply,
+    NameIssue,
+)
+from app.services import cleanup_service, tree_service
+
+router = APIRouter(prefix="/trees", tags=["cleanup"])
+
+
+@router.get("/{tree_id}/cleanup/deceased", response_model=list[DeceasedCandidate])
+async def preview_deceased(
+    tree_id: uuid.UUID,
+    session: SessionDep,
+    current: CurrentUser,
+    born_on_or_before: int = 1930,
+) -> list[DeceasedCandidate]:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    rows = await cleanup_service.preview_deceased(
+        session, actor=current, tree=tree, year=born_on_or_before
+    )
+    return [DeceasedCandidate(**r) for r in rows]
+
+
+@router.post("/{tree_id}/cleanup/deceased", response_model=CleanupResult)
+async def apply_deceased(
+    tree_id: uuid.UUID, data: DeceasedApply, session: SessionDep, current: CurrentUser
+) -> CleanupResult:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    n = await cleanup_service.apply_deceased(
+        session, actor=current, tree=tree, person_ids=data.person_ids
+    )
+    return CleanupResult(updated=n)
+
+
+@router.post("/{tree_id}/cleanup/gender/preview", response_model=list[GenderProposal])
+async def preview_gender(
+    tree_id: uuid.UUID,
+    session: SessionDep,
+    current: CurrentUser,
+    file: UploadFile = File(...),
+) -> list[GenderProposal]:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    text = (await file.read()).decode("utf-8", errors="replace")
+    rows = await cleanup_service.preview_gender(
+        session, actor=current, tree=tree, gedcom_text=text
+    )
+    return [GenderProposal(**r) for r in rows]
+
+
+@router.get("/{tree_id}/cleanup/gender/guess", response_model=list[GenderProposal])
+async def guess_gender(
+    tree_id: uuid.UUID, session: SessionDep, current: CurrentUser
+) -> list[GenderProposal]:
+    """Best-guess sex from first names (bundled dictionary) for people missing it."""
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    rows = await cleanup_service.guess_gender_by_name(session, actor=current, tree=tree)
+    return [GenderProposal(**r) for r in rows]
+
+
+@router.get("/{tree_id}/cleanup/gender/from-spouse", response_model=list[GenderProposal])
+async def guess_gender_from_spouse(
+    tree_id: uuid.UUID, session: SessionDep, current: CurrentUser
+) -> list[GenderProposal]:
+    """Infer a missing sex from a partner whose sex is set (opposite-sex couple)."""
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    rows = await cleanup_service.guess_gender_by_spouse(session, actor=current, tree=tree)
+    return [GenderProposal(**r) for r in rows]
+
+
+@router.post("/{tree_id}/cleanup/gender", response_model=CleanupResult)
+async def apply_gender(
+    tree_id: uuid.UUID, data: GenderApply, session: SessionDep, current: CurrentUser
+) -> CleanupResult:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    n = await cleanup_service.apply_gender(
+        session,
+        actor=current,
+        tree=tree,
+        updates=[u.model_dump() for u in data.updates],
+    )
+    return CleanupResult(updated=n)
+
+
+@router.get("/{tree_id}/cleanup/names", response_model=list[NameIssue])
+async def preview_names(
+    tree_id: uuid.UUID, session: SessionDep, current: CurrentUser
+) -> list[NameIssue]:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    rows = await cleanup_service.preview_names(session, actor=current, tree=tree)
+    return [NameIssue(**r) for r in rows]
+
+
+@router.post("/{tree_id}/cleanup/names", response_model=CleanupResult)
+async def apply_names(
+    tree_id: uuid.UUID, data: NameApply, session: SessionDep, current: CurrentUser
+) -> CleanupResult:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    n = await cleanup_service.apply_names(
+        session, actor=current, tree=tree, edits=[e.model_dump() for e in data.edits]
+    )
+    return CleanupResult(updated=n)

backend/app/api/v1/events.py

@@ -3,7 +3,7 @@ import uuid
 from fastapi import APIRouter, status
 
 from app.api.deps import CurrentUser, SessionDep
-from app.schemas.event import EventCreate, EventRead
+from app.schemas.event import EventCreate, EventRead, EventUpdate
 from app.services import event_service, tree_service
 
 router = APIRouter(prefix="/trees", tags=["events"])
@@ -40,6 +40,25 @@ async def list_person_events(
     return [EventRead.model_validate(e) for e in events]
 
 
+@router.patch("/{tree_id}/events/{event_id}", response_model=EventRead)
+async def update_event(
+    tree_id: uuid.UUID,
+    event_id: uuid.UUID,
+    data: EventUpdate,
+    session: SessionDep,
+    current: CurrentUser,
+) -> EventRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    event = await event_service.update_event(
+        session,
+        actor=current,
+        tree=tree,
+        event_id=event_id,
+        changes=data.model_dump(exclude_unset=True),
+    )
+    return EventRead.model_validate(event)
+
+
 @router.delete("/{tree_id}/events/{event_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_event(
     tree_id: uuid.UUID, event_id: uuid.UUID, session: SessionDep, current: CurrentUser

backend/app/api/v1/gedcom.py

@@ -1,25 +1,56 @@
+import json
 import uuid
 
-from fastapi import APIRouter, File, Response, UploadFile
+from fastapi import APIRouter, File, Form, Response, UploadFile
 
 from app.api.deps import CurrentUser, SessionDep
-from app.schemas.gedcom import ImportReport
+from app.schemas.gedcom import ImportPreview, ImportReport
 from app.services import gedcom, tree_service
 
 router = APIRouter(prefix="/trees", tags=["gedcom"])
 
 
+@router.post("/{tree_id}/gedcom/preview", response_model=ImportPreview)
+async def preview_gedcom(
+    tree_id: uuid.UUID,
+    session: SessionDep,
+    current: CurrentUser,
+    file: UploadFile = File(...),
+) -> ImportPreview:
+    """Dry run: report counts and incoming people that look like duplicates of
+    existing ones, so the user can choose how to resolve each before importing."""
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    text = (await file.read()).decode("utf-8", errors="replace")
+    report = await gedcom.preview_gedcom(session, actor=current, tree=tree, text=text)
+    return ImportPreview(**report)
+
+
 @router.post("/{tree_id}/gedcom/import", response_model=ImportReport)
 async def import_gedcom(
     tree_id: uuid.UUID,
     session: SessionDep,
     current: CurrentUser,
     file: UploadFile = File(...),
+    default_action: str = Form("new"),
+    resolutions: str = Form("{}"),
 ) -> ImportReport:
-    # NOTE: additive — records are created as new; existing people are not merged.
+    """Import a GEDCOM. ``default_action`` (new|skip|merge|overwrite) applies to
+    incoming people that match an existing one; ``resolutions`` is a JSON object
+    {xref: {action, target_id}} overriding it per record."""
     tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
     text = (await file.read()).decode("utf-8", errors="replace")
-    report = await gedcom.import_gedcom(session, actor=current, tree=tree, text=text)
+    try:
+        parsed = json.loads(resolutions or "{}")
+    except json.JSONDecodeError:
+        parsed = {}
+    report = await gedcom.import_gedcom(
+        session,
+        actor=current,
+        tree=tree,
+        text=text,
+        default_action=default_action,
+        resolutions=parsed,
+    )
     return ImportReport(**report)
 
 

backend/app/api/v1/media.py

@@ -3,7 +3,7 @@ import uuid
 from fastapi import APIRouter, File, Form, Response, UploadFile, status
 
 from app.api.deps import CurrentUser, ObjectStoreDep, SessionDep
-from app.schemas.media import MediaRead
+from app.schemas.media import MediaRead, MediaUpdate
 from app.services import media_service, tree_service
 
 
@@ -81,6 +81,26 @@ async def media_content(
     )
 
 
+@router.patch("/{tree_id}/media/{media_id}", response_model=MediaRead)
+async def update_media(
+    tree_id: uuid.UUID,
+    media_id: uuid.UUID,
+    data: MediaUpdate,
+    session: SessionDep,
+    current: CurrentUser,
+    store: ObjectStoreDep,
+) -> MediaRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    media = await media_service.update_media(
+        session,
+        actor=current,
+        tree=tree,
+        media_id=media_id,
+        changes=data.model_dump(exclude_unset=True),
+    )
+    return _read(media)
+
+
 @router.delete("/{tree_id}/media/{media_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_media(
     tree_id: uuid.UUID, media_id: uuid.UUID, session: SessionDep, current: CurrentUser

backend/app/api/v1/members.py

@@ -0,0 +1,61 @@
+"""Tree membership management endpoints (owner-managed; members can list)."""
+
+import uuid
+
+from fastapi import APIRouter, status
+
+from app.api.deps import CurrentUser, SessionDep
+from app.schemas.membership import MemberAdd, MemberRoleUpdate, MembershipRead
+from app.services import membership_service, tree_service
+
+router = APIRouter(prefix="/trees", tags=["members"])
+
+
+@router.get("/{tree_id}/members", response_model=list[MembershipRead])
+async def list_members(
+    tree_id: uuid.UUID, session: SessionDep, current: CurrentUser
+) -> list[MembershipRead]:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    rows = await membership_service.list_members(session, viewer_id=current.id, tree=tree)
+    return [MembershipRead(**r) for r in rows]
+
+
+@router.post(
+    "/{tree_id}/members", response_model=MembershipRead, status_code=status.HTTP_201_CREATED
+)
+async def add_member(
+    tree_id: uuid.UUID, data: MemberAdd, session: SessionDep, current: CurrentUser
+) -> MembershipRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    row = await membership_service.add_member(
+        session, actor=current, tree=tree, email=data.email, role=data.role
+    )
+    return MembershipRead(**row)
+
+
+@router.patch("/{tree_id}/members/{membership_id}", response_model=MembershipRead)
+async def update_member(
+    tree_id: uuid.UUID,
+    membership_id: uuid.UUID,
+    data: MemberRoleUpdate,
+    session: SessionDep,
+    current: CurrentUser,
+) -> MembershipRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    row = await membership_service.update_member_role(
+        session, actor=current, tree=tree, membership_id=membership_id, role=data.role
+    )
+    return MembershipRead(**row)
+
+
+@router.delete("/{tree_id}/members/{membership_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def remove_member(
+    tree_id: uuid.UUID,
+    membership_id: uuid.UUID,
+    session: SessionDep,
+    current: CurrentUser,
+) -> None:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    await membership_service.remove_member(
+        session, actor=current, tree=tree, membership_id=membership_id
+    )

backend/app/api/v1/names.py

@@ -0,0 +1,90 @@
+import uuid
+
+from fastapi import APIRouter, status
+
+from app.api.deps import CurrentUser, SessionDep
+from app.schemas.name import NameCreate, NameRead, NameUpdate
+from app.services import name_service, tree_service
+
+# Names are nested under their person (which is nested under the tree tenant).
+router = APIRouter(prefix="/trees", tags=["names"])
+
+
+@router.get("/{tree_id}/persons/{person_id}/names", response_model=list[NameRead])
+async def list_names(
+    tree_id: uuid.UUID, person_id: uuid.UUID, session: SessionDep, current: CurrentUser
+) -> list[NameRead]:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    names = await name_service.list_names(
+        session, viewer_id=current.id, tree=tree, person_id=person_id
+    )
+    return [NameRead.model_validate(n) for n in names]
+
+
+@router.post(
+    "/{tree_id}/persons/{person_id}/names",
+    response_model=NameRead,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_name(
+    tree_id: uuid.UUID,
+    person_id: uuid.UUID,
+    data: NameCreate,
+    session: SessionDep,
+    current: CurrentUser,
+) -> NameRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    name = await name_service.create_name(
+        session,
+        actor=current,
+        tree=tree,
+        person_id=person_id,
+        name_type=data.name_type,
+        given=data.given,
+        surname=data.surname,
+        prefix=data.prefix,
+        suffix=data.suffix,
+        nickname=data.nickname,
+        is_primary=data.is_primary,
+    )
+    return NameRead.model_validate(name)
+
+
+@router.patch(
+    "/{tree_id}/persons/{person_id}/names/{name_id}", response_model=NameRead
+)
+async def update_name(
+    tree_id: uuid.UUID,
+    person_id: uuid.UUID,
+    name_id: uuid.UUID,
+    data: NameUpdate,
+    session: SessionDep,
+    current: CurrentUser,
+) -> NameRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    name = await name_service.update_name(
+        session,
+        actor=current,
+        tree=tree,
+        person_id=person_id,
+        name_id=name_id,
+        changes=data.model_dump(exclude_unset=True),
+    )
+    return NameRead.model_validate(name)
+
+
+@router.delete(
+    "/{tree_id}/persons/{person_id}/names/{name_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def delete_name(
+    tree_id: uuid.UUID,
+    person_id: uuid.UUID,
+    name_id: uuid.UUID,
+    session: SessionDep,
+    current: CurrentUser,
+) -> None:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    await name_service.delete_name(
+        session, actor=current, tree=tree, person_id=person_id, name_id=name_id
+    )

backend/app/api/v1/persons.py

@@ -3,7 +3,7 @@ import uuid
 from fastapi import APIRouter, status
 
 from app.api.deps import CurrentUser, SessionDep
-from app.schemas.person import PersonCreate, PersonRead
+from app.schemas.person import PersonCreate, PersonRead, PersonUpdate
 from app.services import person_service, tree_service
 
 # Persons are nested under their tree (the tenant boundary).
@@ -36,10 +36,18 @@ async def create_person(
 
 @router.get("/{tree_id}/persons", response_model=list[PersonRead])
 async def list_persons(
-    tree_id: uuid.UUID, session: SessionDep, current: CurrentUser, deleted: bool = False
+    tree_id: uuid.UUID,
+    session: SessionDep,
+    current: CurrentUser,
+    deleted: bool = False,
+    q: str | None = None,
 ) -> list[PersonRead]:
     tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
-    if deleted:
+    if q:
+        persons = await person_service.search_persons(
+            session, viewer_id=current.id, tree=tree, query=q
+        )
+    elif deleted:
         persons = await person_service.list_deleted_persons(
             session, viewer_id=current.id, tree=tree
         )
@@ -48,12 +56,40 @@ async def list_persons(
     return [PersonRead.model_validate(p) for p in persons]
 
 
-@router.delete("/{tree_id}/persons/{person_id}", status_code=status.HTTP_204_NO_CONTENT)
-async def delete_person(
-    tree_id: uuid.UUID, person_id: uuid.UUID, session: SessionDep, current: CurrentUser
-) -> None:
+@router.patch("/{tree_id}/persons/{person_id}", response_model=PersonRead)
+async def update_person(
+    tree_id: uuid.UUID,
+    person_id: uuid.UUID,
+    data: PersonUpdate,
+    session: SessionDep,
+    current: CurrentUser,
+) -> PersonRead:
     tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
-    await person_service.delete_person(session, actor=current, tree=tree, person_id=person_id)
+    person = await person_service.update_person(
+        session,
+        actor=current,
+        tree=tree,
+        person_id=person_id,
+        changes=data.model_dump(exclude_unset=True),
+    )
+    return PersonRead.model_validate(person)
+
+
+@router.delete("/{tree_id}/persons/{person_id}")
+async def delete_person(
+    tree_id: uuid.UUID,
+    person_id: uuid.UUID,
+    session: SessionDep,
+    current: CurrentUser,
+    cascade: bool = False,
+) -> dict[str, int]:
+    """Delete a person. ``cascade=true`` also deletes all descendants. Returns
+    the number of persons deleted (1 unless cascading)."""
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    deleted = await person_service.delete_person(
+        session, actor=current, tree=tree, person_id=person_id, cascade=cascade
+    )
+    return {"deleted": deleted}
 
 
 @router.post("/{tree_id}/persons/{person_id}/restore", response_model=PersonRead)

backend/app/api/v1/proposals.py

@@ -0,0 +1,116 @@
+"""Change-proposal endpoints: list / create / get / apply / reject / delete.
+
+Applying a proposal is the only way its operations reach the database, and only
+an editor can do it (enforced in the service). See docs/design/change-proposal.md.
+"""
+
+import uuid
+
+from fastapi import APIRouter, status
+
+from app.api.deps import CurrentUser, SessionDep
+from app.models.enums import ChangeProposalStatus
+from app.schemas.change_proposal import (
+    ChangeProposalCreate,
+    ChangeProposalRead,
+    ProposalReview,
+)
+from app.services import change_proposal_service, tree_service
+
+router = APIRouter(prefix="/trees", tags=["proposals"])
+
+
+@router.get("/{tree_id}/proposals", response_model=list[ChangeProposalRead])
+async def list_proposals(
+    tree_id: uuid.UUID,
+    session: SessionDep,
+    current: CurrentUser,
+    status: ChangeProposalStatus | None = None,
+) -> list[ChangeProposalRead]:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    rows = await change_proposal_service.list_proposals(
+        session, viewer_id=current.id, tree=tree, status=status
+    )
+    return [ChangeProposalRead.model_validate(r) for r in rows]
+
+
+@router.post(
+    "/{tree_id}/proposals", response_model=ChangeProposalRead, status_code=status.HTTP_201_CREATED
+)
+async def create_proposal(
+    tree_id: uuid.UUID, data: ChangeProposalCreate, session: SessionDep, current: CurrentUser
+) -> ChangeProposalRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    operations = [op.model_dump(mode="json") for op in data.operations]
+    cp = await change_proposal_service.propose(
+        session,
+        tree=tree,
+        origin=data.origin,
+        created_by=current.id,
+        summary=data.summary,
+        rationale=data.rationale,
+        operations=operations,
+    )
+    return ChangeProposalRead.model_validate(cp)
+
+
+@router.get("/{tree_id}/proposals/{proposal_id}", response_model=ChangeProposalRead)
+async def get_proposal(
+    tree_id: uuid.UUID, proposal_id: uuid.UUID, session: SessionDep, current: CurrentUser
+) -> ChangeProposalRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    cp = await change_proposal_service.get_proposal(
+        session, viewer_id=current.id, tree=tree, proposal_id=proposal_id
+    )
+    return ChangeProposalRead.model_validate(cp)
+
+
+@router.post("/{tree_id}/proposals/{proposal_id}/apply", response_model=ChangeProposalRead)
+async def apply_proposal(
+    tree_id: uuid.UUID,
+    proposal_id: uuid.UUID,
+    session: SessionDep,
+    current: CurrentUser,
+    data: ProposalReview | None = None,
+) -> ChangeProposalRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    edited = (
+        [op.model_dump(mode="json") for op in data.operations]
+        if data and data.operations is not None
+        else None
+    )
+    cp = await change_proposal_service.apply(
+        session, actor=current, tree=tree, proposal_id=proposal_id, edited_operations=edited
+    )
+    return ChangeProposalRead.model_validate(cp)
+
+
+@router.post("/{tree_id}/proposals/{proposal_id}/reject", response_model=ChangeProposalRead)
+async def reject_proposal(
+    tree_id: uuid.UUID,
+    proposal_id: uuid.UUID,
+    session: SessionDep,
+    current: CurrentUser,
+    data: ProposalReview | None = None,
+) -> ChangeProposalRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    cp = await change_proposal_service.reject(
+        session,
+        actor=current,
+        tree=tree,
+        proposal_id=proposal_id,
+        note=data.note if data else None,
+    )
+    return ChangeProposalRead.model_validate(cp)
+
+
+@router.delete(
+    "/{tree_id}/proposals/{proposal_id}", status_code=status.HTTP_204_NO_CONTENT
+)
+async def delete_proposal(
+    tree_id: uuid.UUID, proposal_id: uuid.UUID, session: SessionDep, current: CurrentUser
+) -> None:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    await change_proposal_service.delete_proposal(
+        session, actor=current, tree=tree, proposal_id=proposal_id
+    )

backend/app/api/v1/public.py

@@ -0,0 +1,135 @@
+"""Public, read-only viewing surface.
+
+Optional auth (anonymous allowed). Every response is built by
+``public_view_service``, which routes through the privacy engine and redacts
+possibly-living people. No create/update/delete here.
+"""
+
+import uuid
+
+from fastapi import APIRouter
+
+from app.api.deps import CurrentUserOrNone, SessionDep
+from app.schemas.event import EventRead
+from app.schemas.name import NameRead
+from app.schemas.person import PersonRead
+from app.schemas.relationship import RelationshipRead
+from app.schemas.tree import PublicTreeRead
+from app.services import public_view_service
+
+router = APIRouter(prefix="/public", tags=["public"])
+
+
+def _vid(viewer: CurrentUserOrNone) -> uuid.UUID | None:
+    return viewer.id if viewer else None
+
+
+@router.get("/trees", response_model=list[PublicTreeRead])
+async def public_directory(
+    session: SessionDep,
+    viewer: CurrentUserOrNone,
+    q: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> list[PublicTreeRead]:
+    trees = await public_view_service.list_public_trees(
+        session, viewer_id=_vid(viewer), q=q, limit=limit, offset=offset
+    )
+    return [PublicTreeRead.model_validate(t) for t in trees]
+
+
+@router.get("/trees/{tree_id}", response_model=PublicTreeRead)
+async def public_tree(
+    tree_id: uuid.UUID, session: SessionDep, viewer: CurrentUserOrNone
+) -> PublicTreeRead:
+    tree = await public_view_service.get_public_tree(
+        session, viewer_id=_vid(viewer), tree_id=tree_id
+    )
+    return PublicTreeRead.model_validate(tree)
+
+
+@router.get("/trees/{tree_id}/persons", response_model=list[PersonRead])
+async def public_persons(
+    tree_id: uuid.UUID, session: SessionDep, viewer: CurrentUserOrNone
+) -> list[PersonRead]:
+    tree = await public_view_service.get_public_tree(
+        session, viewer_id=_vid(viewer), tree_id=tree_id
+    )
+    persons = await public_view_service.list_public_persons(
+        session, viewer_id=_vid(viewer), tree=tree
+    )
+    return [PersonRead.model_validate(p) for p in persons]
+
+
+@router.get("/trees/{tree_id}/relationships", response_model=list[RelationshipRead])
+async def public_relationships(
+    tree_id: uuid.UUID, session: SessionDep, viewer: CurrentUserOrNone
+) -> list[RelationshipRead]:
+    tree = await public_view_service.get_public_tree(
+        session, viewer_id=_vid(viewer), tree_id=tree_id
+    )
+    rels = await public_view_service.list_public_relationships(
+        session, viewer_id=_vid(viewer), tree=tree
+    )
+    return [RelationshipRead.model_validate(r) for r in rels]
+
+
+@router.get("/trees/{tree_id}/events", response_model=list[EventRead])
+async def public_events(
+    tree_id: uuid.UUID, session: SessionDep, viewer: CurrentUserOrNone
+) -> list[EventRead]:
+    tree = await public_view_service.get_public_tree(
+        session, viewer_id=_vid(viewer), tree_id=tree_id
+    )
+    events = await public_view_service.list_public_events(
+        session, viewer_id=_vid(viewer), tree=tree
+    )
+    return [EventRead.model_validate(e) for e in events]
+
+
+@router.get("/trees/{tree_id}/persons/{person_id}", response_model=PersonRead)
+async def public_person(
+    tree_id: uuid.UUID,
+    person_id: uuid.UUID,
+    session: SessionDep,
+    viewer: CurrentUserOrNone,
+) -> PersonRead:
+    tree = await public_view_service.get_public_tree(
+        session, viewer_id=_vid(viewer), tree_id=tree_id
+    )
+    person = await public_view_service.get_public_person(
+        session, viewer_id=_vid(viewer), tree=tree, person_id=person_id
+    )
+    return PersonRead.model_validate(person)
+
+
+@router.get("/trees/{tree_id}/persons/{person_id}/names", response_model=list[NameRead])
+async def public_person_names(
+    tree_id: uuid.UUID,
+    person_id: uuid.UUID,
+    session: SessionDep,
+    viewer: CurrentUserOrNone,
+) -> list[NameRead]:
+    tree = await public_view_service.get_public_tree(
+        session, viewer_id=_vid(viewer), tree_id=tree_id
+    )
+    names = await public_view_service.list_public_person_names(
+        session, viewer_id=_vid(viewer), tree=tree, person_id=person_id
+    )
+    return [NameRead.model_validate(n) for n in names]
+
+
+@router.get("/trees/{tree_id}/persons/{person_id}/events", response_model=list[EventRead])
+async def public_person_events(
+    tree_id: uuid.UUID,
+    person_id: uuid.UUID,
+    session: SessionDep,
+    viewer: CurrentUserOrNone,
+) -> list[EventRead]:
+    tree = await public_view_service.get_public_tree(
+        session, viewer_id=_vid(viewer), tree_id=tree_id
+    )
+    events = await public_view_service.list_public_person_events(
+        session, viewer_id=_vid(viewer), tree=tree, person_id=person_id
+    )
+    return [EventRead.model_validate(e) for e in events]

backend/app/api/v1/relationships.py

@@ -3,7 +3,7 @@ import uuid
 from fastapi import APIRouter, status
 
 from app.api.deps import CurrentUser, SessionDep
-from app.schemas.relationship import RelationshipCreate, RelationshipRead
+from app.schemas.relationship import RelationshipCreate, RelationshipRead, RelationshipUpdate
 from app.services import relationship_service, tree_service
 
 router = APIRouter(prefix="/trees", tags=["relationships"])
@@ -47,6 +47,25 @@ async def list_person_relationships(
     return [RelationshipRead.model_validate(r) for r in rels]
 
 
+@router.patch("/{tree_id}/relationships/{relationship_id}", response_model=RelationshipRead)
+async def update_relationship(
+    tree_id: uuid.UUID,
+    relationship_id: uuid.UUID,
+    data: RelationshipUpdate,
+    session: SessionDep,
+    current: CurrentUser,
+) -> RelationshipRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    rel = await relationship_service.update_relationship(
+        session,
+        actor=current,
+        tree=tree,
+        relationship_id=relationship_id,
+        changes=data.model_dump(exclude_unset=True),
+    )
+    return RelationshipRead.model_validate(rel)
+
+
 @router.delete(
     "/{tree_id}/relationships/{relationship_id}", status_code=status.HTTP_204_NO_CONTENT
 )

backend/app/api/v1/sources.py

@@ -3,7 +3,7 @@ import uuid
 from fastapi import APIRouter, status
 
 from app.api.deps import CurrentUser, SessionDep
-from app.schemas.source import SourceCreate, SourceRead
+from app.schemas.source import SourceCreate, SourceRead, SourceUpdate
 from app.services import source_service, tree_service
 
 router = APIRouter(prefix="/trees", tags=["sources"])
@@ -40,6 +40,25 @@ async def get_source(
     return SourceRead.model_validate(source)
 
 
+@router.patch("/{tree_id}/sources/{source_id}", response_model=SourceRead)
+async def update_source(
+    tree_id: uuid.UUID,
+    source_id: uuid.UUID,
+    data: SourceUpdate,
+    session: SessionDep,
+    current: CurrentUser,
+) -> SourceRead:
+    tree = await tree_service.get_tree(session, viewer_id=current.id, tree_id=tree_id)
+    source = await source_service.update_source(
+        session,
+        actor=current,
+        tree=tree,
+        source_id=source_id,
+        changes=data.model_dump(exclude_unset=True),
+    )
+    return SourceRead.model_validate(source)
+
+
 @router.delete("/{tree_id}/sources/{source_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_source(
     tree_id: uuid.UUID, source_id: uuid.UUID, session: SessionDep, current: CurrentUser

backend/app/api/v1/trees.py

@@ -3,7 +3,7 @@ import uuid
 from fastapi import APIRouter, status
 
 from app.api.deps import CurrentUser, SessionDep
-from app.schemas.tree import TreeCreate, TreeRead
+from app.schemas.tree import TreeCreate, TreeRead, TreeUpdate
 from app.services import tree_service
 
 router = APIRouter(prefix="/trees", tags=["trees"])
@@ -38,6 +38,16 @@ async def get_tree(tree_id: uuid.UUID, session: SessionDep, current: CurrentUser
     return TreeRead.model_validate(tree)
 
 
+@router.patch("/{tree_id}", response_model=TreeRead)
+async def update_tree(
+    tree_id: uuid.UUID, data: TreeUpdate, session: SessionDep, current: CurrentUser
+) -> TreeRead:
+    tree = await tree_service.update_tree(
+        session, actor=current, tree_id=tree_id, changes=data.model_dump(exclude_unset=True)
+    )
+    return TreeRead.model_validate(tree)
+
+
 @router.delete("/{tree_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_tree(tree_id: uuid.UUID, session: SessionDep, current: CurrentUser) -> None:
     await tree_service.delete_tree(session, actor=current, tree_id=tree_id)

backend/app/api/v1/users.py

@@ -1,7 +1,8 @@
-from fastapi import APIRouter
+from fastapi import APIRouter, File, Form, Response, UploadFile
 
-from app.api.deps import CurrentUser
-from app.schemas.user import UserRead
+from app.api.deps import CurrentUser, ObjectStoreDep, SessionDep
+from app.schemas.user import UserRead, UserSelfPersonUpdate
+from app.services import account_service, user_service
 
 router = APIRouter(prefix="/users", tags=["users"])
 
@@ -9,3 +10,48 @@ router = APIRouter(prefix="/users", tags=["users"])
 @router.get("/me", response_model=UserRead)
 async def read_me(current: CurrentUser) -> UserRead:
     return UserRead.model_validate(current)
+
+
+@router.patch("/me/self-person", response_model=UserRead)
+async def set_self_person(
+    data: UserSelfPersonUpdate, session: SessionDep, current: CurrentUser
+) -> UserRead:
+    """Link (or unlink) the Person record that represents this account."""
+    user = await user_service.set_self_person(
+        session, user=current, person_id=data.self_person_id
+    )
+    return UserRead.model_validate(user)
+
+
+@router.get("/me/export")
+async def export_account(
+    session: SessionDep, current: CurrentUser, store: ObjectStoreDep
+) -> Response:
+    """Download a full backup (JSON + media) of every tree the user owns."""
+    data = await account_service.export_account(session, store, user=current)
+    return Response(
+        content=data,
+        media_type="application/zip",
+        headers={"Content-Disposition": 'attachment; filename="provenance-export.zip"'},
+    )
+
+
+@router.post("/me/import")
+async def import_account(
+    session: SessionDep,
+    current: CurrentUser,
+    store: ObjectStoreDep,
+    file: UploadFile = File(...),
+) -> dict:
+    """Restore a previously-exported backup into new trees (non-destructive)."""
+    raw = await file.read()
+    return await account_service.import_account(session, store, user=current, raw_zip=raw)
+
+
+@router.delete("/me", status_code=204)
+async def delete_account(
+    session: SessionDep, current: CurrentUser, confirm_email: str = Form(...)
+) -> None:
+    """Delete the account: the user, their owned trees, and their sessions.
+    Requires retyping the account email as a guard."""
+    await account_service.delete_account(session, user=current, confirm_email=confirm_email)

backend/app/core/config.py

@@ -48,6 +48,11 @@ class Settings(BaseSettings):
     purge_after_days: int = 30  # soft-deleted rows older than this are purged
 
     # --- Email (SMTP) ---
+    # When true, a user with no verified email gets no active session (login is
+    # refused and existing sessions stop resolving). Default false so self-hosts
+    # without SMTP — and accounts created before this gate existed — aren't
+    # locked out; operators turn it on once mail works and accounts are verified.
+    require_email_verification: bool = False
     mailer: str = Field(default="console", description="console | smtp")
     smtp_host: str | None = None
     smtp_port: int = 587
@@ -55,6 +60,36 @@ class Settings(BaseSettings):
     smtp_password: str | None = None
     smtp_from: str = "Provenance <no-reply@provenance.local>"
 
+    # --- Model providers (AI assistant + match-ranking embeddings) ---
+    # Configure as many as you like; each is enabled when its credentials are
+    # present. `default_*_provider` picks which one is used by default. LLM and
+    # embeddings are independent (Anthropic has no embeddings endpoint).
+    default_llm_provider: str = "null"  # null | anthropic | openai | xai | ollama
+    default_embedding_provider: str = "null"  # null | openai | ollama
+    llm_max_tokens: int = 4096
+    embedding_dimensions: int = 1536  # must match the embedding model + pgvector column
+
+    # Anthropic (LLM only)
+    anthropic_api_key: str | None = None
+    anthropic_model: str = "claude-opus-4-8"
+
+    # OpenAI (LLM + embeddings)
+    openai_api_key: str | None = None
+    openai_base_url: str = "https://api.openai.com/v1"
+    openai_model: str = "gpt-4o"
+    openai_embedding_model: str = "text-embedding-3-small"
+
+    # xAI / Grok — OpenAI-compatible (LLM)
+    xai_api_key: str | None = None
+    xai_base_url: str = "https://api.x.ai/v1"
+    xai_model: str = "grok-2-latest"  # set to your account's current Grok model
+
+    # Ollama — local, OpenAI-compatible, no key (LLM + embeddings)
+    ollama_enabled: bool = False
+    ollama_base_url: str = "http://localhost:11434/v1"
+    ollama_model: str = "llama3.1"
+    ollama_embedding_model: str = "nomic-embed-text"
+
 
 @lru_cache
 def get_settings() -> Settings:

backend/app/integrations/models/anthropic_provider.py

@@ -0,0 +1,24 @@
+"""Anthropic LLM provider (official SDK). Self-hosters who want everything to
+stay on their own metal would configure a local provider instead (e.g. Ollama) —
+that's a future implementation of the same LLMProvider interface."""
+
+from anthropic import AsyncAnthropic
+
+from app.integrations.models.base import LLMProvider
+
+
+class AnthropicLLMProvider(LLMProvider):
+    def __init__(self, *, api_key: str, model: str, max_tokens: int = 4096) -> None:
+        self._client = AsyncAnthropic(api_key=api_key)
+        self._model = model
+        self._max_tokens = max_tokens
+
+    async def complete(self, *, prompt: str, system: str | None = None) -> str:
+        resp = await self._client.messages.create(
+            model=self._model,
+            max_tokens=self._max_tokens,
+            system=system or "",
+            messages=[{"role": "user", "content": prompt}],
+        )
+        # content is a list of blocks; concatenate the text ones.
+        return "".join(b.text for b in resp.content if b.type == "text")

backend/app/integrations/models/base.py

@@ -0,0 +1,36 @@
+"""Model-provider interfaces — the seam the AI assistant and match ranking plug
+into. LLM (text) and embeddings are *separate* abstractions: Anthropic offers no
+embeddings endpoint, so the two are configured independently (twelve-factor,
+CLAUDE.md #7) and a deployment may run one without the other.
+
+These providers are read-only text/vector producers. They MUST NOT mutate tree
+data — the assistant's writes go through a ChangeProposal a human approves
+(CLAUDE.md #1). Nothing here touches the database.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class LLMProvider(ABC):
+    """Text in, text out. Implementations wrap a chat/completion model."""
+
+    @abstractmethod
+    async def complete(self, *, prompt: str, system: str | None = None) -> str:
+        """Return the model's text response to a single user prompt."""
+        ...
+
+
+class EmbeddingProvider(ABC):
+    """Text in, vectors out — for pgvector-backed match ranking."""
+
+    #: Dimensionality of the returned vectors (for the pgvector column).
+    dimensions: int
+
+    @abstractmethod
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        """Return one embedding vector per input text, in order."""
+        ...
+
+
+class ModelProviderNotConfigured(RuntimeError):
+    """Raised when an AI capability is used but no provider is configured."""

backend/app/integrations/models/null.py

@@ -0,0 +1,31 @@
+"""Default providers when no model backend is configured — AI features are off.
+
+They fail loudly (rather than silently doing nothing) so a caller that reaches
+for an unconfigured capability gets a clear, actionable error.
+"""
+
+from app.integrations.models.base import (
+    EmbeddingProvider,
+    LLMProvider,
+    ModelProviderNotConfigured,
+)
+
+_MSG = (
+    "No model provider configured. Set MODEL_PROVIDER (e.g. 'anthropic') and the "
+    "provider's credentials to enable AI features."
+)
+
+
+class NullLLMProvider(LLMProvider):
+    async def complete(self, *, prompt: str, system: str | None = None) -> str:
+        raise ModelProviderNotConfigured(_MSG)
+
+
+class NullEmbeddingProvider(EmbeddingProvider):
+    dimensions = 0
+
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        raise ModelProviderNotConfigured(
+            "No embedding provider configured. Set EMBEDDING_PROVIDER and its "
+            "credentials to enable match ranking."
+        )

backend/app/integrations/models/openai_compat.py

@@ -0,0 +1,40 @@
+"""OpenAI-compatible providers (one implementation, many vendors).
+
+OpenAI, xAI (api.x.ai/v1), Ollama (…:11434/v1), OpenRouter, Together, vLLM, etc.
+all speak the OpenAI Chat Completions / Embeddings API — they differ only by
+base URL, key, and model name. So a single class, parameterized by those, plugs
+in every one of them via the official `openai` SDK.
+"""
+
+from openai import AsyncOpenAI
+
+from app.integrations.models.base import EmbeddingProvider, LLMProvider
+
+
+class OpenAICompatibleLLMProvider(LLMProvider):
+    def __init__(self, *, api_key: str | None, base_url: str, model: str, max_tokens: int = 4096) -> None:
+        # Local backends (Ollama) ignore the key but the SDK requires a non-empty one.
+        self._client = AsyncOpenAI(api_key=api_key or "not-needed", base_url=base_url)
+        self._model = model
+        self._max_tokens = max_tokens
+
+    async def complete(self, *, prompt: str, system: str | None = None) -> str:
+        messages: list[dict] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        resp = await self._client.chat.completions.create(
+            model=self._model, max_tokens=self._max_tokens, messages=messages
+        )
+        return resp.choices[0].message.content or ""
+
+
+class OpenAICompatibleEmbeddingProvider(EmbeddingProvider):
+    def __init__(self, *, api_key: str | None, base_url: str, model: str, dimensions: int) -> None:
+        self._client = AsyncOpenAI(api_key=api_key or "not-needed", base_url=base_url)
+        self._model = model
+        self.dimensions = dimensions
+
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        resp = await self._client.embeddings.create(model=self._model, input=texts)
+        return [d.embedding for d in resp.data]

backend/app/models/__init__.py

@@ -4,6 +4,7 @@ and for ``create_all`` in tests."""
 from app.models.audit import AuditEntry
 from app.models.auth import Session, UserToken
 from app.models.base import Base
+from app.models.change_proposal import ChangeProposal
 from app.models.event import Event
 from app.models.media import Media
 from app.models.person import Name, Person
@@ -30,4 +31,5 @@ __all__ = [
     "Session",
     "UserToken",
     "Media",
+    "ChangeProposal",
 ]

backend/app/models/change_proposal.py

@@ -0,0 +1,48 @@
+"""ChangeProposal — a structured diff the AI assistant (or an untrusted
+contributor) proposes, which a human approves/edits/rejects. Applying it routes
+each operation through the normal editing services, so the change passes the
+privacy engine and is audited as the approving human's action. See
+docs/design/change-proposal.md and CLAUDE.md non-negotiable #1.
+"""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, String, Text
+from sqlalchemy import Enum as SAEnum
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base
+from app.models.enums import ChangeProposalOrigin, ChangeProposalStatus
+from app.models.mixins import SoftDelete, TenantScoped, Timestamps, UUIDPrimaryKey
+
+
+class ChangeProposal(Base, UUIDPrimaryKey, TenantScoped, Timestamps, SoftDelete):
+    __tablename__ = "change_proposals"
+
+    status: Mapped[ChangeProposalStatus] = mapped_column(
+        SAEnum(ChangeProposalStatus, name="change_proposal_status"),
+        default=ChangeProposalStatus.pending,
+        server_default=ChangeProposalStatus.pending.value,
+        index=True,
+    )
+    origin: Mapped[ChangeProposalOrigin] = mapped_column(
+        SAEnum(ChangeProposalOrigin, name="change_proposal_origin"),
+        default=ChangeProposalOrigin.assistant,
+        server_default=ChangeProposalOrigin.assistant.value,
+    )
+    created_by_user_id: Mapped[uuid.UUID | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL")
+    )
+    summary: Mapped[str] = mapped_column(String(512))
+    rationale: Mapped[str | None] = mapped_column(Text)
+    # The structured diff: a list of {op, entity_type, entity_id?, payload} dicts.
+    operations: Mapped[list] = mapped_column(JSONB, nullable=False)
+
+    reviewed_by_user_id: Mapped[uuid.UUID | None] = mapped_column(
+        ForeignKey("users.id", ondelete="SET NULL")
+    )
+    reviewed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    review_note: Mapped[str | None] = mapped_column(String(512))
+    apply_error: Mapped[str | None] = mapped_column(Text)

backend/app/models/enums.py

@@ -9,9 +9,10 @@ import enum
 
 
 class TreeVisibility(enum.StrEnum):
-    public = "public"
-    unlisted = "unlisted"
-    private = "private"
+    public = "public"  # anyone on the web (anonymous), listed + search-indexable
+    site_members = "site_members"  # any authenticated user of this instance
+    unlisted = "unlisted"  # anyone with the link (anonymous), not listed/indexed
+    private = "private"  # members only (default)
 
 
 class MembershipRole(enum.StrEnum):
@@ -60,3 +61,14 @@ class AuditActorType(enum.StrEnum):
 class TokenPurpose(enum.StrEnum):
     email_verify = "email_verify"
     password_reset = "password_reset"
+
+
+class ChangeProposalStatus(enum.StrEnum):
+    pending = "pending"
+    applied = "applied"
+    rejected = "rejected"
+
+
+class ChangeProposalOrigin(enum.StrEnum):
+    assistant = "assistant"  # the AI assistant, acting on behalf of a user
+    contributor = "contributor"  # an untrusted human edit awaiting moderation

backend/app/models/person.py

@@ -7,7 +7,7 @@ aliases) so name changes over time are first-class.
 
 import uuid
 
-from sqlalchemy import Boolean, ForeignKey, Integer, String, Text, text
+from sqlalchemy import Boolean, ForeignKey, Index, Integer, String, Text, text
 from sqlalchemy import Enum as SAEnum
 from sqlalchemy.orm import Mapped, mapped_column
 
@@ -33,6 +33,22 @@ class Person(Base, UUIDPrimaryKey, TenantScoped, Timestamps, SoftDelete):
 
 class Name(Base, UUIDPrimaryKey, TenantScoped, Timestamps, SoftDelete):
     __tablename__ = "names"
+    # Trigram indexes for fuzzy name search (Mueller/Müller/Muller). Requires the
+    # pg_trgm extension (enabled in the accompanying migration).
+    __table_args__ = (
+        Index(
+            "ix_names_given_trgm",
+            "given",
+            postgresql_using="gin",
+            postgresql_ops={"given": "gin_trgm_ops"},
+        ),
+        Index(
+            "ix_names_surname_trgm",
+            "surname",
+            postgresql_using="gin",
+            postgresql_ops={"surname": "gin_trgm_ops"},
+        ),
+    )
 
     person_id: Mapped[uuid.UUID] = mapped_column(
         ForeignKey("persons.id", ondelete="CASCADE"), index=True

backend/app/models/tree.py

@@ -26,6 +26,16 @@ class Tree(Base, UUIDPrimaryKey, Timestamps, SoftDelete):
         default=TreeVisibility.private,
         server_default=TreeVisibility.private.value,
     )
+    # The person a tree opens focused on (its "home"/root person). Cleared if
+    # that person is deleted. use_alter + name: trees<->persons form an FK cycle.
+    home_person_id: Mapped[uuid.UUID | None] = mapped_column(
+        ForeignKey(
+            "persons.id",
+            ondelete="SET NULL",
+            name="fk_trees_home_person_id",
+            use_alter=True,
+        )
+    )
 
 
 class TreeMembership(Base, UUIDPrimaryKey, Timestamps):

backend/app/models/user.py

@@ -3,9 +3,10 @@ multiple auth providers later (the provider-link table arrives with the auth
 slice). ``hashed_password`` is nullable: external/OIDC users have none.
 """
 
+import uuid
 from datetime import datetime
 
-from sqlalchemy import DateTime, String
+from sqlalchemy import DateTime, ForeignKey, String
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.models.base import Base
@@ -19,3 +20,15 @@ class User(Base, UUIDPrimaryKey, Timestamps, SoftDelete):
     email_verified_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     display_name: Mapped[str | None] = mapped_column(String(255))
     hashed_password: Mapped[str | None] = mapped_column(String(255))
+    # The Person record that *is* this user ("home person"). Cleared if that
+    # person is deleted, so the link can never dangle.
+    self_person_id: Mapped[uuid.UUID | None] = mapped_column(
+        # use_alter + explicit name: users<->persons<->trees form an FK cycle,
+        # so this constraint must be created/dropped via ALTER, not inline.
+        ForeignKey(
+            "persons.id",
+            ondelete="SET NULL",
+            name="fk_users_self_person_id",
+            use_alter=True,
+        )
+    )

backend/app/schemas/auth.py

@@ -29,6 +29,11 @@ class PasswordResetConfirm(BaseModel):
     new_password: str = Field(min_length=8)
 
 
+class PasswordChange(BaseModel):
+    current_password: str
+    new_password: str = Field(min_length=8)
+
+
 class SessionRead(BaseModel):
     user: UserRead
     token: str

backend/app/schemas/change_proposal.py

@@ -0,0 +1,44 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+from app.models.enums import ChangeProposalOrigin, ChangeProposalStatus
+
+
+class ProposalOperation(BaseModel):
+    op: str  # create | update | delete
+    entity_type: str  # person | name | event | relationship | source | citation
+    entity_id: uuid.UUID | None = None
+    payload: dict = {}
+
+
+class ChangeProposalCreate(BaseModel):
+    summary: str
+    rationale: str | None = None
+    origin: ChangeProposalOrigin = ChangeProposalOrigin.contributor
+    operations: list[ProposalOperation]
+
+
+class ProposalReview(BaseModel):
+    note: str | None = None
+    # Optional edited operations to apply instead of the original (approve-with-edits).
+    operations: list[ProposalOperation] | None = None
+
+
+class ChangeProposalRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    tree_id: uuid.UUID
+    status: ChangeProposalStatus
+    origin: ChangeProposalOrigin
+    created_by_user_id: uuid.UUID | None
+    summary: str
+    rationale: str | None
+    operations: list
+    reviewed_by_user_id: uuid.UUID | None
+    reviewed_at: datetime | None
+    review_note: str | None
+    apply_error: str | None
+    created_at: datetime

backend/app/schemas/cleanup.py

@@ -0,0 +1,50 @@
+import uuid
+
+from pydantic import BaseModel
+
+
+class DeceasedCandidate(BaseModel):
+    person_id: uuid.UUID
+    name: str
+    birth_year: int
+
+
+class DeceasedApply(BaseModel):
+    person_ids: list[uuid.UUID]
+
+
+class GenderProposal(BaseModel):
+    person_id: uuid.UUID
+    name: str
+    proposed_gender: str
+
+
+class GenderUpdate(BaseModel):
+    person_id: uuid.UUID
+    gender: str
+
+
+class GenderApply(BaseModel):
+    updates: list[GenderUpdate]
+
+
+class NameIssue(BaseModel):
+    name_id: uuid.UUID
+    person_id: uuid.UUID
+    given: str | None = None
+    surname: str | None = None
+    issue: str
+
+
+class NameEdit(BaseModel):
+    name_id: uuid.UUID
+    given: str | None = None
+    surname: str | None = None
+
+
+class NameApply(BaseModel):
+    edits: list[NameEdit]
+
+
+class CleanupResult(BaseModel):
+    updated: int

backend/app/schemas/event.py

@@ -20,6 +20,19 @@ class EventCreate(BaseModel):
     notes: str | None = None
 
 
+class EventUpdate(BaseModel):
+    # All optional; only fields explicitly sent are changed (PATCH semantics).
+    event_type: str | None = None
+    place_id: uuid.UUID | None = None
+    date_value: str | None = None
+    date_start: date | None = None
+    date_end: date | None = None
+    date_precision: str | None = None
+    calendar: str | None = None
+    detail: str | None = None
+    notes: str | None = None
+
+
 class EventRead(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 

backend/app/schemas/gedcom.py

@@ -1,6 +1,25 @@
+import uuid
+
 from pydantic import BaseModel
 
 
 class ImportReport(BaseModel):
     counts: dict[str, int]
     unmapped_tags: list[str]
+
+
+class DuplicateMatch(BaseModel):
+    # An incoming GEDCOM person that resembles an existing one in the tree.
+    xref: str
+    incoming_name: str
+    incoming_birth_year: str | None = None
+    existing_person_id: uuid.UUID
+    existing_name: str
+    existing_birth_year: str | None = None
+    score: str  # "high" | "medium"
+
+
+class ImportPreview(BaseModel):
+    counts: dict[str, int]
+    potential_duplicates: list[DuplicateMatch]
+    unmapped_tags: list[str]

backend/app/schemas/media.py

@@ -4,6 +4,13 @@ from datetime import datetime
 from pydantic import BaseModel, ConfigDict
 
 
+class MediaUpdate(BaseModel):
+    title: str | None = None
+    person_id: uuid.UUID | None = None
+    event_id: uuid.UUID | None = None
+    source_id: uuid.UUID | None = None
+
+
 class MediaRead(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 

backend/app/schemas/membership.py

@@ -0,0 +1,26 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+from app.models.enums import MembershipRole
+
+
+class MembershipRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    user_id: uuid.UUID
+    email: str
+    display_name: str | None
+    role: MembershipRole
+    created_at: datetime
+
+
+class MemberAdd(BaseModel):
+    email: str
+    role: MembershipRole = MembershipRole.viewer
+
+
+class MemberRoleUpdate(BaseModel):
+    role: MembershipRole

backend/app/schemas/name.py

@@ -0,0 +1,42 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class NameCreate(BaseModel):
+    # Open vocabulary: birth/maiden, married, alias, religious, nickname, ...
+    name_type: str = "birth"
+    given: str | None = None
+    surname: str | None = None
+    prefix: str | None = None
+    suffix: str | None = None
+    nickname: str | None = None
+    is_primary: bool = False
+
+
+class NameUpdate(BaseModel):
+    name_type: str | None = None
+    given: str | None = None
+    surname: str | None = None
+    prefix: str | None = None
+    suffix: str | None = None
+    nickname: str | None = None
+    is_primary: bool | None = None
+
+
+class NameRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    tree_id: uuid.UUID
+    person_id: uuid.UUID
+    name_type: str
+    given: str | None
+    surname: str | None
+    prefix: str | None
+    suffix: str | None
+    nickname: str | None
+    is_primary: bool
+    sort_order: int
+    created_at: datetime

backend/app/schemas/person.py

@@ -15,6 +15,16 @@ class PersonCreate(BaseModel):
     notes: str | None = None
 
 
+class PersonUpdate(BaseModel):
+    # Person fields + the primary name's parts; only sent fields are changed.
+    given: str | None = None
+    surname: str | None = None
+    gender: str | None = None
+    is_living: bool | None = None
+    privacy: PersonPrivacy | None = None
+    notes: str | None = None
+
+
 class PersonRead(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 

backend/app/schemas/relationship.py

@@ -15,6 +15,11 @@ class RelationshipCreate(BaseModel):
     notes: str | None = None
 
 
+class RelationshipUpdate(BaseModel):
+    qualifier: ParentChildQualifier | None = None
+    notes: str | None = None
+
+
 class RelationshipRead(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 

backend/app/schemas/source.py

@@ -33,6 +33,23 @@ class SourceRead(BaseModel):
     created_at: datetime
 
 
+class SourceUpdate(BaseModel):
+    title: str | None = None
+    author: str | None = None
+    source_type: str | None = None
+    repository: str | None = None
+    url: str | None = None
+    citation_text: str | None = None
+    publication_info: str | None = None
+    quality_note: str | None = None
+
+
+class CitationUpdate(BaseModel):
+    page: str | None = None
+    detail: str | None = None
+    confidence: CitationConfidence | None = None
+
+
 class CitationCreate(BaseModel):
     source_id: uuid.UUID
     # Exactly one target fact.

backend/app/schemas/tree.py

@@ -12,6 +12,13 @@ class TreeCreate(BaseModel):
     visibility: TreeVisibility = TreeVisibility.private
 
 
+class TreeUpdate(BaseModel):
+    name: str | None = None
+    description: str | None = None
+    visibility: TreeVisibility | None = None
+    home_person_id: uuid.UUID | None = None
+
+
 class TreeRead(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
@@ -20,4 +27,18 @@ class TreeRead(BaseModel):
     description: str | None
     visibility: TreeVisibility
     owner_id: uuid.UUID
+    home_person_id: uuid.UUID | None = None
     created_at: datetime
+
+
+class PublicTreeRead(BaseModel):
+    """Tree projection for the public surface — deliberately omits owner_id so a
+    public/unlisted tree doesn't reveal which account owns it."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    description: str | None
+    visibility: TreeVisibility
+    home_person_id: uuid.UUID | None = None

backend/app/schemas/user.py

@@ -19,4 +19,10 @@ class UserRead(BaseModel):
     email: str
     display_name: str | None
     email_verified_at: datetime | None
+    self_person_id: uuid.UUID | None = None
     created_at: datetime
+
+
+class UserSelfPersonUpdate(BaseModel):
+    # null clears the link; otherwise the Person that represents this account.
+    self_person_id: uuid.UUID | None = None

backend/app/services/account_service.py

@@ -0,0 +1,352 @@
+"""Account-level data portability: export the signed-in user's owned trees as a
+zip (JSON + media bytes), restore such a zip into a brand-new tree
+(non-destructive), and delete the account.
+
+The export format is a zip containing ``account.json`` plus ``media/<id>`` blobs.
+Restore always creates new trees and remaps ids, so it can't clobber existing
+data.
+"""
+
+import hashlib
+import io
+import json
+import uuid
+import zipfile
+from datetime import UTC, date, datetime
+
+from sqlalchemy import select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.integrations.objectstore.base import ObjectStore
+from app.models.auth import Session as SessionModel
+from app.models.enums import MembershipRole
+from app.models.event import Event
+from app.models.media import Media
+from app.models.person import Name, Person
+from app.models.place import Place
+from app.models.relationship import Relationship
+from app.models.source import Citation, Source
+from app.models.tree import Tree, TreeMembership
+from app.models.user import User
+from app.services.audit import record_audit
+from app.services.exceptions import Forbidden, NotFound
+
+EXPORT_VERSION = 1
+_DROP = {"created_at", "updated_at", "deleted_at", "tree_id"}
+# Media columns rebuilt on import (storage is re-keyed, checksum recomputed).
+_MEDIA_DROP = _DROP | {"uploader_id", "storage_key", "byte_size", "checksum_sha256"}
+_DATE_FIELDS = {"date_start", "date_end"}
+
+
+def _row(obj, drop: set[str]) -> dict:
+    out: dict = {}
+    for col in obj.__table__.columns.keys():  # noqa: SIM118
+        if col in drop:
+            continue
+        out[col] = getattr(obj, col)
+    return out
+
+
+async def _entities(session: AsyncSession, model, tree_id: uuid.UUID):
+    stmt = select(model).where(model.tree_id == tree_id, model.deleted_at.is_(None))
+    return list((await session.execute(stmt)).scalars().all())
+
+
+async def export_account(session: AsyncSession, store: ObjectStore, *, user: User) -> bytes:
+    """Build a zip of every tree the user owns: account.json + media blobs."""
+    trees = list(
+        (
+            await session.execute(
+                select(Tree).where(Tree.owner_id == user.id, Tree.deleted_at.is_(None))
+            )
+        ).scalars().all()
+    )
+
+    payload: dict = {
+        "version": EXPORT_VERSION,
+        "user": {"email": user.email, "display_name": user.display_name},
+        "trees": [],
+    }
+    media_blobs: list[tuple[str, bytes]] = []
+
+    for tree in trees:
+        media_rows = await _entities(session, Media, tree.id)
+        media_out = []
+        for m in media_rows:
+            ref = f"media/{m.id}"
+            rec = _row(m, _MEDIA_DROP)
+            rec["_file"] = ref
+            media_out.append(rec)
+            try:
+                media_blobs.append((ref, await store.get_object(key=m.storage_key)))
+            except Exception:  # noqa: BLE001 — a missing blob shouldn't abort the export
+                rec["_file"] = None
+
+        payload["trees"].append({
+            "tree": {
+                "name": tree.name,
+                "description": tree.description,
+                "visibility": tree.visibility,
+                "home_person_id": tree.home_person_id,
+            },
+            "places": [_row(p, _DROP) for p in await _entities(session, Place, tree.id)],
+            "persons": [_row(p, _DROP) for p in await _entities(session, Person, tree.id)],
+            "names": [_row(n, _DROP) for n in await _entities(session, Name, tree.id)],
+            "relationships": [
+                _row(r, _DROP) for r in await _entities(session, Relationship, tree.id)
+            ],
+            "events": [_row(e, _DROP) for e in await _entities(session, Event, tree.id)],
+            "sources": [_row(s, _DROP) for s in await _entities(session, Source, tree.id)],
+            "citations": [_row(c, _DROP) for c in await _entities(session, Citation, tree.id)],
+            "media": media_out,
+        })
+
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("account.json", json.dumps(payload, default=str, indent=2))
+        for ref, blob in media_blobs:
+            zf.writestr(ref, blob)
+    return buf.getvalue()
+
+
+def _as_uuid(v) -> uuid.UUID | None:
+    return uuid.UUID(v) if v else None
+
+
+def _as_date(v) -> date | None:
+    return date.fromisoformat(v) if v else None
+
+
+async def import_account(
+    session: AsyncSession, store: ObjectStore, *, user: User, raw_zip: bytes
+) -> dict:
+    """Restore an exported zip into NEW trees owned by the user. Non-destructive:
+    every record gets a fresh id; nothing existing is touched."""
+    try:
+        zf = zipfile.ZipFile(io.BytesIO(raw_zip))
+        payload = json.loads(zf.read("account.json"))
+    except (zipfile.BadZipFile, KeyError, json.JSONDecodeError) as e:
+        raise NotFound("not a valid Provenance export") from e
+
+    counts: dict[str, int] = {"trees": 0, "persons": 0, "events": 0, "media": 0}
+
+    for tdata in payload.get("trees", []):
+        t = tdata.get("tree", {})
+        tree = Tree(
+            owner_id=user.id,
+            name=(t.get("name") or "Imported tree"),
+            description=t.get("description"),
+            visibility=t.get("visibility") or "private",
+        )
+        session.add(tree)
+        await session.flush()
+        session.add(
+            TreeMembership(tree_id=tree.id, user_id=user.id, role=MembershipRole.owner)
+        )
+        counts["trees"] += 1
+
+        # id remaps from the export's ids to the freshly created ones.
+        pmap: dict[str, uuid.UUID] = {}
+        rmap: dict[str, uuid.UUID] = {}
+        smap: dict[str, uuid.UUID] = {}
+        nmap: dict[str, uuid.UUID] = {}
+        emap: dict[str, uuid.UUID] = {}
+        plmap: dict[str, uuid.UUID] = {}
+
+        for pl in tdata.get("places", []):
+            obj = Place(
+                tree_id=tree.id,
+                name=pl.get("name") or "",
+                place_type=pl.get("place_type"),
+                latitude=pl.get("latitude"),
+                longitude=pl.get("longitude"),
+            )
+            session.add(obj)
+            await session.flush()
+            plmap[pl["id"]] = obj.id
+
+        for p in tdata.get("persons", []):
+            obj = Person(
+                tree_id=tree.id,
+                gender=p.get("gender"),
+                is_living=p.get("is_living"),
+                privacy=p.get("privacy") or "inherit",
+                notes=p.get("notes"),
+            )
+            session.add(obj)
+            await session.flush()
+            pmap[p["id"]] = obj.id
+            counts["persons"] += 1
+
+        for n in tdata.get("names", []):
+            pid = pmap.get(n.get("person_id"))
+            if pid is None:
+                continue
+            obj = Name(
+                tree_id=tree.id,
+                person_id=pid,
+                name_type=n.get("name_type") or "birth",
+                given=n.get("given"),
+                surname=n.get("surname"),
+                prefix=n.get("prefix"),
+                suffix=n.get("suffix"),
+                nickname=n.get("nickname"),
+                display_name=n.get("display_name"),
+                is_primary=bool(n.get("is_primary")),
+                sort_order=n.get("sort_order") or 0,
+            )
+            session.add(obj)
+            await session.flush()
+            nmap[n["id"]] = obj.id
+
+        for r in tdata.get("relationships", []):
+            a = pmap.get(r.get("person_from_id"))
+            b = pmap.get(r.get("person_to_id"))
+            if a is None or b is None:
+                continue
+            obj = Relationship(
+                tree_id=tree.id,
+                type=r.get("type"),
+                person_from_id=a,
+                person_to_id=b,
+                qualifier=r.get("qualifier"),
+                notes=r.get("notes"),
+            )
+            session.add(obj)
+            await session.flush()
+            rmap[r["id"]] = obj.id
+
+        for e in tdata.get("events", []):
+            obj = Event(
+                tree_id=tree.id,
+                event_type=e.get("event_type") or "other",
+                person_id=pmap.get(e.get("person_id")),
+                relationship_id=rmap.get(e.get("relationship_id")),
+                place_id=plmap.get(e.get("place_id")),
+                date_value=e.get("date_value"),
+                date_start=_as_date(e.get("date_start")),
+                date_end=_as_date(e.get("date_end")),
+                date_precision=e.get("date_precision"),
+                calendar=e.get("calendar") or "gregorian",
+                detail=e.get("detail"),
+                notes=e.get("notes"),
+            )
+            session.add(obj)
+            await session.flush()
+            emap[e["id"]] = obj.id
+            counts["events"] += 1
+
+        for s in tdata.get("sources", []):
+            obj = Source(
+                tree_id=tree.id,
+                title=s.get("title") or "Untitled source",
+                author=s.get("author"),
+                source_type=s.get("source_type"),
+                repository=s.get("repository"),
+                url=s.get("url"),
+                citation_text=s.get("citation_text"),
+                publication_info=s.get("publication_info"),
+                quality_note=s.get("quality_note"),
+            )
+            session.add(obj)
+            await session.flush()
+            smap[s["id"]] = obj.id
+
+        for c in tdata.get("citations", []):
+            sid = smap.get(c.get("source_id"))
+            if sid is None:
+                continue
+            session.add(
+                Citation(
+                    tree_id=tree.id,
+                    source_id=sid,
+                    person_id=pmap.get(c.get("person_id")),
+                    event_id=emap.get(c.get("event_id")),
+                    name_id=nmap.get(c.get("name_id")),
+                    relationship_id=rmap.get(c.get("relationship_id")),
+                    page=c.get("page"),
+                    detail=c.get("detail"),
+                    confidence=c.get("confidence"),
+                )
+            )
+
+        for m in tdata.get("media", []):
+            ref = m.get("_file")
+            if not ref:
+                continue
+            try:
+                blob = zf.read(ref)
+            except KeyError:
+                continue
+            media_id = uuid.uuid4()
+            filename = m.get("original_filename") or "upload"
+            key = f"{tree.id}/{media_id}/{filename}"
+            await store.ensure_bucket()
+            await store.put_object(
+                key=key,
+                data=blob,
+                content_type=m.get("content_type") or "application/octet-stream",
+            )
+            session.add(
+                Media(
+                    id=media_id,
+                    tree_id=tree.id,
+                    uploader_id=user.id,
+                    storage_key=key,
+                    original_filename=filename,
+                    content_type=m.get("content_type") or "application/octet-stream",
+                    byte_size=len(blob),
+                    checksum_sha256=hashlib.sha256(blob).hexdigest(),
+                    title=m.get("title"),
+                    person_id=pmap.get(m.get("person_id")),
+                    event_id=emap.get(m.get("event_id")),
+                    source_id=smap.get(m.get("source_id")),
+                )
+            )
+            counts["media"] += 1
+
+        # Remap the home person last, once persons exist.
+        home = t.get("home_person_id")
+        if home and home in pmap:
+            tree.home_person_id = pmap[home]
+
+        record_audit(
+            session,
+            action="import",
+            entity_type="Account",
+            entity_id=tree.id,
+            tree_id=tree.id,
+            actor_user_id=user.id,
+            after=counts,
+        )
+
+    await session.commit()
+    return counts
+
+
+async def delete_account(session: AsyncSession, *, user: User, confirm_email: str) -> None:
+    """Soft-delete the account: the user, the trees they own, and all their
+    sessions. Requires the user to retype their email as a guard."""
+    if confirm_email.strip().lower() != user.email.lower():
+        raise Forbidden("email confirmation does not match")
+    now = datetime.now(UTC)
+
+    await session.execute(
+        update(Tree)
+        .where(Tree.owner_id == user.id, Tree.deleted_at.is_(None))
+        .values(deleted_at=now)
+    )
+    await session.execute(
+        update(SessionModel)
+        .where(SessionModel.user_id == user.id, SessionModel.revoked_at.is_(None))
+        .values(revoked_at=now)
+    )
+    user.deleted_at = now
+    record_audit(
+        session,
+        action="delete",
+        entity_type="User",
+        entity_id=user.id,
+        actor_user_id=user.id,
+    )
+    await session.commit()

backend/app/services/audit.py

@@ -3,6 +3,7 @@ the change to a User (or the assistant principal acting for a User). Staged on
 the session; the caller commits as part of its unit of work.
 """
 
+import json
 import uuid
 
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -11,6 +12,14 @@ from app.models.audit import AuditEntry
 from app.models.enums import AuditActorType
 
 
+def _json_safe(d: dict | None) -> dict | None:
+    """Coerce a change dict to JSON-native types (UUIDs, enums, dates -> str) so
+    it lands in the JSON audit column regardless of what the caller passed."""
+    if d is None:
+        return None
+    return json.loads(json.dumps(d, default=str))
+
+
 def record_audit(
     session: AsyncSession,
     *,
@@ -30,8 +39,8 @@ def record_audit(
         tree_id=tree_id,
         actor_user_id=actor_user_id,
         actor_type=actor_type,
-        before=before,
-        after=after,
+        before=_json_safe(before),
+        after=_json_safe(after),
     )
     session.add(entry)
     return entry

backend/app/services/auth_service.py

@@ -9,7 +9,7 @@ from sqlalchemy import select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.config import get_settings
-from app.core.security import generate_token, hash_password, hash_token
+from app.core.security import generate_token, hash_password, hash_token, verify_password
 from app.integrations.auth.local import LocalAuthProvider
 from app.integrations.mailer.base import Mailer
 from app.models.auth import Session as SessionModel
@@ -17,7 +17,7 @@ from app.models.auth import UserToken
 from app.models.enums import TokenPurpose
 from app.models.user import User
 from app.services.audit import record_audit
-from app.services.exceptions import Conflict, NotFound
+from app.services.exceptions import Conflict, Forbidden, NotFound
 
 _local_provider = LocalAuthProvider()
 
@@ -113,6 +113,8 @@ async def login(
     user = await _local_provider.authenticate(session, identifier=email, secret=password)
     if user is None:
         return None
+    if get_settings().require_email_verification and user.email_verified_at is None:
+        raise Forbidden("email not verified — check your inbox for the verification link")
     raw_token, record = _issue_session(session, user)
     record_audit(
         session, action="login", entity_type="User", entity_id=user.id, actor_user_id=user.id
@@ -141,11 +143,16 @@ async def resolve_session_user(session: AsyncSession, *, raw_token: str) -> User
     ).scalar_one_or_none()
     if record is None or record.revoked_at is not None or record.expires_at <= _now():
         return None
-    return (
+    user = (
         await session.execute(
             select(User).where(User.id == record.user_id, User.deleted_at.is_(None))
         )
     ).scalar_one_or_none()
+    # The single read-side enforcement: an unverified user has no active session
+    # when verification is required. Gates every authenticated request at once.
+    if user is not None and get_settings().require_email_verification and user.email_verified_at is None:
+        return None
+    return user
 
 
 async def verify_email(session: AsyncSession, *, raw_token: str) -> None:
@@ -178,6 +185,26 @@ async def request_password_reset(session: AsyncSession, mailer: Mailer, *, email
     await mailer.send_password_reset(to=email, link=_link("/auth/reset-password", raw))
 
 
+async def change_password(
+    session: AsyncSession, *, user: User, current_password: str, new_password: str
+) -> None:
+    """Change a logged-in user's password after re-verifying the current one.
+    Revokes other sessions so a changed password takes effect everywhere."""
+    if not user.hashed_password or not verify_password(
+        user.hashed_password, current_password
+    ):
+        raise Forbidden("current password is incorrect")
+    user.hashed_password = hash_password(new_password)
+    record_audit(
+        session,
+        action="change_password",
+        entity_type="User",
+        entity_id=user.id,
+        actor_user_id=user.id,
+    )
+    await session.commit()
+
+
 async def reset_password(session: AsyncSession, *, raw_token: str, new_password: str) -> None:
     token = await _consume_token(session, raw_token, TokenPurpose.password_reset)
     await session.execute(

backend/app/services/change_proposal_service.py

@@ -0,0 +1,355 @@
+"""ChangeProposal lifecycle: propose (assistant/contributor) → review → apply/reject.
+
+The structural guarantee (CLAUDE.md #1): a proposal's operations are executed
+ONLY by ``apply()``, which requires the actor be an editor and dispatches every
+op through the normal editing services — so each change passes the privacy
+engine and is audited as the approving human. ``propose()`` only inserts a
+pending row; it performs no domain mutation. See docs/design/change-proposal.md.
+"""
+
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.change_proposal import ChangeProposal
+from app.models.enums import (
+    ChangeProposalOrigin,
+    ChangeProposalStatus,
+    CitationConfidence,
+    ParentChildQualifier,
+    RelationshipType,
+)
+from app.models.tree import Tree
+from app.models.user import User
+from app.services import (
+    citation_service,
+    event_service,
+    name_service,
+    person_service,
+    privacy,
+    relationship_service,
+    source_service,
+)
+from app.services.exceptions import Conflict, Forbidden, NotFound
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+def _uuid(v) -> uuid.UUID | None:
+    return uuid.UUID(str(v)) if v else None
+
+
+async def _require_editor(session: AsyncSession, *, actor: User, tree: Tree) -> None:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+
+
+async def _require_member(session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tree) -> None:
+    # Proposals can reference unredacted facts → members only.
+    if await privacy.get_membership_role(session, viewer_id, tree.id) is None:
+        raise Forbidden("only members can see change proposals")
+
+
+async def _load(
+    session: AsyncSession, tree: Tree, proposal_id: uuid.UUID
+) -> ChangeProposal:
+    cp = (
+        await session.execute(
+            select(ChangeProposal).where(
+                ChangeProposal.id == proposal_id,
+                ChangeProposal.tree_id == tree.id,
+                ChangeProposal.deleted_at.is_(None),
+            )
+        )
+    ).scalar_one_or_none()
+    if cp is None:
+        raise NotFound("proposal not found")
+    return cp
+
+
+async def propose(
+    session: AsyncSession,
+    *,
+    tree: Tree,
+    origin: ChangeProposalOrigin,
+    created_by: uuid.UUID | None,
+    summary: str,
+    rationale: str | None,
+    operations: list[dict],
+) -> ChangeProposal:
+    """Insert a pending proposal. The ONLY mutation here is the proposal row — no
+    tree data changes. (No edit-rights check: proposing isn't writing.)"""
+    cp = ChangeProposal(
+        tree_id=tree.id,
+        origin=origin,
+        created_by_user_id=created_by,
+        summary=summary,
+        rationale=rationale,
+        operations=operations,
+        status=ChangeProposalStatus.pending,
+    )
+    session.add(cp)
+    await session.commit()
+    await session.refresh(cp)
+    return cp
+
+
+async def list_proposals(
+    session: AsyncSession,
+    *,
+    viewer_id: uuid.UUID,
+    tree: Tree,
+    status: ChangeProposalStatus | None = None,
+) -> list[ChangeProposal]:
+    await _require_member(session, viewer_id=viewer_id, tree=tree)
+    stmt = select(ChangeProposal).where(
+        ChangeProposal.tree_id == tree.id, ChangeProposal.deleted_at.is_(None)
+    )
+    if status is not None:
+        stmt = stmt.where(ChangeProposal.status == status)
+    stmt = stmt.order_by(ChangeProposal.created_at.desc())
+    return list((await session.execute(stmt)).scalars().all())
+
+
+async def get_proposal(
+    session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tree, proposal_id: uuid.UUID
+) -> ChangeProposal:
+    await _require_member(session, viewer_id=viewer_id, tree=tree)
+    return await _load(session, tree, proposal_id)
+
+
+async def reject(
+    session: AsyncSession,
+    *,
+    actor: User,
+    tree: Tree,
+    proposal_id: uuid.UUID,
+    note: str | None = None,
+) -> ChangeProposal:
+    await _require_editor(session, actor=actor, tree=tree)
+    cp = await _load(session, tree, proposal_id)
+    if cp.status is not ChangeProposalStatus.pending:
+        raise Conflict("proposal is not pending")
+    cp.status = ChangeProposalStatus.rejected
+    cp.reviewed_by_user_id = actor.id
+    cp.reviewed_at = _now()
+    cp.review_note = note
+    await session.commit()
+    await session.refresh(cp)
+    return cp
+
+
+async def apply(
+    session: AsyncSession,
+    *,
+    actor: User,
+    tree: Tree,
+    proposal_id: uuid.UUID,
+    edited_operations: list[dict] | None = None,
+) -> ChangeProposal:
+    await _require_editor(session, actor=actor, tree=tree)
+    cp = await _load(session, tree, proposal_id)
+    if cp.status is not ChangeProposalStatus.pending:
+        raise Conflict("proposal is not pending")
+    ops = edited_operations if edited_operations is not None else list(cp.operations)
+    try:
+        for op in ops:
+            await _dispatch(session, actor=actor, tree=tree, op=op)
+    except Conflict:
+        raise
+    except Exception as exc:  # noqa: BLE001 — record the failure on the proposal
+        err = f"{type(exc).__name__}: {exc}"[:2000]
+        # The editing services raise (NotFound/Forbidden/validation) before
+        # committing, so the transaction is clean — record the error and commit.
+        # If a later op did write before failing, those ops already committed
+        # (v1 isn't cross-op transactional; see the design note).
+        cp = await _load(session, tree, proposal_id)
+        cp.apply_error = err
+        await session.commit()
+        raise Conflict(f"could not apply proposal: {err}") from exc
+    if edited_operations is not None:
+        cp.operations = edited_operations
+    cp.status = ChangeProposalStatus.applied
+    cp.reviewed_by_user_id = actor.id
+    cp.reviewed_at = _now()
+    cp.apply_error = None
+    await session.commit()
+    await session.refresh(cp)
+    return cp
+
+
+async def delete_proposal(
+    session: AsyncSession, *, actor: User, tree: Tree, proposal_id: uuid.UUID
+) -> None:
+    await _require_editor(session, actor=actor, tree=tree)
+    cp = await _load(session, tree, proposal_id)
+    cp.deleted_at = _now()
+    await session.commit()
+
+
+def _bad(entity_type: str, action: str) -> Conflict:
+    return Conflict(f"unsupported operation '{action}' on '{entity_type}'")
+
+
+async def _dispatch(session: AsyncSession, *, actor: User, tree: Tree, op: dict) -> None:
+    """Route one operation through the matching editing service (privacy + audit)."""
+    et = op.get("entity_type")
+    action = op.get("op")
+    payload = op.get("payload") or {}
+    eid = op.get("entity_id")
+
+    if et == "person":
+        if action == "create":
+            await person_service.create_person(
+                session,
+                actor=actor,
+                tree=tree,
+                given=payload.get("given"),
+                surname=payload.get("surname"),
+                gender=payload.get("gender"),
+                is_living=payload.get("is_living"),
+                notes=payload.get("notes"),
+            )
+        elif action == "update":
+            await person_service.update_person(
+                session, actor=actor, tree=tree, person_id=_uuid(eid), changes=payload
+            )
+        elif action == "delete":
+            await person_service.delete_person(
+                session,
+                actor=actor,
+                tree=tree,
+                person_id=_uuid(eid),
+                cascade=bool(payload.get("cascade", False)),
+            )
+        else:
+            raise _bad(et, action)
+    elif et == "event":
+        if action == "create":
+            await event_service.create_event(
+                session,
+                actor=actor,
+                tree=tree,
+                event_type=payload["event_type"],
+                person_id=_uuid(payload.get("person_id")),
+                relationship_id=_uuid(payload.get("relationship_id")),
+                date_value=payload.get("date_value"),
+                date_precision=payload.get("date_precision"),
+                detail=payload.get("detail"),
+                notes=payload.get("notes"),
+            )
+        elif action == "update":
+            await event_service.update_event(
+                session, actor=actor, tree=tree, event_id=_uuid(eid), changes=payload
+            )
+        elif action == "delete":
+            await event_service.delete_event(
+                session, actor=actor, tree=tree, event_id=_uuid(eid)
+            )
+        else:
+            raise _bad(et, action)
+    elif et == "relationship":
+        if action == "create":
+            await relationship_service.create_relationship(
+                session,
+                actor=actor,
+                tree=tree,
+                type=RelationshipType(payload["type"]),
+                person_from_id=_uuid(payload["person_from_id"]),
+                person_to_id=_uuid(payload["person_to_id"]),
+                qualifier=ParentChildQualifier(payload["qualifier"])
+                if payload.get("qualifier")
+                else None,
+                notes=payload.get("notes"),
+            )
+        elif action == "delete":
+            await relationship_service.delete_relationship(
+                session, actor=actor, tree=tree, relationship_id=_uuid(eid)
+            )
+        else:
+            raise _bad(et, action)
+    elif et == "name":
+        if action == "create":
+            await name_service.create_name(
+                session,
+                actor=actor,
+                tree=tree,
+                person_id=_uuid(payload["person_id"]),
+                name_type=payload.get("name_type", "birth"),
+                given=payload.get("given"),
+                surname=payload.get("surname"),
+                prefix=payload.get("prefix"),
+                suffix=payload.get("suffix"),
+                nickname=payload.get("nickname"),
+                is_primary=bool(payload.get("is_primary", False)),
+            )
+        elif action == "update":
+            changes = {k: v for k, v in payload.items() if k != "person_id"}
+            await name_service.update_name(
+                session,
+                actor=actor,
+                tree=tree,
+                person_id=_uuid(payload["person_id"]),
+                name_id=_uuid(eid),
+                changes=changes,
+            )
+        elif action == "delete":
+            await name_service.delete_name(
+                session,
+                actor=actor,
+                tree=tree,
+                person_id=_uuid(payload["person_id"]),
+                name_id=_uuid(eid),
+            )
+        else:
+            raise _bad(et, action)
+    elif et == "source":
+        if action == "create":
+            await source_service.create_source(
+                session,
+                actor=actor,
+                tree=tree,
+                title=payload["title"],
+                author=payload.get("author"),
+                source_type=payload.get("source_type"),
+                repository=payload.get("repository"),
+                url=payload.get("url"),
+                citation_text=payload.get("citation_text"),
+                publication_info=payload.get("publication_info"),
+                quality_note=payload.get("quality_note"),
+            )
+        elif action == "delete":
+            await source_service.delete_source(
+                session, actor=actor, tree=tree, source_id=_uuid(eid)
+            )
+        else:
+            raise _bad(et, action)
+    elif et == "citation":
+        if action == "create":
+            await citation_service.create_citation(
+                session,
+                actor=actor,
+                tree=tree,
+                source_id=_uuid(payload["source_id"]),
+                person_id=_uuid(payload.get("person_id")),
+                event_id=_uuid(payload.get("event_id")),
+                name_id=_uuid(payload.get("name_id")),
+                relationship_id=_uuid(payload.get("relationship_id")),
+                page=payload.get("page"),
+                detail=payload.get("detail"),
+                confidence=CitationConfidence(payload["confidence"])
+                if payload.get("confidence")
+                else None,
+            )
+        elif action == "delete":
+            await citation_service.delete_citation(
+                session, actor=actor, tree=tree, citation_id=_uuid(eid)
+            )
+        else:
+            raise _bad(et, action)
+    else:
+        raise Conflict(f"unsupported entity type '{et}'")

backend/app/services/citation_service.py

@@ -113,6 +113,38 @@ async def list_citations(
     return list((await session.execute(stmt)).scalars().all())
 
 
+async def update_citation(
+    session: AsyncSession, *, actor: User, tree: Tree, citation_id: uuid.UUID, changes: dict
+) -> Citation:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    citation = (
+        await session.execute(
+            select(Citation).where(
+                Citation.id == citation_id,
+                Citation.tree_id == tree.id,
+                Citation.deleted_at.is_(None),
+            )
+        )
+    ).scalar_one_or_none()
+    if citation is None:
+        raise NotFound("citation not found")
+    for key in {"page", "detail", "confidence"} & changes.keys():
+        setattr(citation, key, changes[key])
+    record_audit(
+        session,
+        action="update",
+        entity_type="Citation",
+        entity_id=citation.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after=changes,
+    )
+    await session.commit()
+    await session.refresh(citation)
+    return citation
+
+
 async def delete_citation(
     session: AsyncSession, *, actor: User, tree: Tree, citation_id: uuid.UUID
 ) -> None:

backend/app/services/cleanup_service.py

@@ -0,0 +1,337 @@
+"""Bulk tree cleanup — preview/apply pairs for common import messes.
+
+Per the project's #1 rule (the assistant proposes, humans approve), each fix has
+a *preview* that returns the proposed changes and an *apply* that commits only
+the ids/edits the user confirmed. Nothing here mutates without an explicit apply
+call carrying the user's selections.
+"""
+
+import re
+import uuid
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.enums import RelationshipType
+from app.models.event import Event
+from app.models.person import Name, Person
+from app.models.relationship import Relationship
+from app.models.tree import Tree
+from app.models.user import User
+from app.services import gedcom, privacy
+from app.services.audit import record_audit
+from app.services.exceptions import Forbidden, NotFound
+from app.services.name_gender_data import guess_sex
+
+
+async def _require_editor(session: AsyncSession, *, actor: User, tree: Tree) -> None:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+
+
+async def _persons(session: AsyncSession, tree_id: uuid.UUID) -> list[Person]:
+    return list(
+        (
+            await session.execute(
+                select(Person).where(Person.tree_id == tree_id, Person.deleted_at.is_(None))
+            )
+        ).scalars().all()
+    )
+
+
+async def _primary_name_by_person(
+    session: AsyncSession, tree_id: uuid.UUID
+) -> dict[uuid.UUID, Name]:
+    names = (
+        await session.execute(
+            select(Name)
+            .where(Name.tree_id == tree_id, Name.deleted_at.is_(None))
+            .order_by(Name.is_primary.desc(), Name.sort_order)
+        )
+    ).scalars().all()
+    out: dict[uuid.UUID, Name] = {}
+    for n in names:
+        out.setdefault(n.person_id, n)
+    return out
+
+
+async def _birth_year_by_person(session: AsyncSession, tree_id: uuid.UUID) -> dict[uuid.UUID, int]:
+    evs = (
+        await session.execute(
+            select(Event).where(
+                Event.tree_id == tree_id,
+                Event.deleted_at.is_(None),
+                Event.event_type == "birth",
+            )
+        )
+    ).scalars().all()
+    out: dict[uuid.UUID, int] = {}
+    for e in evs:
+        if not e.person_id or e.person_id in out:
+            continue
+        y = e.date_start.year if e.date_start else None
+        if y is None:
+            ys = gedcom._year(e.date_value)
+            y = int(ys) if ys else None
+        if y is not None:
+            out[e.person_id] = y
+    return out
+
+
+def _display(n: Name | None) -> str:
+    if n is None:
+        return "Unnamed"
+    return " ".join(x for x in (n.given, n.surname) if x) or (n.display_name or "Unnamed")
+
+
+# ---- 1. Mark deceased by birth year -------------------------------------------------
+
+async def preview_deceased(
+    session: AsyncSession, *, actor: User, tree: Tree, year: int
+) -> list[dict]:
+    await _require_editor(session, actor=actor, tree=tree)
+    names = await _primary_name_by_person(session, tree.id)
+    years = await _birth_year_by_person(session, tree.id)
+    out: list[dict] = []
+    for p in await _persons(session, tree.id):
+        if p.is_living is False:  # already deceased
+            continue
+        by = years.get(p.id)
+        if by is not None and by <= year:
+            out.append(
+                {"person_id": str(p.id), "name": _display(names.get(p.id)), "birth_year": by}
+            )
+    out.sort(key=lambda r: r["birth_year"])
+    return out
+
+
+async def apply_deceased(
+    session: AsyncSession, *, actor: User, tree: Tree, person_ids: list[uuid.UUID]
+) -> int:
+    await _require_editor(session, actor=actor, tree=tree)
+    persons = (
+        await session.execute(
+            select(Person).where(
+                Person.tree_id == tree.id,
+                Person.deleted_at.is_(None),
+                Person.id.in_(person_ids),
+            )
+        )
+    ).scalars().all()
+    for p in persons:
+        p.is_living = False
+    record_audit(
+        session,
+        action="cleanup_deceased",
+        entity_type="Tree",
+        entity_id=tree.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after={"count": len(persons)},
+    )
+    await session.commit()
+    return len(persons)
+
+
+# ---- 2. Re-derive gender from a source GEDCOM (matches by name) ----------------------
+
+async def preview_gender(
+    session: AsyncSession, *, actor: User, tree: Tree, gedcom_text: str
+) -> list[dict]:
+    await _require_editor(session, actor=actor, tree=tree)
+    name2sex: dict[str, str] = {}
+    for rec in gedcom.parse_records(gedcom_text):
+        if rec.tag != "INDI":
+            continue
+        summ = gedcom._person_summary(rec)
+        sex = gedcom._sex(rec.text("SEX"))
+        if sex and summ["norm"]:
+            name2sex.setdefault(summ["norm"], sex)
+
+    names = await _primary_name_by_person(session, tree.id)
+    out: list[dict] = []
+    for p in await _persons(session, tree.id):
+        if p.gender:  # only fill in what's missing
+            continue
+        nm = names.get(p.id)
+        if nm is None:
+            continue
+        proposed = name2sex.get(gedcom._norm(nm.given, nm.surname))
+        if proposed:
+            out.append({"person_id": str(p.id), "name": _display(nm), "proposed_gender": proposed})
+    out.sort(key=lambda r: r["name"])
+    return out
+
+
+async def guess_gender_by_name(
+    session: AsyncSession, *, actor: User, tree: Tree
+) -> list[dict]:
+    """Best-guess sex from the first given name for people who don't have it set,
+    using the bundled name dictionary. Ambiguous/unknown names are skipped."""
+    await _require_editor(session, actor=actor, tree=tree)
+    names = await _primary_name_by_person(session, tree.id)
+    out: list[dict] = []
+    for p in await _persons(session, tree.id):
+        if p.gender:
+            continue
+        nm = names.get(p.id)
+        if nm is None:
+            continue
+        proposed = guess_sex(nm.given)
+        if proposed:
+            out.append({"person_id": str(p.id), "name": _display(nm), "proposed_gender": proposed})
+    out.sort(key=lambda r: r["name"])
+    return out
+
+
+async def guess_gender_by_spouse(
+    session: AsyncSession, *, actor: User, tree: Tree
+) -> list[dict]:
+    """Infer the sex of a person who has none set from a partner whose sex IS set
+    (couples in a tree are opposite-sex in practice — e.g. a confirmed-male
+    husband implies a female wife). People whose known partners disagree are
+    ambiguous and skipped; the result is a preview to review, not an auto-write."""
+    await _require_editor(session, actor=actor, tree=tree)
+    persons = await _persons(session, tree.id)
+    gender = {p.id: p.gender for p in persons}
+    names = await _primary_name_by_person(session, tree.id)
+    rels = (
+        await session.execute(
+            select(Relationship).where(
+                Relationship.tree_id == tree.id,
+                Relationship.deleted_at.is_(None),
+                Relationship.type == RelationshipType.partnership,
+            )
+        )
+    ).scalars().all()
+    opp = {"male": "female", "female": "male"}
+    proposals: dict[uuid.UUID, set[str]] = {}
+    for r in rels:
+        for me_id, other_id in (
+            (r.person_from_id, r.person_to_id),
+            (r.person_to_id, r.person_from_id),
+        ):
+            if gender.get(me_id):
+                continue  # this person already has a sex
+            other_sex = str(gender.get(other_id) or "")
+            if other_sex in opp:
+                proposals.setdefault(me_id, set()).add(opp[other_sex])
+    out: list[dict] = []
+    for pid, sexes in proposals.items():
+        if len(sexes) != 1:
+            continue  # partners of differing known sex → ambiguous
+        nm = names.get(pid)
+        if nm is None:
+            continue
+        out.append(
+            {"person_id": str(pid), "name": _display(nm), "proposed_gender": next(iter(sexes))}
+        )
+    out.sort(key=lambda r: r["name"])
+    return out
+
+
+async def apply_gender(
+    session: AsyncSession, *, actor: User, tree: Tree, updates: list[dict]
+) -> int:
+    """updates: [{person_id, gender}]."""
+    await _require_editor(session, actor=actor, tree=tree)
+    wanted = {uuid.UUID(str(u["person_id"])): u["gender"] for u in updates if u.get("gender")}
+    persons = (
+        await session.execute(
+            select(Person).where(
+                Person.tree_id == tree.id,
+                Person.deleted_at.is_(None),
+                Person.id.in_(wanted.keys()),
+            )
+        )
+    ).scalars().all()
+    for p in persons:
+        p.gender = wanted[p.id]
+    record_audit(
+        session,
+        action="cleanup_gender",
+        entity_type="Tree",
+        entity_id=tree.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after={"count": len(persons)},
+    )
+    await session.commit()
+    return len(persons)
+
+
+# ---- 3. Flag malformed names for review --------------------------------------------
+
+_YEAR_RE = re.compile(r"\b\d{3,4}\b")
+
+
+def _name_issue(n: Name) -> str | None:
+    given = (n.given or "").strip()
+    surname = (n.surname or "").strip()
+    if _YEAR_RE.search(surname) or re.search(r"\d", surname):
+        return "date_in_surname"
+    if re.search(r"\d", given):
+        return "date_in_given"
+    # A given name with many tokens often means a maiden+married name was packed
+    # in (e.g. "Mary Smith Jones") — surface it for a human to split.
+    if surname == "" and len(given.split()) >= 2:
+        return "no_surname"
+    if len(given.split()) >= 3:
+        return "packed_given"
+    return None
+
+
+async def preview_names(session: AsyncSession, *, actor: User, tree: Tree) -> list[dict]:
+    await _require_editor(session, actor=actor, tree=tree)
+    names = (
+        await session.execute(
+            select(Name).where(Name.tree_id == tree.id, Name.deleted_at.is_(None))
+        )
+    ).scalars().all()
+    out: list[dict] = []
+    for n in names:
+        issue = _name_issue(n)
+        if issue:
+            out.append({
+                "name_id": str(n.id),
+                "person_id": str(n.person_id),
+                "given": n.given,
+                "surname": n.surname,
+                "issue": issue,
+            })
+    return out
+
+
+async def apply_names(
+    session: AsyncSession, *, actor: User, tree: Tree, edits: list[dict]
+) -> int:
+    """edits: [{name_id, given, surname}] — the user's corrected values."""
+    await _require_editor(session, actor=actor, tree=tree)
+    by_id = {uuid.UUID(str(e["name_id"])): e for e in edits}
+    rows = (
+        await session.execute(
+            select(Name).where(
+                Name.tree_id == tree.id,
+                Name.deleted_at.is_(None),
+                Name.id.in_(by_id.keys()),
+            )
+        )
+    ).scalars().all()
+    if len(rows) != len(by_id):
+        raise NotFound("one or more names not found in this tree")
+    for n in rows:
+        e = by_id[n.id]
+        n.given = (e.get("given") or "").strip() or None
+        n.surname = (e.get("surname") or "").strip() or None
+        n.display_name = None  # rebuild from parts
+    record_audit(
+        session,
+        action="cleanup_names",
+        entity_type="Tree",
+        entity_id=tree.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after={"count": len(rows)},
+    )
+    await session.commit()
+    return len(rows)

backend/app/services/event_service.py

@@ -97,6 +97,13 @@ async def list_events(
     """All events in the tree — lets the family view compute birth/death years."""
     if not await privacy.can_view_tree(session, user_id=viewer_id, tree=tree):
         raise Forbidden("not permitted to view this tree")
+    # Non-members get the redacted projection (no living-person dates).
+    if await privacy.get_membership_role(session, viewer_id, tree.id) is None:
+        from app.services import public_view_service
+
+        return await public_view_service.list_public_events(
+            session, viewer_id=viewer_id, tree=tree
+        )
     stmt = (
         select(Event)
         .where(Event.tree_id == tree.id, Event.deleted_at.is_(None))
@@ -110,6 +117,13 @@ async def list_events_for_person(
 ) -> list[Event]:
     if not await privacy.can_view_tree(session, user_id=viewer_id, tree=tree):
         raise Forbidden("not permitted to view this tree")
+    # Non-members only see a full-visibility person's events (redacted → none).
+    if await privacy.get_membership_role(session, viewer_id, tree.id) is None:
+        from app.services import public_view_service
+
+        return await public_view_service.list_public_person_events(
+            session, viewer_id=viewer_id, tree=tree, person_id=person_id
+        )
     stmt = (
         select(Event)
         .where(
@@ -122,6 +136,44 @@ async def list_events_for_person(
     return list((await session.execute(stmt)).scalars().all())
 
 
+async def update_event(
+    session: AsyncSession,
+    *,
+    actor: User,
+    tree: Tree,
+    event_id: uuid.UUID,
+    changes: dict,
+) -> Event:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    event = (
+        await session.execute(
+            select(Event).where(
+                Event.id == event_id, Event.tree_id == tree.id, Event.deleted_at.is_(None)
+            )
+        )
+    ).scalar_one_or_none()
+    if event is None:
+        raise NotFound("event not found")
+    if "place_id" in changes and changes["place_id"] is not None:
+        if not await _belongs_to_tree(session, Place, changes["place_id"], tree.id):
+            raise NotFound("place not found in this tree")
+    for key, value in changes.items():
+        setattr(event, key, value)
+    record_audit(
+        session,
+        action="update",
+        entity_type="Event",
+        entity_id=event.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after=changes,
+    )
+    await session.commit()
+    await session.refresh(event)
+    return event
+
+
 async def delete_event(
     session: AsyncSession, *, actor: User, tree: Tree, event_id: uuid.UUID
 ) -> None:

backend/app/services/gedcom.py

@@ -4,14 +4,20 @@ A pragmatic parser + mapper for the common subset of GEDCOM (5.5.1 / 7 share
 the line grammar): INDI, FAM, SOUR. Import maps records into a tree and returns
 a mapping report (counts + unmapped tags); export serializes the tree back to
 GEDCOM. Runs inline for now — large files should move to the worker later.
+
+Import is duplicate-aware: ``preview_gedcom`` reports incoming people that look
+like existing ones, and ``import_gedcom`` applies a per-record resolution
+(new / skip / merge / overwrite). Names carry their GEDCOM type (a married name
+imports as a typed alternate, not a second primary).
 """
 
 import re
 import uuid
 from collections import defaultdict
-from datetime import date
+from datetime import UTC, date, datetime
+from difflib import SequenceMatcher
 
-from sqlalchemy import select
+from sqlalchemy import or_, select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.models.enums import ParentChildQualifier, RelationshipType
@@ -32,12 +38,31 @@ INDI_EVENTS = {
     "BURI": "burial", "CREM": "cremation", "RESI": "residence", "CENS": "census",
     "IMMI": "immigration", "EMIG": "emigration", "OCCU": "occupation",
     "EDUC": "education", "GRAD": "graduation", "RETI": "retirement",
-    "NATU": "naturalization", "BAPL": "baptism",
+    "NATU": "naturalization", "BAPL": "baptism", "RELI": "religion",
+}
+# INDI attribute tags whose line VALUE is the fact (no date), stored in detail.
+VALUE_EVENTS = {"RELI", "OCCU", "EDUC"}
+# INDI sub-tags consumed elsewhere or intentionally ignored (not "unmapped").
+INDI_SKIP_TAGS = {
+    "NAME", "SEX", "SOUR", "FAMC", "FAMS", "CHAN", "OBJE", "_UID", "_MARNM", "NOTE",
 }
 # FAM-level events.
 FAM_EVENTS = {"MARR": "marriage", "DIV": "divorce", "ENGA": "engagement"}
 EVENT_TO_GED = {v: k for k, v in {**INDI_EVENTS, **FAM_EVENTS}.items()}
 
+# GEDCOM NAME TYPE (or _MARNM-derived) -> our Name.name_type vocabulary.
+NAME_TYPE_MAP = {
+    "birth": "birth", "maiden": "birth", "married": "married",
+    "aka": "alias", "also known as": "alias", "nickname": "nickname",
+    "religious": "religious", "immigrant": "immigration",
+    "immigration": "immigration", "professional": "alias", "other": "alias",
+}
+# Our type -> GEDCOM TYPE on export (birth is the default; emit nothing).
+EXPORT_TYPE_MAP = {
+    "married": "married", "alias": "aka", "nickname": "nickname",
+    "religious": "religious", "immigration": "immigrant",
+}
+
 
 class GedcomNode:
     __slots__ = ("level", "tag", "value", "xref", "children")
@@ -108,6 +133,50 @@ def _parse_name(value: str) -> tuple[str | None, str | None]:
     return value.strip() or None, None
 
 
+def _parse_marnm(value: str, base_given: str | None) -> tuple[str | None, str | None]:
+    """A _MARNM value is sometimes a full name ("Jane /Smith/") and sometimes
+    just the married surname ("Smith"). Keep the given name from the base name
+    in the latter case."""
+    v = (value or "").strip()
+    if "/" in v:
+        g, s = _parse_name(v)
+        return (g or base_given), s
+    return base_given, (v or None)
+
+
+def _extract_names(rec: GedcomNode) -> list[dict]:
+    """All names for an INDI, typed. Multiple NAME records (each with an optional
+    TYPE) plus any _MARNM (married name) subtags become separate Name rows. The
+    first birth/maiden name is primary."""
+    out: list[dict] = []
+    for nm in rec.all("NAME"):
+        g, s = _parse_name(nm.value)
+        t = (nm.text("TYPE") or "").strip().lower()
+        ntype = NAME_TYPE_MAP.get(t, t or "birth")
+        out.append({"type": ntype, "given": g, "surname": s, "display": nm.value or None,
+                    "nickname": nm.text("NICK")})
+        for mar in nm.all("_MARNM"):
+            mg, ms = _parse_marnm(mar.value, g)
+            out.append({"type": "married", "given": mg, "surname": ms,
+                        "display": mar.value or None, "nickname": None})
+    for mar in rec.all("_MARNM"):
+        base_g = out[0]["given"] if out else None
+        mg, ms = _parse_marnm(mar.value, base_g)
+        out.append({"type": "married", "given": mg, "surname": ms,
+                    "display": mar.value or None, "nickname": None})
+    if not out:
+        return out
+    primary_idx = next((i for i, n in enumerate(out) if n["type"] == "birth"), 0)
+    for i, n in enumerate(out):
+        n["is_primary"] = i == primary_idx
+        n["sort"] = i
+    return out
+
+
+def _norm(given: str | None, surname: str | None) -> str:
+    return re.sub(r"\s+", " ", f"{given or ''} {surname or ''}".strip().lower())
+
+
 def _year(date_value: str | None) -> str | None:
     if not date_value:
         return None
@@ -132,18 +201,215 @@ def _sex(value: str | None) -> str | None:
     return {"M": "male", "F": "female"}.get(v, value.strip().lower() or None)
 
 
+def _notes_text(rec: GedcomNode) -> str | None:
+    """Join an INDI's NOTE lines (which pack confidence / findagrave / fs_pid /
+    free text) into the person's notes field."""
+    vals = [n.value.strip() for n in rec.all("NOTE") if n.value and n.value.strip()]
+    return "\n".join(vals) or None
+
+
+def _person_summary(rec: GedcomNode) -> dict:
+    """Display name + birth year for an incoming INDI, for duplicate matching."""
+    names = _extract_names(rec)
+    primary = next((n for n in names if n.get("is_primary")), names[0] if names else None)
+    g = primary["given"] if primary else None
+    s = primary["surname"] if primary else None
+    disp = " ".join(x for x in (g, s) if x)
+    if not disp and primary:
+        disp = primary.get("display") or ""
+    birth = rec.first("BIRT")
+    year = _year(birth.text("DATE")) if birth else None
+    return {"names": names, "norm": _norm(g, s), "name": disp or "(no name)", "year": year}
+
+
+async def _build_existing_index(session: AsyncSession, tree: Tree) -> list[dict]:
+    """Existing (non-deleted) people with a display name + birth year, for
+    matching incoming records against."""
+    persons = list(
+        (
+            await session.execute(
+                select(Person).where(Person.tree_id == tree.id, Person.deleted_at.is_(None))
+            )
+        ).scalars().all()
+    )
+    names = list(
+        (
+            await session.execute(
+                select(Name).where(Name.tree_id == tree.id, Name.deleted_at.is_(None))
+            )
+        ).scalars().all()
+    )
+    name_by_person: dict[uuid.UUID, Name] = {}
+    for n in sorted(names, key=lambda n: (not n.is_primary, n.sort_order)):
+        name_by_person.setdefault(n.person_id, n)
+    births = list(
+        (
+            await session.execute(
+                select(Event).where(
+                    Event.tree_id == tree.id,
+                    Event.deleted_at.is_(None),
+                    Event.event_type == "birth",
+                )
+            )
+        ).scalars().all()
+    )
+    year_by_person: dict[uuid.UUID, str] = {}
+    for e in births:
+        if e.person_id and e.person_id not in year_by_person:
+            y = str(e.date_start.year) if e.date_start else _year(e.date_value)
+            if y:
+                year_by_person[e.person_id] = y
+
+    index: list[dict] = []
+    for p in persons:
+        nm = name_by_person.get(p.id)
+        g = nm.given if nm else None
+        s = nm.surname if nm else None
+        disp = " ".join(x for x in (g, s) if x) or (nm.display_name if nm else None)
+        index.append({
+            "id": p.id,
+            "norm": _norm(g, s),
+            "name": disp or "(no name)",
+            "year": year_by_person.get(p.id),
+        })
+    return index
+
+
+def _best_match(norm: str, year: str | None, index: list[dict]) -> tuple[dict | None, str | None]:
+    """Closest existing person by name similarity, rejecting clear birth-year
+    conflicts. Returns (entry, "high"|"medium") or (None, None)."""
+    if not norm:
+        return None, None
+    best: dict | None = None
+    best_r = 0.0
+    for e in index:
+        if not e["norm"]:
+            continue
+        r = SequenceMatcher(None, norm, e["norm"]).ratio()
+        if r < 0.88:
+            continue
+        if year and e["year"] and abs(int(year) - int(e["year"])) > 1:
+            continue  # same-ish name but different birth year — not a duplicate
+        if r > best_r:
+            best_r = r
+            best = e
+    if best is None:
+        return None, None
+    year_match = bool(year and best["year"] and abs(int(year) - int(best["year"])) <= 1)
+    both_unknown = not year and not best["year"]
+    score = "high" if best_r >= 0.93 and (year_match or both_unknown) else "medium"
+    return best, score
+
+
+def _relkey(rtype: RelationshipType, a: uuid.UUID, b: uuid.UUID) -> tuple:
+    if rtype == RelationshipType.parent_child:
+        return ("pc", str(a), str(b))
+    return (rtype.value, *sorted([str(a), str(b)]))
+
+
+def _count_incoming(roots: list[GedcomNode]) -> tuple[dict, list[str]]:
+    counts: dict[str, int] = defaultdict(int)
+    unmapped: set[str] = set()
+    for rec in roots:
+        if rec.tag == "INDI" and rec.xref:
+            counts["persons"] += 1
+            counts["names"] += len(_extract_names(rec))
+            for child in rec.children:
+                if child.tag in INDI_EVENTS:
+                    counts["events"] += 1
+                elif child.tag not in INDI_SKIP_TAGS:
+                    unmapped.add(child.tag)
+        elif rec.tag == "FAM":
+            counts["families"] += 1
+            for child in rec.children:
+                if child.tag in FAM_EVENTS:
+                    counts["events"] += 1
+        elif rec.tag == "SOUR" and rec.xref:
+            counts["sources"] += 1
+    return dict(counts), sorted(unmapped)
+
+
+async def preview_gedcom(session: AsyncSession, *, actor: User, tree: Tree, text: str) -> dict:
+    """Dry run: what would import, and which incoming people look like existing
+    ones. No writes."""
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    roots = parse_records(text)
+    counts, unmapped = _count_incoming(roots)
+    index = await _build_existing_index(session, tree)
+
+    duplicates: list[dict] = []
+    for rec in roots:
+        if rec.tag != "INDI" or not rec.xref:
+            continue
+        summ = _person_summary(rec)
+        entry, score = _best_match(summ["norm"], summ["year"], index)
+        if entry is None:
+            continue
+        duplicates.append({
+            "xref": rec.xref,
+            "incoming_name": summ["name"],
+            "incoming_birth_year": summ["year"],
+            "existing_person_id": entry["id"],
+            "existing_name": entry["name"],
+            "existing_birth_year": entry["year"],
+            "score": score,
+        })
+    return {"counts": counts, "potential_duplicates": duplicates, "unmapped_tags": unmapped}
+
+
 async def import_gedcom(
-    session: AsyncSession, *, actor: User, tree: Tree, text: str
+    session: AsyncSession,
+    *,
+    actor: User,
+    tree: Tree,
+    text: str,
+    default_action: str = "new",
+    resolutions: dict | None = None,
 ) -> dict:
+    """Import records. ``default_action`` (new|skip|merge|overwrite) applies to
+    incoming people that match an existing one; ``resolutions`` overrides it per
+    GEDCOM xref ({xref: {action, target_id}}). 'skip' links families to the
+    existing person but copies nothing; 'merge' also copies the incoming names
+    (as alternates), events and citations onto them; 'overwrite' deletes the
+    existing person and imports the incoming one fresh."""
     if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
         raise Forbidden("not an editor of this tree")
 
+    resolutions = resolutions or {}
     roots = parse_records(text)
-    counts = defaultdict(int)
+    counts: dict[str, int] = defaultdict(int)
     unmapped: set[str] = set()
     place_cache: dict[str, uuid.UUID] = {}
     source_map: dict[str, uuid.UUID] = {}
     person_map: dict[str, uuid.UUID] = {}
+    now = datetime.now(UTC)
+
+    index = await _build_existing_index(session, tree)
+
+    # Pre-load existing relationship keys so a merge doesn't create dup edges.
+    existing_rels = list(
+        (
+            await session.execute(
+                select(Relationship).where(
+                    Relationship.tree_id == tree.id, Relationship.deleted_at.is_(None)
+                )
+            )
+        ).scalars().all()
+    )
+    rel_keys = {_relkey(r.type, r.person_from_id, r.person_to_id) for r in existing_rels}
+
+    def add_relationship(
+        rtype: RelationshipType, a: uuid.UUID, b: uuid.UUID, **kw
+    ) -> Relationship | None:
+        key = _relkey(rtype, a, b)
+        if key in rel_keys:
+            return None
+        rel = Relationship(tree_id=tree.id, type=rtype, person_from_id=a, person_to_id=b, **kw)
+        session.add(rel)
+        rel_keys.add(key)
+        counts["relationships"] += 1
+        return rel
 
     async def place_id(name: str | None) -> uuid.UUID | None:
         if not name:
@@ -177,59 +443,139 @@ async def import_gedcom(
             sid = source_map.get(s.value.strip())
             if sid is None:
                 continue
-            session.add(
-                Citation(tree_id=tree.id, source_id=sid, page=s.text("PAGE"), **target)
-            )
+            session.add(Citation(tree_id=tree.id, source_id=sid, page=s.text("PAGE"), **target))
             counts["citations"] += 1
 
-    # Individuals.
-    for rec in roots:
-        if rec.tag != "INDI" or not rec.xref:
-            continue
-        person = Person(tree_id=tree.id, gender=_sex(rec.text("SEX")))
-        session.add(person)
-        await session.flush()
-        person_map[rec.xref] = person.id
-        counts["persons"] += 1
-
-        for i, nm in enumerate(rec.all("NAME")):
-            given, surname = _parse_name(nm.value)
+    def add_names(person_id: uuid.UUID, names: list[dict], *, set_primary: bool) -> None:
+        for nd in names:
             session.add(
                 Name(
                     tree_id=tree.id,
-                    person_id=person.id,
-                    name_type="birth",
-                    given=given,
-                    surname=surname,
-                    display_name=nm.value or None,
-                    is_primary=(i == 0),
-                    sort_order=i,
+                    person_id=person_id,
+                    name_type=nd["type"],
+                    given=nd["given"],
+                    surname=nd["surname"],
+                    nickname=nd.get("nickname"),
+                    display_name=nd.get("display"),
+                    is_primary=set_primary and nd.get("is_primary", False),
+                    sort_order=nd.get("sort", 0),
                 )
             )
             counts["names"] += 1
 
-        await add_citations(rec, person_id=person.id)
-
+    async def add_events(rec: GedcomNode, person_id: uuid.UUID) -> None:
         for child in rec.children:
             if child.tag in INDI_EVENTS:
                 dv = child.text("DATE")
+                # Attribute-style facts (RELI, OCCU, EDUC) carry their value on
+                # the line itself; store it in detail.
+                detail = child.value.strip() if child.tag in VALUE_EVENTS else None
                 ev = Event(
                     tree_id=tree.id,
-                    person_id=person.id,
+                    person_id=person_id,
                     event_type=INDI_EVENTS[child.tag],
                     date_value=dv,
                     date_start=_date_start(dv),
                     place_id=await place_id(child.text("PLAC")),
+                    detail=detail or None,
+                    notes=child.text("NOTE"),
                 )
                 session.add(ev)
                 await session.flush()
                 counts["events"] += 1
                 await add_citations(child, event_id=ev.id)
-            elif child.tag in ("NAME", "SEX", "SOUR", "FAMC", "FAMS", "CHAN", "OBJE", "_UID"):
+            elif child.tag in INDI_SKIP_TAGS:
                 continue
             else:
                 unmapped.add(child.tag)
 
+    async def soft_delete_existing(person_id: uuid.UUID) -> None:
+        p = (
+            await session.execute(
+                select(Person).where(Person.id == person_id, Person.deleted_at.is_(None))
+            )
+        ).scalar_one_or_none()
+        if p is None:
+            return
+        p.deleted_at = now
+        rels = (
+            await session.execute(
+                select(Relationship).where(
+                    Relationship.tree_id == tree.id,
+                    Relationship.deleted_at.is_(None),
+                    or_(
+                        Relationship.person_from_id == person_id,
+                        Relationship.person_to_id == person_id,
+                    ),
+                )
+            )
+        ).scalars().all()
+        for r in rels:
+            r.deleted_at = now
+        await session.execute(
+            update(User).where(User.self_person_id == person_id).values(self_person_id=None)
+        )
+
+    # Precompute the best match per incoming xref (for default-policy resolution).
+    matches: dict[str, dict] = {}
+    for rec in roots:
+        if rec.tag == "INDI" and rec.xref:
+            summ = _person_summary(rec)
+            entry, _score = _best_match(summ["norm"], summ["year"], index)
+            if entry is not None:
+                matches[rec.xref] = entry
+
+    def resolve(xref: str) -> tuple[str, uuid.UUID | None]:
+        ov = resolutions.get(xref)
+        if ov:
+            action = ov.get("action", "new")
+            tid = ov.get("target_id")
+            target = uuid.UUID(tid) if tid else (matches[xref]["id"] if xref in matches else None)
+            if action in ("skip", "merge", "overwrite") and target is None:
+                return "new", None
+            return action, target
+        if default_action != "new" and xref in matches:
+            return default_action, matches[xref]["id"]
+        return "new", None
+
+    # Individuals.
+    for rec in roots:
+        if rec.tag != "INDI" or not rec.xref:
+            continue
+        names = _extract_names(rec)
+        action, target = resolve(rec.xref)
+
+        if action == "skip" and target is not None:
+            person_map[rec.xref] = target
+            counts["skipped"] += 1
+            continue
+        if action == "merge" and target is not None:
+            person_map[rec.xref] = target
+            add_names(target, names, set_primary=False)
+            await add_events(rec, target)
+            await add_citations(rec, person_id=target)
+            note = _notes_text(rec)
+            if note:
+                existing = (
+                    await session.execute(select(Person).where(Person.id == target))
+                ).scalar_one_or_none()
+                if existing is not None:
+                    existing.notes = "\n".join(filter(None, [existing.notes, note]))
+            counts["merged"] += 1
+            continue
+        if action == "overwrite" and target is not None:
+            await soft_delete_existing(target)
+            counts["overwritten"] += 1
+
+        person = Person(tree_id=tree.id, gender=_sex(rec.text("SEX")), notes=_notes_text(rec))
+        session.add(person)
+        await session.flush()
+        person_map[rec.xref] = person.id
+        counts["persons"] += 1
+        add_names(person.id, names, set_primary=True)
+        await add_citations(rec, person_id=person.id)
+        await add_events(rec, person.id)
+
     # Families -> partnerships, parent-child edges, marriage events.
     for rec in roots:
         if rec.tag != "FAM":
@@ -238,17 +584,22 @@ async def import_gedcom(
         husb = person_map.get((rec.text("HUSB") or "").strip())
         wife = person_map.get((rec.text("WIFE") or "").strip())
         partnership_id: uuid.UUID | None = None
-        if husb and wife:
-            rel = Relationship(
-                tree_id=tree.id,
-                type=RelationshipType.partnership,
-                person_from_id=husb,
-                person_to_id=wife,
+        if husb and wife and husb != wife:
+            rel = add_relationship(RelationshipType.partnership, husb, wife)
+            if rel is not None:
+                await session.flush()
+                partnership_id = rel.id
+        if partnership_id is None and husb and wife:
+            # Edge already existed — find it so marriage events can attach.
+            existing = next(
+                (
+                    r for r in existing_rels
+                    if r.type == RelationshipType.partnership
+                    and {r.person_from_id, r.person_to_id} == {husb, wife}
+                ),
+                None,
             )
-            session.add(rel)
-            await session.flush()
-            partnership_id = rel.id
-            counts["relationships"] += 1
+            partnership_id = existing.id if existing else None
 
         for fe in rec.children:
             if fe.tag in FAM_EVENTS and partnership_id is not None:
@@ -271,16 +622,12 @@ async def import_gedcom(
                 continue
             for parent in (husb, wife):
                 if parent and parent != cp:
-                    session.add(
-                        Relationship(
-                            tree_id=tree.id,
-                            type=RelationshipType.parent_child,
-                            person_from_id=parent,
-                            person_to_id=cp,
-                            qualifier=ParentChildQualifier.biological,
-                        )
+                    add_relationship(
+                        RelationshipType.parent_child,
+                        parent,
+                        cp,
+                        qualifier=ParentChildQualifier.biological,
                     )
-                    counts["relationships"] += 1
 
     record_audit(
         session,
@@ -345,10 +692,45 @@ async def export_gedcom(session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tr
             await session.execute(select(Place).where(Place.tree_id == tree.id))
         ).scalars().all()
     }
+    citations = list(
+        (
+            await session.execute(
+                select(Citation).where(
+                    Citation.tree_id == tree.id, Citation.deleted_at.is_(None)
+                )
+            )
+        ).scalars().all()
+    )
 
     pxref = {p.id: f"@I{i + 1}@" for i, p in enumerate(persons)}
     gender_by_id = {p.id: p.gender for p in persons}
     sxref = {s.id: f"@S{i + 1}@" for i, s in enumerate(sources)}
+    # Citations grouped by the fact they sit on, so each fact can emit its SOUR
+    # links (dropping these is the round-trip data loss this fixes). Skip any
+    # whose source didn't export.
+    cite_by_person: dict[uuid.UUID, list[Citation]] = defaultdict(list)
+    cite_by_name: dict[uuid.UUID, list[Citation]] = defaultdict(list)
+    cite_by_event: dict[uuid.UUID, list[Citation]] = defaultdict(list)
+    cite_by_rel: dict[uuid.UUID, list[Citation]] = defaultdict(list)
+    for c in citations:
+        if c.source_id not in sxref:
+            continue
+        if c.person_id:
+            cite_by_person[c.person_id].append(c)
+        elif c.event_id:
+            cite_by_event[c.event_id].append(c)
+        elif c.name_id:
+            cite_by_name[c.name_id].append(c)
+        elif c.relationship_id:
+            cite_by_rel[c.relationship_id].append(c)
+
+    def cite_lines(cites: list[Citation], depth: int) -> list[str]:
+        lines: list[str] = []
+        for c in cites:
+            lines.append(f"{depth} SOUR {sxref[c.source_id]}")
+            if c.page:
+                lines.append(f"{depth + 1} PAGE {c.page}")
+        return lines
     names_by_person: dict[uuid.UUID, list[Name]] = defaultdict(list)
     for n in sorted(names, key=lambda n: (n.sort_order, not n.is_primary)):
         names_by_person[n.person_id].append(n)
@@ -397,6 +779,10 @@ async def export_gedcom(session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tr
         for n in names_by_person.get(p.id, []):
             display = n.display_name or f"{n.given or ''} /{n.surname or ''}/".strip()
             out.append(f"1 NAME {display}")
+            ged_type = EXPORT_TYPE_MAP.get(n.name_type)
+            if ged_type:
+                out.append(f"2 TYPE {ged_type}")
+            out += cite_lines(cite_by_name.get(n.id, []), 2)
         sex = {"male": "M", "female": "F"}.get(p.gender or "")
         if sex:
             out.append(f"1 SEX {sex}")
@@ -409,6 +795,8 @@ async def export_gedcom(session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tr
                 out.append(f"2 DATE {e.date_value}")
             if e.place_id and e.place_id in places:
                 out.append(f"2 PLAC {places[e.place_id].name}")
+            out += cite_lines(cite_by_event.get(e.id, []), 2)
+        out += cite_lines(cite_by_person.get(p.id, []), 1)
         if p.id in child_fams:
             out.append(f"1 FAMC {child_fams[p.id]}")
         for x in spouse_fams.get(p.id, []):
@@ -437,6 +825,8 @@ async def export_gedcom(session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tr
                 out.append(f"1 {tag}")
                 if _ged_date(e.date_value):
                     out.append(f"2 DATE {e.date_value}")
+                out += cite_lines(cite_by_event.get(e.id, []), 2)
+            out += cite_lines(cite_by_rel.get(f["rel_id"], []), 1)
 
     for s in sources:
         out.append(f"0 {sxref[s.id]} SOUR")

backend/app/services/media_service.py

@@ -72,6 +72,13 @@ async def upload_media(
 async def list_media(session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tree) -> list[Media]:
     if not await privacy.can_view_tree(session, user_id=viewer_id, tree=tree):
         raise Forbidden("not permitted to view this tree")
+    # Non-members only see media of a FULL-visibility person (no living-person photos).
+    if await privacy.get_membership_role(session, viewer_id, tree.id) is None:
+        from app.services import public_view_service
+
+        return await public_view_service.list_public_media(
+            session, viewer_id=viewer_id, tree=tree
+        )
     stmt = (
         select(Media)
         .where(Media.tree_id == tree.id, Media.deleted_at.is_(None))
@@ -94,6 +101,45 @@ async def get_media(
     ).scalar_one_or_none()
     if media is None:
         raise NotFound("media not found")
+    # Non-members may only see/download media of a FULL-visibility person. 404
+    # (not 403) so the item's existence isn't revealed. This gates media_content.
+    if await privacy.get_membership_role(session, viewer_id, tree.id) is None:
+        from app.services import public_view_service
+
+        if not await public_view_service.can_view_media(
+            session, viewer_id=viewer_id, tree=tree, media=media
+        ):
+            raise NotFound("media not found")
+    return media
+
+
+async def update_media(
+    session: AsyncSession, *, actor: User, tree: Tree, media_id: uuid.UUID, changes: dict
+) -> Media:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    media = (
+        await session.execute(
+            select(Media).where(
+                Media.id == media_id, Media.tree_id == tree.id, Media.deleted_at.is_(None)
+            )
+        )
+    ).scalar_one_or_none()
+    if media is None:
+        raise NotFound("media not found")
+    for key in {"title", "person_id", "event_id", "source_id"} & changes.keys():
+        setattr(media, key, changes[key])
+    record_audit(
+        session,
+        action="update",
+        entity_type="Media",
+        entity_id=media.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after=changes,
+    )
+    await session.commit()
+    await session.refresh(media)
     return media
 
 

backend/app/services/membership_service.py

@@ -0,0 +1,156 @@
+"""Tree membership management: list / add / change-role / remove.
+
+Only an owner may change membership. A tree must always keep at least one owner.
+The member list (which exposes user emails) is visible only to members — never
+to a non-member viewing a public/unlisted tree.
+"""
+
+import uuid
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.enums import MembershipRole
+from app.models.tree import Tree, TreeMembership
+from app.models.user import User
+from app.services import privacy
+from app.services.audit import record_audit
+from app.services.exceptions import Conflict, Forbidden, NotFound
+
+
+async def _require_owner(session: AsyncSession, *, actor_id: uuid.UUID, tree: Tree) -> None:
+    if await privacy.get_membership_role(session, actor_id, tree.id) is not MembershipRole.owner:
+        raise Forbidden("only the owner can manage members")
+
+
+async def _owner_count(session: AsyncSession, tree_id: uuid.UUID) -> int:
+    return (
+        await session.execute(
+            select(func.count())
+            .select_from(TreeMembership)
+            .where(TreeMembership.tree_id == tree_id, TreeMembership.role == MembershipRole.owner)
+        )
+    ).scalar_one()
+
+
+def _row(m: TreeMembership, u: User) -> dict:
+    return {
+        "id": m.id,
+        "user_id": u.id,
+        "email": u.email,
+        "display_name": u.display_name,
+        "role": m.role,
+        "created_at": m.created_at,
+    }
+
+
+async def list_members(session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tree) -> list[dict]:
+    # Member-only: the list exposes emails, so a non-member (even on a public
+    # tree) must not see it.
+    if await privacy.get_membership_role(session, viewer_id, tree.id) is None:
+        raise Forbidden("only members can see the member list")
+    rows = (
+        await session.execute(
+            select(TreeMembership, User)
+            .join(User, User.id == TreeMembership.user_id)
+            .where(TreeMembership.tree_id == tree.id)
+            .order_by(TreeMembership.created_at)
+        )
+    ).all()
+    return [_row(m, u) for m, u in rows]
+
+
+async def add_member(
+    session: AsyncSession, *, actor: User, tree: Tree, email: str, role: MembershipRole
+) -> dict:
+    await _require_owner(session, actor_id=actor.id, tree=tree)
+    user = (
+        await session.execute(
+            select(User).where(User.email == email, User.deleted_at.is_(None))
+        )
+    ).scalar_one_or_none()
+    if user is None:
+        raise NotFound("no user with that email on this instance")
+    if await privacy.get_membership_role(session, user.id, tree.id) is not None:
+        raise Conflict("that user is already a member")
+    m = TreeMembership(tree_id=tree.id, user_id=user.id, role=role)
+    session.add(m)
+    record_audit(
+        session,
+        action="add_member",
+        entity_type="Tree",
+        entity_id=tree.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after={"user_id": str(user.id), "role": role.value},
+    )
+    await session.commit()
+    await session.refresh(m)
+    return _row(m, user)
+
+
+async def _get_membership(
+    session: AsyncSession, tree: Tree, membership_id: uuid.UUID
+) -> TreeMembership:
+    m = (
+        await session.execute(
+            select(TreeMembership).where(
+                TreeMembership.id == membership_id, TreeMembership.tree_id == tree.id
+            )
+        )
+    ).scalar_one_or_none()
+    if m is None:
+        raise NotFound("member not found")
+    return m
+
+
+async def update_member_role(
+    session: AsyncSession,
+    *,
+    actor: User,
+    tree: Tree,
+    membership_id: uuid.UUID,
+    role: MembershipRole,
+) -> dict:
+    await _require_owner(session, actor_id=actor.id, tree=tree)
+    m = await _get_membership(session, tree, membership_id)
+    if (
+        m.role == MembershipRole.owner
+        and role != MembershipRole.owner
+        and await _owner_count(session, tree.id) <= 1
+    ):
+        raise Conflict("a tree must keep at least one owner")
+    m.role = role
+    record_audit(
+        session,
+        action="update_member",
+        entity_type="Tree",
+        entity_id=tree.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after={"membership_id": str(m.id), "role": role.value},
+    )
+    await session.commit()
+    await session.refresh(m)
+    u = (await session.execute(select(User).where(User.id == m.user_id))).scalar_one()
+    return _row(m, u)
+
+
+async def remove_member(
+    session: AsyncSession, *, actor: User, tree: Tree, membership_id: uuid.UUID
+) -> None:
+    await _require_owner(session, actor_id=actor.id, tree=tree)
+    m = await _get_membership(session, tree, membership_id)
+    if m.role == MembershipRole.owner and await _owner_count(session, tree.id) <= 1:
+        raise Conflict("a tree must keep at least one owner")
+    await session.delete(m)
+    record_audit(
+        session,
+        action="remove_member",
+        entity_type="Tree",
+        entity_id=tree.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after={"membership_id": str(membership_id)},
+    )
+    await session.commit()

backend/app/services/name_gender_data.py

@@ -0,0 +1,69 @@
+"""A curated given-name -> sex lookup for best-guessing a person's sex from
+their first name. Weighted toward English + German names (this codebase's first
+real tree is a German-American family). Deterministic and offline — no model
+needed; the Cleanup tool previews every guess before anything is applied.
+
+Genuinely ambiguous names (Marion, Frances/Francis, Jordan, Jamie, Robin, Leslie,
+Dana, …) are intentionally left out of BOTH sets so they aren't guessed — better
+a human decides those than a coin flip.
+"""
+
+MALE_NAMES: set[str] = {
+    # English / common US
+    "james", "john", "robert", "michael", "william", "david", "richard", "joseph",
+    "thomas", "charles", "christopher", "daniel", "matthew", "anthony", "donald",
+    "mark", "paul", "steven", "andrew", "kenneth", "george", "joshua", "kevin",
+    "brian", "edward", "ronald", "timothy", "jason", "jeffrey", "gary", "ryan",
+    "nicholas", "eric", "stephen", "jacob", "larry", "frank", "jonathan", "scott",
+    "raymond", "gregory", "samuel", "benjamin", "patrick", "jack", "dennis", "jerry",
+    "alexander", "tyler", "henry", "douglas", "peter", "adam", "harold", "albert",
+    "arthur", "carl", "ralph", "roy", "eugene", "louis", "philip", "bobby", "walter",
+    "willie", "wayne", "fred", "howard", "ernest", "earl", "clarence", "leon",
+    "leonard", "lewis", "floyd", "leroy", "elmer", "homer", "orrin", "josias",
+    "emerson", "dale", "bernard", "vernon", "virgil", "wilbur", "russell",
+    "harvey", "herbert", "melvin", "lloyd", "marvin", "norman", "stanley",
+    # German
+    "hans", "karl", "wilhelm", "friedrich", "heinrich", "otto", "hermann", "gustav",
+    "ludwig", "ernst", "fritz", "johann", "conrad", "konrad", "reinhold", "rudolf",
+    "rudolph", "gerhard", "helmut", "horst", "klaus", "kurt", "dieter", "günther",
+    "gunther", "manfred", "siegfried", "hilgard", "christian", "august", "wolfgang",
+    "jürgen", "jurgen", "matthias", "lothar", "bruno", "gottlieb", "reinhard",
+}
+
+FEMALE_NAMES: set[str] = {
+    # English / common US
+    "mary", "patricia", "jennifer", "linda", "elizabeth", "barbara", "susan",
+    "jessica", "sarah", "karen", "nancy", "lisa", "betty", "margaret", "sandra",
+    "ashley", "kimberly", "emily", "donna", "michelle", "carol", "amanda", "dorothy",
+    "melissa", "deborah", "stephanie", "rebecca", "sharon", "laura", "cynthia",
+    "kathleen", "amy", "angela", "shirley", "anna", "ruth", "brenda", "pamela",
+    "nicole", "katherine", "virginia", "catherine", "helen", "debra", "rachel",
+    "carolyn", "janet", "maria", "heather", "diane", "julie", "joyce", "victoria",
+    "kelly", "christina", "joan", "evelyn", "judith", "megan", "alice", "frances",
+    "marie", "florence", "flora", "zella", "thelma", "ellen", "althea", "della",
+    "beatrice", "pauline", "hedwig", "florentine", "wilhelmina", "augusta", "bertha",
+    "gladys", "mildred", "lucille", "edith", "esther", "irene", "hazel", "doris",
+    "rose", "rita", "norma", "june", "lois", "marjorie",
+    # German
+    "greta", "ilse", "ursula", "gertrud", "gertrude", "frieda", "frida", "else",
+    "hilda", "hilde", "hildegard", "ingrid", "helga", "renate", "monika", "sieglinde",
+    "brigitte", "gisela", "elke", "anneliese", "waltraud", "edeltraud", "johanna",
+    "katharina", "margarethe", "wilhelmine", "emilie", "auguste",
+}
+
+
+def guess_sex(given: str | None) -> str | None:
+    """Best-guess "male"/"female" from the first token of a given name, or None
+    if unknown/ambiguous."""
+    if not given:
+        return None
+    first = given.strip().split()[0].lower() if given.strip() else ""
+    # Strip trailing punctuation/initials like "wm." -> "wm".
+    first = first.strip(".,'\"")
+    if not first:
+        return None
+    if first in MALE_NAMES:
+        return "male"
+    if first in FEMALE_NAMES:
+        return "female"
+    return None

backend/app/services/name_service.py

@@ -0,0 +1,215 @@
+"""Name service. A Person carries one or more Name rows — a primary (typically
+the birth/maiden name) plus typed alternates (married, alias, religious, …).
+Exactly one name is primary at a time; it drives display everywhere. Writes
+require editor rights; reads go through the tree's view check.
+"""
+
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.person import Name, Person
+from app.models.tree import Tree
+from app.models.user import User
+from app.services import privacy
+from app.services.audit import record_audit
+from app.services.exceptions import Forbidden, NotFound
+
+
+async def _get_person(session: AsyncSession, *, tree: Tree, person_id: uuid.UUID) -> Person:
+    person = (
+        await session.execute(
+            select(Person).where(
+                Person.id == person_id, Person.tree_id == tree.id, Person.deleted_at.is_(None)
+            )
+        )
+    ).scalar_one_or_none()
+    if person is None:
+        raise NotFound("person not found")
+    return person
+
+
+async def _clear_primary(
+    session: AsyncSession, *, person_id: uuid.UUID, keep: uuid.UUID | None
+) -> None:
+    """Demote every other name so exactly one stays primary."""
+    stmt = (
+        update(Name)
+        .where(Name.person_id == person_id, Name.deleted_at.is_(None), Name.is_primary.is_(True))
+        .values(is_primary=False)
+    )
+    if keep is not None:
+        stmt = stmt.where(Name.id != keep)
+    await session.execute(stmt)
+
+
+async def list_names(
+    session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tree, person_id: uuid.UUID
+) -> list[Name]:
+    if not await privacy.can_view_tree(session, user_id=viewer_id, tree=tree):
+        raise Forbidden("not permitted to view this tree")
+    await _get_person(session, tree=tree, person_id=person_id)
+    # Non-members: a redacted/hidden person's real names must not leak.
+    if await privacy.get_membership_role(session, viewer_id, tree.id) is None:
+        from app.services import public_view_service
+
+        return await public_view_service.list_public_person_names(
+            session, viewer_id=viewer_id, tree=tree, person_id=person_id
+        )
+    stmt = (
+        select(Name)
+        .where(Name.person_id == person_id, Name.deleted_at.is_(None))
+        .order_by(Name.is_primary.desc(), Name.sort_order, Name.created_at)
+    )
+    return list((await session.execute(stmt)).scalars().all())
+
+
+async def create_name(
+    session: AsyncSession,
+    *,
+    actor: User,
+    tree: Tree,
+    person_id: uuid.UUID,
+    name_type: str = "birth",
+    given: str | None = None,
+    surname: str | None = None,
+    prefix: str | None = None,
+    suffix: str | None = None,
+    nickname: str | None = None,
+    is_primary: bool = False,
+) -> Name:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    await _get_person(session, tree=tree, person_id=person_id)
+
+    # First name for a person is always primary; otherwise honor the flag.
+    existing = (
+        await session.execute(
+            select(Name.id).where(Name.person_id == person_id, Name.deleted_at.is_(None))
+        )
+    ).first()
+    primary = is_primary or existing is None
+    if primary:
+        await _clear_primary(session, person_id=person_id, keep=None)
+
+    name = Name(
+        tree_id=tree.id,
+        person_id=person_id,
+        name_type=name_type,
+        given=given,
+        surname=surname,
+        prefix=prefix,
+        suffix=suffix,
+        nickname=nickname,
+        is_primary=primary,
+    )
+    session.add(name)
+    await session.flush()
+    record_audit(
+        session,
+        action="create",
+        entity_type="Name",
+        entity_id=name.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after={"name_type": name_type, "given": given, "surname": surname},
+    )
+    await session.commit()
+    await session.refresh(name)
+    return name
+
+
+_NAME_FIELDS = {"name_type", "given", "surname", "prefix", "suffix", "nickname"}
+
+
+async def update_name(
+    session: AsyncSession,
+    *,
+    actor: User,
+    tree: Tree,
+    person_id: uuid.UUID,
+    name_id: uuid.UUID,
+    changes: dict,
+) -> Name:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    name = (
+        await session.execute(
+            select(Name).where(
+                Name.id == name_id,
+                Name.person_id == person_id,
+                Name.tree_id == tree.id,
+                Name.deleted_at.is_(None),
+            )
+        )
+    ).scalar_one_or_none()
+    if name is None:
+        raise NotFound("name not found")
+
+    for key in _NAME_FIELDS & changes.keys():
+        setattr(name, key, changes[key])
+    if changes.get("is_primary") is True:
+        await _clear_primary(session, person_id=person_id, keep=name.id)
+        name.is_primary = True
+
+    record_audit(
+        session,
+        action="update",
+        entity_type="Name",
+        entity_id=name.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after=changes,
+    )
+    await session.commit()
+    await session.refresh(name)
+    return name
+
+
+async def delete_name(
+    session: AsyncSession,
+    *,
+    actor: User,
+    tree: Tree,
+    person_id: uuid.UUID,
+    name_id: uuid.UUID,
+) -> None:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    name = (
+        await session.execute(
+            select(Name).where(
+                Name.id == name_id,
+                Name.person_id == person_id,
+                Name.tree_id == tree.id,
+                Name.deleted_at.is_(None),
+            )
+        )
+    ).scalar_one_or_none()
+    if name is None:
+        raise NotFound("name not found")
+    name.deleted_at = datetime.now(UTC)
+    was_primary = name.is_primary
+    name.is_primary = False
+    record_audit(
+        session,
+        action="delete",
+        entity_type="Name",
+        entity_id=name.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+    )
+    # Promote another name to primary so the person never loses their display name.
+    if was_primary:
+        nxt = (
+            await session.execute(
+                select(Name)
+                .where(Name.person_id == person_id, Name.deleted_at.is_(None))
+                .order_by(Name.sort_order, Name.created_at)
+            )
+        ).scalars().first()
+        if nxt is not None:
+            nxt.is_primary = True
+    await session.commit()

backend/app/services/person_service.py

@@ -6,11 +6,12 @@ person through the privacy engine. Each returned Person gets a transient
 import uuid
 from datetime import UTC, datetime
 
-from sqlalchemy import select
+from sqlalchemy import func, or_, select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.models.enums import PersonPrivacy
+from app.models.enums import PersonPrivacy, RelationshipType
 from app.models.person import Name, Person
+from app.models.relationship import Relationship
 from app.models.tree import Tree
 from app.models.user import User
 from app.services import privacy
@@ -25,6 +26,14 @@ def _format_name(name: Name) -> str | None:
     return joined or name.display_name
 
 
+def _redact(person: Person) -> None:
+    """Minimise a possibly-living person for a non-member view (transient only —
+    never committed)."""
+    person.primary_name = "Living person"
+    person.gender = None
+    person.is_living = True
+
+
 async def _attach_primary_name(session: AsyncSession, person: Person) -> None:
     stmt = (
         select(Name)
@@ -87,6 +96,59 @@ async def create_person(
     return person
 
 
+_PERSON_FIELDS = {"gender", "is_living", "privacy", "notes"}
+
+
+async def update_person(
+    session: AsyncSession, *, actor: User, tree: Tree, person_id: uuid.UUID, changes: dict
+) -> Person:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    person = (
+        await session.execute(
+            select(Person).where(
+                Person.id == person_id, Person.tree_id == tree.id, Person.deleted_at.is_(None)
+            )
+        )
+    ).scalar_one_or_none()
+    if person is None:
+        raise NotFound("person not found")
+
+    for key in _PERSON_FIELDS & changes.keys():
+        setattr(person, key, changes[key])
+
+    if "given" in changes or "surname" in changes:
+        name = (
+            await session.execute(
+                select(Name)
+                .where(Name.person_id == person.id, Name.deleted_at.is_(None))
+                .order_by(Name.is_primary.desc(), Name.sort_order)
+            )
+        ).scalars().first()
+        if name is None:
+            name = Name(tree_id=tree.id, person_id=person.id, name_type="birth", is_primary=True)
+            session.add(name)
+        if "given" in changes:
+            name.given = changes["given"]
+        if "surname" in changes:
+            name.surname = changes["surname"]
+        name.display_name = None  # rebuild display from parts
+
+    record_audit(
+        session,
+        action="update",
+        entity_type="Person",
+        entity_id=person.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after=changes,
+    )
+    await session.commit()
+    await session.refresh(person)
+    await _attach_primary_name(session, person)
+    return person
+
+
 async def get_person(
     session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tree, person_id: uuid.UUID
 ) -> Person:
@@ -104,18 +166,77 @@ async def get_person(
     if person is None:
         raise NotFound("person not found")
     # Run the single person through the privacy engine (redaction lands Phase 2).
-    if (
-        await privacy.person_visibility(session, user_id=viewer_id, tree=tree, person=person)
-        == Visibility.hidden
-    ):
+    vis = await privacy.person_visibility(
+        session, user_id=viewer_id, tree=tree, person=person
+    )
+    if vis == Visibility.hidden:
         raise NotFound("person not found")
-    await _attach_primary_name(session, person)
+    if vis == Visibility.redacted:
+        _redact(person)
+    else:
+        await _attach_primary_name(session, person)
     return person
 
 
-async def delete_person(
-    session: AsyncSession, *, actor: User, tree: Tree, person_id: uuid.UUID
+async def _children_of(
+    session: AsyncSession, *, tree_id: uuid.UUID, parent_id: uuid.UUID
+) -> list[uuid.UUID]:
+    rows = (
+        await session.execute(
+            select(Relationship.person_to_id).where(
+                Relationship.tree_id == tree_id,
+                Relationship.deleted_at.is_(None),
+                Relationship.type == RelationshipType.parent_child,
+                Relationship.person_from_id == parent_id,
+            )
+        )
+    ).scalars().all()
+    return list(rows)
+
+
+async def _soft_delete_one(
+    session: AsyncSession, *, actor: User, tree: Tree, person: Person, now: datetime
 ) -> None:
+    """Soft-delete a single person and the relationships touching them, so no
+    dangling edges are left to break the tree view."""
+    person.deleted_at = now
+    rels = (
+        await session.execute(
+            select(Relationship).where(
+                Relationship.tree_id == tree.id,
+                Relationship.deleted_at.is_(None),
+                or_(
+                    Relationship.person_from_id == person.id,
+                    Relationship.person_to_id == person.id,
+                ),
+            )
+        )
+    ).scalars().all()
+    for rel in rels:
+        rel.deleted_at = now
+    record_audit(
+        session,
+        action="delete",
+        entity_type="Person",
+        entity_id=person.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after={"cascaded_relationships": len(rels)},
+    )
+
+
+async def delete_person(
+    session: AsyncSession,
+    *,
+    actor: User,
+    tree: Tree,
+    person_id: uuid.UUID,
+    cascade: bool = False,
+) -> int:
+    """Soft-delete a person. Always removes the relationships that touch them
+    (preventing dangling edges). With ``cascade=True``, recursively deletes
+    their descendants too — handy for pruning a bad GEDCOM import. Returns the
+    number of persons deleted."""
     if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
         raise Forbidden("not an editor of this tree")
     person = (
@@ -127,16 +248,52 @@ async def delete_person(
     ).scalar_one_or_none()
     if person is None:
         raise NotFound("person not found")
-    person.deleted_at = datetime.now(UTC)
-    record_audit(
-        session,
-        action="delete",
-        entity_type="Person",
-        entity_id=person.id,
-        tree_id=tree.id,
-        actor_user_id=actor.id,
+
+    now = datetime.now(UTC)
+
+    # Gather the set of persons to delete. For cascade, walk descendants
+    # breadth-first, guarding against cycles.
+    to_delete: list[Person] = [person]
+    if cascade:
+        seen = {person.id}
+        frontier = [person.id]
+        while frontier:
+            nxt: list[uuid.UUID] = []
+            for pid in frontier:
+                for child_id in await _children_of(session, tree_id=tree.id, parent_id=pid):
+                    if child_id not in seen:
+                        seen.add(child_id)
+                        nxt.append(child_id)
+            frontier = nxt
+        extra_ids = [pid for pid in seen if pid != person.id]
+        if extra_ids:
+            extra = (
+                await session.execute(
+                    select(Person).where(
+                        Person.id.in_(extra_ids),
+                        Person.tree_id == tree.id,
+                        Person.deleted_at.is_(None),
+                    )
+                )
+            ).scalars().all()
+            to_delete.extend(extra)
+
+    for p in to_delete:
+        await _soft_delete_one(session, actor=actor, tree=tree, person=p, now=now)
+
+    # Soft delete leaves the row in place, so the DB-level "ON DELETE SET NULL"
+    # never fires — clear any links (account self-person, tree home person) to a
+    # deleted person.
+    deleted_ids = [p.id for p in to_delete]
+    await session.execute(
+        update(User).where(User.self_person_id.in_(deleted_ids)).values(self_person_id=None)
     )
+    await session.execute(
+        update(Tree).where(Tree.home_person_id.in_(deleted_ids)).values(home_person_id=None)
+    )
+
     await session.commit()
+    return len(to_delete)
 
 
 async def restore_person(
@@ -199,13 +356,66 @@ async def list_persons(
 
     visible: list[Person] = []
     for person in persons:
-        if (
-            await privacy.person_visibility(
-                session, user_id=viewer_id, tree=tree, person=person
-            )
-            == Visibility.hidden
-        ):
+        vis = await privacy.person_visibility(
+            session, user_id=viewer_id, tree=tree, person=person
+        )
+        if vis == Visibility.hidden:
             continue
-        await _attach_primary_name(session, person)
+        if vis == Visibility.redacted:
+            _redact(person)
+        else:
+            await _attach_primary_name(session, person)
         visible.append(person)
     return visible
+
+
+async def search_persons(
+    session: AsyncSession, *, viewer_id: uuid.UUID, tree: Tree, query: str, limit: int = 50
+) -> list[Person]:
+    if not await privacy.can_view_tree(session, user_id=viewer_id, tree=tree):
+        raise Forbidden("not permitted to view this tree")
+    q = query.strip()
+    if not q:
+        return []
+    like = f"%{q}%"
+    score = func.greatest(
+        func.similarity(func.coalesce(Name.given, ""), q),
+        func.similarity(func.coalesce(Name.surname, ""), q),
+    )
+    sub = (
+        select(Name.person_id.label("pid"), func.max(score).label("score"))
+        .where(
+            Name.tree_id == tree.id,
+            Name.deleted_at.is_(None),
+            or_(
+                Name.given.op("%")(q),
+                Name.surname.op("%")(q),
+                Name.given.ilike(like),
+                Name.surname.ilike(like),
+            ),
+        )
+        .group_by(Name.person_id)
+        .order_by(func.max(score).desc())
+        .limit(limit)
+        .subquery()
+    )
+    stmt = (
+        select(Person)
+        .join(sub, sub.c.pid == Person.id)
+        .where(Person.tree_id == tree.id, Person.deleted_at.is_(None))
+        .order_by(sub.c.score.desc())
+    )
+    persons = list((await session.execute(stmt)).scalars().all())
+    out: list[Person] = []
+    for person in persons:
+        vis = await privacy.person_visibility(
+            session, user_id=viewer_id, tree=tree, person=person
+        )
+        if vis == Visibility.hidden:
+            continue
+        if vis == Visibility.redacted:
+            _redact(person)
+        else:
+            await _attach_primary_name(session, person)
+        out.append(person)
+    return out

backend/app/services/privacy.py

@@ -8,14 +8,20 @@ tree's visibility, the per-person override, and (Phase 2) living-person status.
 
 import enum
 import uuid
+from datetime import UTC, datetime
 
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.models.enums import MembershipRole, PersonPrivacy, TreeVisibility
+from app.models.event import Event
 from app.models.person import Person
 from app.models.tree import Tree, TreeMembership
 
+# A person with no death fact whose birth is within this window (or unknown) is
+# treated as possibly living and redacted from non-members (ARCHITECTURE §6).
+LIVING_RECENCY_YEARS = 100
+
 
 class Visibility(enum.StrEnum):
     full = "full"
@@ -39,8 +45,17 @@ async def can_view_tree(session: AsyncSession, *, user_id: uuid.UUID | None, tre
     if tree.deleted_at is not None:
         return False
     if await get_membership_role(session, user_id, tree.id) is not None:
+        return True  # members always (any role)
+    # Non-members. Branch on the viewer's auth state:
+    #   public / unlisted  → anyone, including anonymous (unlisted is gated only
+    #                        by knowing the link, so the API must never *list* it).
+    #   site_members       → any authenticated account on this instance.
+    #   private            → no one.
+    if tree.visibility in (TreeVisibility.public, TreeVisibility.unlisted):
         return True
-    return tree.visibility in (TreeVisibility.public, TreeVisibility.unlisted)
+    if tree.visibility == TreeVisibility.site_members:
+        return user_id is not None
+    return False
 
 
 async def can_edit_tree(session: AsyncSession, *, user_id: uuid.UUID | None, tree: Tree) -> bool:
@@ -48,15 +63,56 @@ async def can_edit_tree(session: AsyncSession, *, user_id: uuid.UUID | None, tre
     return role in (MembershipRole.owner, MembershipRole.editor)
 
 
+async def is_possibly_living(session: AsyncSession, person: Person) -> bool:
+    """True if the person should be treated as living: explicit flag, or (absent
+    a death fact) a birth within the recency window or an unknown birth."""
+    if person.is_living is True:
+        return True
+    if person.is_living is False:
+        return False
+    death = (
+        await session.execute(
+            select(Event.id)
+            .where(
+                Event.person_id == person.id,
+                Event.event_type == "death",
+                Event.deleted_at.is_(None),
+            )
+            .limit(1)
+        )
+    ).scalar_one_or_none()
+    if death is not None:
+        return False
+    birth = (
+        await session.execute(
+            select(Event.date_start)
+            .where(
+                Event.person_id == person.id,
+                Event.event_type == "birth",
+                Event.date_start.is_not(None),
+                Event.deleted_at.is_(None),
+            )
+            .order_by(Event.date_start)
+            .limit(1)
+        )
+    ).scalar_one_or_none()
+    if birth is None:
+        return True  # unknown birth → treat as possibly living
+    return (datetime.now(UTC).year - birth.year) < LIVING_RECENCY_YEARS
+
+
 async def person_visibility(
     session: AsyncSession, *, user_id: uuid.UUID | None, tree: Tree, person: Person
 ) -> Visibility:
     if not await can_view_tree(session, user_id=user_id, tree=tree):
         return Visibility.hidden
     if await get_membership_role(session, user_id, tree.id) is not None:
-        return Visibility.full
+        return Visibility.full  # members see everyone in their tree
     # Non-member viewing a public/unlisted tree:
     if person.privacy == PersonPrivacy.private:
         return Visibility.hidden
-    # TODO(Phase 2): redact living people for non-members (ARCHITECTURE §6).
+    if person.privacy == PersonPrivacy.public:
+        return Visibility.full  # explicit per-person opt-in
+    if await is_possibly_living(session, person):
+        return Visibility.redacted  # living people are protected by default
     return Visibility.full

backend/app/services/public_view_service.py

@@ -0,0 +1,318 @@
+"""Read-only, redaction-safe projections for the public viewing surface.
+
+INVARIANT (CLAUDE.md #2): everything returned here has passed through
+``privacy.person_visibility``. A non-member must never receive a possibly-living
+person's real name, dates, alternate names, or media. The rules:
+
+  - persons        : redacted (living → "Living person"); hidden dropped.
+  - relationships  : only when BOTH endpoints are non-hidden (a link to a
+                     redacted person is fine — the name is already hidden).
+  - events         : only for FULL-visibility persons; partnership events only
+                     when BOTH partners are full (a marriage date would leak a
+                     living partner's timeline otherwise).
+  - names          : only for FULL-visibility persons.
+  - media          : NOT exposed yet (deferred — see docs/design/tree-visibility.md).
+
+A tree that isn't viewable raises NotFound (never Forbidden) so the public
+surface can't be used to probe whether a private tree exists.
+"""
+
+import uuid
+
+from sqlalchemy import or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.enums import TreeVisibility
+from app.models.event import Event
+from app.models.media import Media
+from app.models.person import Name, Person
+from app.models.relationship import Relationship
+from app.models.tree import Tree
+from app.services import privacy
+from app.services.exceptions import NotFound
+from app.services.person_service import _attach_primary_name, _redact
+from app.services.privacy import Visibility
+
+
+async def get_public_tree(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree_id: uuid.UUID
+) -> Tree:
+    tree = (
+        await session.execute(
+            select(Tree).where(Tree.id == tree_id, Tree.deleted_at.is_(None))
+        )
+    ).scalar_one_or_none()
+    # 404 (not 403) when not viewable: don't reveal that a private tree exists.
+    if tree is None or not await privacy.can_view_tree(session, user_id=viewer_id, tree=tree):
+        raise NotFound("tree not found")
+    return tree
+
+
+async def _persons(session: AsyncSession, tree: Tree) -> list[Person]:
+    return list(
+        (
+            await session.execute(
+                select(Person).where(Person.tree_id == tree.id, Person.deleted_at.is_(None))
+            )
+        )
+        .scalars()
+        .all()
+    )
+
+
+async def _visibility_map(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree, persons: list[Person]
+) -> dict[uuid.UUID, Visibility]:
+    return {
+        p.id: await privacy.person_visibility(
+            session, user_id=viewer_id, tree=tree, person=p
+        )
+        for p in persons
+    }
+
+
+async def list_public_persons(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree
+) -> list[Person]:
+    out: list[Person] = []
+    for p in await _persons(session, tree):
+        vis = await privacy.person_visibility(session, user_id=viewer_id, tree=tree, person=p)
+        if vis == Visibility.hidden:
+            continue
+        if vis == Visibility.redacted:
+            _redact(p)
+        else:
+            await _attach_primary_name(session, p)
+        out.append(p)
+    return out
+
+
+async def get_public_person(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree, person_id: uuid.UUID
+) -> Person:
+    person = (
+        await session.execute(
+            select(Person).where(
+                Person.id == person_id,
+                Person.tree_id == tree.id,
+                Person.deleted_at.is_(None),
+            )
+        )
+    ).scalar_one_or_none()
+    if person is None:
+        raise NotFound("person not found")
+    vis = await privacy.person_visibility(session, user_id=viewer_id, tree=tree, person=person)
+    if vis == Visibility.hidden:
+        raise NotFound("person not found")
+    if vis == Visibility.redacted:
+        _redact(person)
+    else:
+        await _attach_primary_name(session, person)
+    return person
+
+
+async def _person_visibility(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree, person_id: uuid.UUID
+) -> Visibility | None:
+    person = (
+        await session.execute(
+            select(Person).where(
+                Person.id == person_id,
+                Person.tree_id == tree.id,
+                Person.deleted_at.is_(None),
+            )
+        )
+    ).scalar_one_or_none()
+    if person is None:
+        return None
+    return await privacy.person_visibility(session, user_id=viewer_id, tree=tree, person=person)
+
+
+async def list_public_relationships(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree
+) -> list[Relationship]:
+    persons = await _persons(session, tree)
+    vis = await _visibility_map(session, viewer_id=viewer_id, tree=tree, persons=persons)
+    nonhidden = {pid for pid, v in vis.items() if v != Visibility.hidden}
+    rels = list(
+        (
+            await session.execute(
+                select(Relationship).where(
+                    Relationship.tree_id == tree.id, Relationship.deleted_at.is_(None)
+                )
+            )
+        )
+        .scalars()
+        .all()
+    )
+    return [
+        r for r in rels if r.person_from_id in nonhidden and r.person_to_id in nonhidden
+    ]
+
+
+async def list_public_events(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree
+) -> list[Event]:
+    persons = await _persons(session, tree)
+    vis = await _visibility_map(session, viewer_id=viewer_id, tree=tree, persons=persons)
+    full = {pid for pid, v in vis.items() if v == Visibility.full}
+    rels = {
+        r.id: r
+        for r in (
+            await session.execute(
+                select(Relationship).where(
+                    Relationship.tree_id == tree.id, Relationship.deleted_at.is_(None)
+                )
+            )
+        )
+        .scalars()
+        .all()
+    }
+    events = list(
+        (
+            await session.execute(
+                select(Event).where(Event.tree_id == tree.id, Event.deleted_at.is_(None))
+            )
+        )
+        .scalars()
+        .all()
+    )
+    out: list[Event] = []
+    for e in events:
+        if e.person_id is not None:
+            if e.person_id in full:
+                out.append(e)
+        elif e.relationship_id is not None:
+            r = rels.get(e.relationship_id)
+            if r is not None and r.person_from_id in full and r.person_to_id in full:
+                out.append(e)
+    return out
+
+
+async def list_public_person_names(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree, person_id: uuid.UUID
+) -> list[Name]:
+    vis = await _person_visibility(session, viewer_id=viewer_id, tree=tree, person_id=person_id)
+    if vis is None:
+        raise NotFound("person not found")
+    if vis != Visibility.full:
+        return []  # redacted/hidden → no names (the real name must not leak)
+    return list(
+        (
+            await session.execute(
+                select(Name)
+                .where(Name.person_id == person_id, Name.deleted_at.is_(None))
+                .order_by(Name.is_primary.desc(), Name.sort_order, Name.created_at)
+            )
+        )
+        .scalars()
+        .all()
+    )
+
+
+async def list_public_person_events(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree, person_id: uuid.UUID
+) -> list[Event]:
+    vis = await _person_visibility(session, viewer_id=viewer_id, tree=tree, person_id=person_id)
+    if vis is None:
+        raise NotFound("person not found")
+    if vis != Visibility.full:
+        return []  # redacted/hidden → no dates
+    return list(
+        (
+            await session.execute(
+                select(Event)
+                .where(
+                    Event.person_id == person_id,
+                    Event.tree_id == tree.id,
+                    Event.deleted_at.is_(None),
+                )
+                .order_by(Event.date_start.nulls_last(), Event.created_at)
+            )
+        )
+        .scalars()
+        .all()
+    )
+
+
+async def list_public_relationships_for_person(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree, person_id: uuid.UUID
+) -> list[Relationship]:
+    persons = await _persons(session, tree)
+    vis = await _visibility_map(session, viewer_id=viewer_id, tree=tree, persons=persons)
+    if vis.get(person_id) in (None, Visibility.hidden):
+        return []
+    nonhidden = {pid for pid, v in vis.items() if v != Visibility.hidden}
+    rels = list(
+        (
+            await session.execute(
+                select(Relationship).where(
+                    Relationship.tree_id == tree.id,
+                    Relationship.deleted_at.is_(None),
+                    or_(
+                        Relationship.person_from_id == person_id,
+                        Relationship.person_to_id == person_id,
+                    ),
+                )
+            )
+        )
+        .scalars()
+        .all()
+    )
+    return [r for r in rels if r.person_from_id in nonhidden and r.person_to_id in nonhidden]
+
+
+async def list_public_media(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree
+) -> list[Media]:
+    """Only media linked to a FULL-visibility person. Media without a person (or
+    linked only to an event/source) is not exposed to non-members — a photo of a
+    living person must never leak."""
+    persons = await _persons(session, tree)
+    vis = await _visibility_map(session, viewer_id=viewer_id, tree=tree, persons=persons)
+    full = {pid for pid, v in vis.items() if v == Visibility.full}
+    media = list(
+        (
+            await session.execute(
+                select(Media).where(Media.tree_id == tree.id, Media.deleted_at.is_(None))
+            )
+        )
+        .scalars()
+        .all()
+    )
+    return [m for m in media if m.person_id is not None and m.person_id in full]
+
+
+async def can_view_media(
+    session: AsyncSession, *, viewer_id: uuid.UUID | None, tree: Tree, media: Media
+) -> bool:
+    """Whether a non-member may see/download a single media item: only when it is
+    linked to a FULL-visibility person."""
+    if media.person_id is None:
+        return False
+    vis = await _person_visibility(
+        session, viewer_id=viewer_id, tree=tree, person_id=media.person_id
+    )
+    return vis == Visibility.full
+
+
+async def list_public_trees(
+    session: AsyncSession,
+    *,
+    viewer_id: uuid.UUID | None,
+    q: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+) -> list[Tree]:
+    # Anonymous: only `public`. Authenticated: also `site_members`. Never list
+    # `unlisted` (reachable by link only) or `private`.
+    allowed = [TreeVisibility.public]
+    if viewer_id is not None:
+        allowed.append(TreeVisibility.site_members)
+    stmt = select(Tree).where(
+        Tree.deleted_at.is_(None), Tree.visibility.in_(allowed)
+    )
+    if q and q.strip():
+        stmt = stmt.where(Tree.name.ilike(f"%{q.strip()}%"))
+    stmt = stmt.order_by(Tree.name).limit(min(limit, 100)).offset(max(offset, 0))
+    return list((await session.execute(stmt)).scalars().all())

backend/app/services/relationship_service.py

@@ -4,7 +4,7 @@ Writes require editor rights; reads go through the privacy engine."""
 import uuid
 from datetime import UTC, datetime
 
-from sqlalchemy import or_, select
+from sqlalchemy import and_, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.models.enums import ParentChildQualifier, RelationshipType
@@ -49,6 +49,38 @@ async def create_relationship(
         if not await _person_in_tree(session, pid, tree.id):
             raise NotFound("person not found in this tree")
 
+    # Reject an equivalent existing edge so the same two people can't be linked
+    # the same way twice. parent_child is directional (parent -> child);
+    # partnership/sibling are symmetric, so match the pair in either order.
+    if type is RelationshipType.parent_child:
+        pair = and_(
+            Relationship.person_from_id == person_from_id,
+            Relationship.person_to_id == person_to_id,
+        )
+    else:
+        pair = or_(
+            and_(
+                Relationship.person_from_id == person_from_id,
+                Relationship.person_to_id == person_to_id,
+            ),
+            and_(
+                Relationship.person_from_id == person_to_id,
+                Relationship.person_to_id == person_from_id,
+            ),
+        )
+    existing = (
+        await session.execute(
+            select(Relationship.id).where(
+                Relationship.tree_id == tree.id,
+                Relationship.type == type,
+                Relationship.deleted_at.is_(None),
+                pair,
+            )
+        )
+    ).scalar_one_or_none()
+    if existing is not None:
+        raise Conflict("these two people are already linked that way")
+
     relationship = Relationship(
         tree_id=tree.id,
         type=type,
@@ -79,6 +111,13 @@ async def list_relationships(
     """All relationships in the tree — powers the family/pedigree view in one call."""
     if not await privacy.can_view_tree(session, user_id=viewer_id, tree=tree):
         raise Forbidden("not permitted to view this tree")
+    # Non-members: drop relationships touching a hidden person.
+    if await privacy.get_membership_role(session, viewer_id, tree.id) is None:
+        from app.services import public_view_service
+
+        return await public_view_service.list_public_relationships(
+            session, viewer_id=viewer_id, tree=tree
+        )
     stmt = (
         select(Relationship)
         .where(Relationship.tree_id == tree.id, Relationship.deleted_at.is_(None))
@@ -92,6 +131,12 @@ async def list_relationships_for_person(
 ) -> list[Relationship]:
     if not await privacy.can_view_tree(session, user_id=viewer_id, tree=tree):
         raise Forbidden("not permitted to view this tree")
+    if await privacy.get_membership_role(session, viewer_id, tree.id) is None:
+        from app.services import public_view_service
+
+        return await public_view_service.list_public_relationships_for_person(
+            session, viewer_id=viewer_id, tree=tree, person_id=person_id
+        )
     stmt = (
         select(Relationship)
         .where(
@@ -107,6 +152,44 @@ async def list_relationships_for_person(
     return list((await session.execute(stmt)).scalars().all())
 
 
+async def update_relationship(
+    session: AsyncSession, *, actor: User, tree: Tree, relationship_id: uuid.UUID, changes: dict
+) -> Relationship:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    relationship = (
+        await session.execute(
+            select(Relationship).where(
+                Relationship.id == relationship_id,
+                Relationship.tree_id == tree.id,
+                Relationship.deleted_at.is_(None),
+            )
+        )
+    ).scalar_one_or_none()
+    if relationship is None:
+        raise NotFound("relationship not found")
+    if (
+        "qualifier" in changes
+        and changes["qualifier"] is not None
+        and relationship.type is not RelationshipType.parent_child
+    ):
+        raise Conflict("qualifier only applies to parent_child relationships")
+    for key in {"qualifier", "notes"} & changes.keys():
+        setattr(relationship, key, changes[key])
+    record_audit(
+        session,
+        action="update",
+        entity_type="Relationship",
+        entity_id=relationship.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after=changes,
+    )
+    await session.commit()
+    await session.refresh(relationship)
+    return relationship
+
+
 async def delete_relationship(
     session: AsyncSession, *, actor: User, tree: Tree, relationship_id: uuid.UUID
 ) -> None:

backend/app/services/source_service.py

@@ -86,6 +86,42 @@ async def get_source(
     return source
 
 
+_SOURCE_FIELDS = {
+    "title", "author", "source_type", "repository", "url", "citation_text",
+    "publication_info", "quality_note",
+}
+
+
+async def update_source(
+    session: AsyncSession, *, actor: User, tree: Tree, source_id: uuid.UUID, changes: dict
+) -> Source:
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    source = (
+        await session.execute(
+            select(Source).where(
+                Source.id == source_id, Source.tree_id == tree.id, Source.deleted_at.is_(None)
+            )
+        )
+    ).scalar_one_or_none()
+    if source is None:
+        raise NotFound("source not found")
+    for key in _SOURCE_FIELDS & changes.keys():
+        setattr(source, key, changes[key])
+    record_audit(
+        session,
+        action="update",
+        entity_type="Source",
+        entity_id=source.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after=changes,
+    )
+    await session.commit()
+    await session.refresh(source)
+    return source
+
+
 async def delete_source(
     session: AsyncSession, *, actor: User, tree: Tree, source_id: uuid.UUID
 ) -> None:

backend/app/services/tree_service.py

@@ -62,6 +62,30 @@ async def get_tree(session: AsyncSession, *, viewer_id: uuid.UUID, tree_id: uuid
     return tree
 
 
+async def update_tree(
+    session: AsyncSession, *, actor: User, tree_id: uuid.UUID, changes: dict
+) -> Tree:
+    tree = await BaseRepository(session, Tree).get(tree_id)
+    if tree is None:
+        raise NotFound("tree not found")
+    if not await privacy.can_edit_tree(session, user_id=actor.id, tree=tree):
+        raise Forbidden("not an editor of this tree")
+    for key in {"name", "description", "visibility", "home_person_id"} & changes.keys():
+        setattr(tree, key, changes[key])
+    record_audit(
+        session,
+        action="update",
+        entity_type="Tree",
+        entity_id=tree.id,
+        tree_id=tree.id,
+        actor_user_id=actor.id,
+        after=changes,
+    )
+    await session.commit()
+    await session.refresh(tree)
+    return tree
+
+
 async def _owned_tree(session: AsyncSession, *, actor: User, tree_id: uuid.UUID) -> Tree:
     """Load a tree (including soft-deleted) and require the actor be its owner."""
     tree = await BaseRepository(session, Tree).get(tree_id, include_deleted=True)

backend/app/services/user_service.py

@@ -8,10 +8,13 @@ import uuid
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.models.person import Person
+from app.models.tree import Tree
 from app.models.user import User
 from app.repositories.base import BaseRepository
+from app.services import privacy
 from app.services.audit import record_audit
-from app.services.exceptions import Conflict
+from app.services.exceptions import Conflict, Forbidden, NotFound
 
 
 async def create_user(
@@ -42,3 +45,39 @@ async def create_user(
 
 async def get_user(session: AsyncSession, user_id: uuid.UUID) -> User | None:
     return await BaseRepository(session, User).get(user_id)
+
+
+async def set_self_person(
+    session: AsyncSession, *, user: User, person_id: uuid.UUID | None
+) -> User:
+    """Point a user's account at the Person record that *is* them ("home
+    person"), or clear it with ``None``. The person must live in a tree the
+    user can view."""
+    if person_id is not None:
+        person = (
+            await session.execute(
+                select(Person).where(Person.id == person_id, Person.deleted_at.is_(None))
+            )
+        ).scalar_one_or_none()
+        if person is None:
+            raise NotFound("person not found")
+        tree = (
+            await session.execute(select(Tree).where(Tree.id == person.tree_id))
+        ).scalar_one_or_none()
+        if tree is None or not await privacy.can_view_tree(
+            session, user_id=user.id, tree=tree
+        ):
+            raise Forbidden("not permitted to link this person")
+
+    user.self_person_id = person_id
+    record_audit(
+        session,
+        action="update",
+        entity_type="User",
+        entity_id=user.id,
+        actor_user_id=user.id,
+        after={"self_person_id": str(person_id) if person_id else None},
+    )
+    await session.commit()
+    await session.refresh(user)
+    return user

backend/docker-entrypoint.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+# Container entrypoint. When RUN_MIGRATIONS=1 (set on the backend service),
+# apply DB migrations before handing off to the command. This makes a deploy
+# self-migrating even when images are swapped in place (e.g. by Watchtower),
+# without a separate orchestration step. `alembic upgrade head` is idempotent —
+# a no-op when the schema is already current.
+set -e
+
+if [ "${RUN_MIGRATIONS:-0}" = "1" ]; then
+  echo "[entrypoint] applying database migrations (alembic upgrade head)…"
+  uv run --no-dev alembic upgrade head
+fi
+
+exec "$@"

backend/migrations/versions/9a2b1c7d4e10_pg_trgm_name_search.py

@@ -0,0 +1,33 @@
+"""pg_trgm extension + trigram name indexes for fuzzy search
+
+Revision ID: 9a2b1c7d4e10
+Revises: 7fc7024ef432
+Create Date: 2026-06-07
+
+"""
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "9a2b1c7d4e10"
+down_revision: str | None = "7fc7024ef432"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("CREATE EXTENSION IF NOT EXISTS pg_trgm")
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_names_given_trgm "
+        "ON names USING gin (given gin_trgm_ops)"
+    )
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_names_surname_trgm "
+        "ON names USING gin (surname gin_trgm_ops)"
+    )
+
+
+def downgrade() -> None:
+    op.execute("DROP INDEX IF EXISTS ix_names_surname_trgm")
+    op.execute("DROP INDEX IF EXISTS ix_names_given_trgm")
+    # Leave the pg_trgm extension in place; other features may rely on it.

backend/migrations/versions/a1b2c3d4e5f6_change_proposals.py

@@ -0,0 +1,62 @@
+"""change_proposals (AI propose-then-confirm)
+
+Revision ID: a1b2c3d4e5f6
+Revises: d4a9c1e7b2f3
+Create Date: 2026-06-09
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "a1b2c3d4e5f6"
+down_revision: str | None = "d4a9c1e7b2f3"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "change_proposals",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("tree_id", sa.Uuid(), nullable=False),
+        sa.Column(
+            "status",
+            sa.Enum("pending", "applied", "rejected", name="change_proposal_status"),
+            server_default="pending",
+            nullable=False,
+        ),
+        sa.Column(
+            "origin",
+            sa.Enum("assistant", "contributor", name="change_proposal_origin"),
+            server_default="assistant",
+            nullable=False,
+        ),
+        sa.Column("created_by_user_id", sa.Uuid(), nullable=True),
+        sa.Column("summary", sa.String(length=512), nullable=False),
+        sa.Column("rationale", sa.Text(), nullable=True),
+        sa.Column("operations", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+        sa.Column("reviewed_by_user_id", sa.Uuid(), nullable=True),
+        sa.Column("reviewed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("review_note", sa.String(length=512), nullable=True),
+        sa.Column("apply_error", sa.Text(), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+        sa.ForeignKeyConstraint(["tree_id"], ["trees.id"], ondelete="CASCADE"),
+        sa.ForeignKeyConstraint(["created_by_user_id"], ["users.id"], ondelete="SET NULL"),
+        sa.ForeignKeyConstraint(["reviewed_by_user_id"], ["users.id"], ondelete="SET NULL"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("ix_change_proposals_tree_id", "change_proposals", ["tree_id"])
+    op.create_index("ix_change_proposals_status", "change_proposals", ["status"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_change_proposals_status", table_name="change_proposals")
+    op.drop_index("ix_change_proposals_tree_id", table_name="change_proposals")
+    op.drop_table("change_proposals")
+    sa.Enum(name="change_proposal_status").drop(op.get_bind())
+    sa.Enum(name="change_proposal_origin").drop(op.get_bind())

backend/migrations/versions/b3d5f8a1c920_user_self_person.py

@@ -0,0 +1,36 @@
+"""user.self_person_id ("home person" link)
+
+Revision ID: b3d5f8a1c920
+Revises: 9a2b1c7d4e10
+Create Date: 2026-06-07
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "b3d5f8a1c920"
+down_revision: str | None = "9a2b1c7d4e10"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "users",
+        sa.Column("self_person_id", sa.Uuid(), nullable=True),
+    )
+    op.create_foreign_key(
+        "fk_users_self_person_id",
+        "users",
+        "persons",
+        ["self_person_id"],
+        ["id"],
+        ondelete="SET NULL",
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint("fk_users_self_person_id", "users", type_="foreignkey")
+    op.drop_column("users", "self_person_id")

backend/migrations/versions/c7e1a4f2d3b8_tree_home_person.py

@@ -0,0 +1,33 @@
+"""tree.home_person_id (per-tree default/home person)
+
+Revision ID: c7e1a4f2d3b8
+Revises: b3d5f8a1c920
+Create Date: 2026-06-07
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "c7e1a4f2d3b8"
+down_revision: str | None = "b3d5f8a1c920"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column("trees", sa.Column("home_person_id", sa.Uuid(), nullable=True))
+    op.create_foreign_key(
+        "fk_trees_home_person_id",
+        "trees",
+        "persons",
+        ["home_person_id"],
+        ["id"],
+        ondelete="SET NULL",
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint("fk_trees_home_person_id", "trees", type_="foreignkey")
+    op.drop_column("trees", "home_person_id")

backend/migrations/versions/d4a9c1e7b2f3_tree_visibility_site_members.py

@@ -0,0 +1,28 @@
+"""tree_visibility: add 'site_members' value
+
+Revision ID: d4a9c1e7b2f3
+Revises: c7e1a4f2d3b8
+Create Date: 2026-06-09
+
+"""
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "d4a9c1e7b2f3"
+down_revision: str | None = "c7e1a4f2d3b8"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ALTER TYPE ... ADD VALUE cannot run inside a transaction block on older
+    # Postgres; run it in an autocommit block so it applies regardless of version.
+    with op.get_context().autocommit_block():
+        op.execute("ALTER TYPE tree_visibility ADD VALUE IF NOT EXISTS 'site_members'")
+
+
+def downgrade() -> None:
+    # Postgres cannot drop an enum value without rebuilding the type; treat the
+    # added value as irreversible. (Rows using it would block a rebuild anyway.)
+    pass

backend/pyproject.toml

@@ -14,6 +14,8 @@ dependencies = [
     "argon2-cffi>=23.1",
     "boto3>=1.35",
     "python-multipart>=0.0.12",
+    "anthropic>=0.108.0",
+    "openai>=2.41.0",
 ]
 
 [dependency-groups]

backend/tests/conftest.py

@@ -11,6 +11,7 @@ import os
 import pytest
 import pytest_asyncio
 from httpx import ASGITransport, AsyncClient
+from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 
 import app.models  # noqa: F401 — register all models on Base.metadata
@@ -66,15 +67,21 @@ def mailer() -> CapturingMailer:
 
 
 @pytest_asyncio.fixture
-async def client():
+async def engine():
     if not TEST_DATABASE_URL:
         pytest.skip("TEST_DATABASE_URL not set")
 
-    engine = create_async_engine(TEST_DATABASE_URL)
-    async with engine.begin() as conn:
+    eng = create_async_engine(TEST_DATABASE_URL)
+    async with eng.begin() as conn:
+        await conn.execute(text("CREATE EXTENSION IF NOT EXISTS pg_trgm"))
         await conn.run_sync(Base.metadata.drop_all)
         await conn.run_sync(Base.metadata.create_all)
+    yield eng
+    await eng.dispose()
 
+
+@pytest_asyncio.fixture
+async def client(engine):
     sessionmaker = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
 
     async def _override_session():
@@ -93,7 +100,14 @@ async def client():
         yield http_client
 
     app.dependency_overrides.clear()
-    await engine.dispose()
+
+
+@pytest_asyncio.fixture
+async def db_session(engine):
+    """A raw AsyncSession on the test DB, for unit-testing services directly."""
+    sessionmaker = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
+    async with sessionmaker() as session:
+        yield session
 
 
 def token_from_link(link: str) -> str:

backend/tests/test_account_portability.py

@@ -0,0 +1,86 @@
+"""Account export -> restore round-trip, and account deletion."""
+
+from tests.conftest import auth, register
+
+
+async def _seed(client, h):
+    tid = (await client.post("/api/v1/trees", json={"name": "Fam"}, headers=h)).json()["id"]
+    p1 = (
+        await client.post(
+            f"/api/v1/trees/{tid}/persons", json={"given": "Ada", "surname": "Lovelace"}, headers=h
+        )
+    ).json()["id"]
+    p2 = (
+        await client.post(f"/api/v1/trees/{tid}/persons", json={"given": "Kid"}, headers=h)
+    ).json()["id"]
+    await client.post(
+        f"/api/v1/trees/{tid}/relationships",
+        json={"type": "parent_child", "person_from_id": p1, "person_to_id": p2},
+        headers=h,
+    )
+    await client.post(
+        f"/api/v1/trees/{tid}/events",
+        json={"event_type": "birth", "person_id": p1, "date_value": "1815"},
+        headers=h,
+    )
+    await client.post(
+        f"/api/v1/trees/{tid}/media",
+        files={"file": ("scan.txt", b"hello", "text/plain")},
+        data={"title": "Scan", "person_id": p1},
+        headers=h,
+    )
+    return tid
+
+
+async def test_export_then_restore_roundtrip(client):
+    h = auth(await register(client, "exp@example.com"))
+    await _seed(client, h)
+
+    export = await client.get("/api/v1/users/me/export", headers=h)
+    assert export.status_code == 200
+    assert export.headers["content-type"] == "application/zip"
+    blob = export.content
+    assert blob[:2] == b"PK"  # zip magic
+
+    # Restore into new trees (non-destructive: the original stays).
+    r = await client.post(
+        "/api/v1/users/me/import",
+        files={"file": ("provenance-export.zip", blob, "application/zip")},
+        headers=h,
+    )
+    assert r.status_code == 200, r.text
+    counts = r.json()
+    assert counts["trees"] == 1 and counts["persons"] == 2
+    assert counts["events"] == 1 and counts["media"] == 1
+
+    trees = (await client.get("/api/v1/trees", headers=h)).json()
+    assert len(trees) == 2  # original + restored
+
+    # The restored tree has the people, with a working relationship and media.
+    restored = [t for t in trees if t["name"] == "Fam"][1]["id"]
+    ppl = (await client.get(f"/api/v1/trees/{restored}/persons", headers=h)).json()
+    assert {p["primary_name"] for p in ppl} == {"Ada Lovelace", "Kid"}
+    rels = (await client.get(f"/api/v1/trees/{restored}/relationships", headers=h)).json()
+    assert len(rels) == 1
+    med = (await client.get(f"/api/v1/trees/{restored}/media", headers=h)).json()
+    assert len(med) == 1 and med[0]["title"] == "Scan"
+
+
+async def test_delete_account_requires_email_then_revokes(client):
+    token = await register(client, "del@example.com")
+    h = auth(token)
+    await _seed(client, h)
+
+    # Wrong email is rejected.
+    bad = await client.request(
+        "DELETE", "/api/v1/users/me", data={"confirm_email": "nope@example.com"}, headers=h
+    )
+    assert bad.status_code == 403
+
+    ok = await client.request(
+        "DELETE", "/api/v1/users/me", data={"confirm_email": "del@example.com"}, headers=h
+    )
+    assert ok.status_code == 204
+
+    # Session is revoked — the token no longer works.
+    assert (await client.get("/api/v1/users/me", headers=h)).status_code == 401

backend/tests/test_account_settings.py

@@ -0,0 +1,53 @@
+"""Change password and per-tree home person."""
+
+from tests.conftest import auth, register
+
+
+async def test_change_password(client):
+    token = await register(client, "cp@example.com", password="password123")
+    h = auth(token)
+
+    # Wrong current password is rejected.
+    bad = await client.post(
+        "/api/v1/auth/change-password",
+        json={"current_password": "nope", "new_password": "newpass123"},
+        headers=h,
+    )
+    assert bad.status_code == 403
+
+    ok = await client.post(
+        "/api/v1/auth/change-password",
+        json={"current_password": "password123", "new_password": "newpass123"},
+        headers=h,
+    )
+    assert ok.status_code == 204
+
+    # The new password logs in; the old one does not.
+    assert (
+        await client.post(
+            "/api/v1/auth/login", json={"email": "cp@example.com", "password": "newpass123"}
+        )
+    ).status_code == 200
+    assert (
+        await client.post(
+            "/api/v1/auth/login", json={"email": "cp@example.com", "password": "password123"}
+        )
+    ).status_code == 401
+
+
+async def test_tree_home_person(client):
+    h = auth(await register(client, "home@example.com"))
+    tid = (await client.post("/api/v1/trees", json={"name": "T"}, headers=h)).json()["id"]
+    pid = (
+        await client.post(f"/api/v1/trees/{tid}/persons", json={"given": "Root"}, headers=h)
+    ).json()["id"]
+
+    r = await client.patch(
+        f"/api/v1/trees/{tid}", json={"home_person_id": pid}, headers=h
+    )
+    assert r.status_code == 200 and r.json()["home_person_id"] == pid
+
+    # Deleting the home person clears the link.
+    await client.delete(f"/api/v1/trees/{tid}/persons/{pid}", headers=h)
+    tree = (await client.get(f"/api/v1/trees/{tid}", headers=h)).json()
+    assert tree["home_person_id"] is None

backend/tests/test_auth.py

@@ -104,3 +104,44 @@ async def test_logout_revokes_session(client):
     assert (await client.get("/api/v1/users/me", headers=auth(token))).status_code == 200
     assert (await client.post("/api/v1/auth/logout", headers=auth(token))).status_code == 204
     assert (await client.get("/api/v1/users/me", headers=auth(token))).status_code == 401
+
+
+async def test_unverified_user_works_by_default(client):
+    # Default (require_email_verification off): unverified accounts work as before.
+    token = await register(client, "open@example.com")
+    assert (await client.get("/api/v1/users/me", headers=auth(token))).status_code == 200
+
+
+async def test_verification_gate_blocks_until_verified(client, mailer, monkeypatch):
+    from app.core.config import get_settings
+
+    monkeypatch.setattr(get_settings(), "require_email_verification", True)
+
+    reg = await client.post(
+        "/api/v1/auth/register", json={"email": "gate@example.com", "password": "password123"}
+    )
+    assert reg.status_code == 201
+    token = reg.json()["token"]
+
+    # The session issued at registration does not resolve while unverified...
+    assert (await client.get("/api/v1/users/me", headers=auth(token))).status_code == 401
+    # ...and login is refused with 403 (not 401 — credentials are valid).
+    blocked = await client.post(
+        "/api/v1/auth/login", json={"email": "gate@example.com", "password": "password123"}
+    )
+    assert blocked.status_code == 403
+
+    # Verify via the emailed link.
+    link = mailer.verifications[-1][1]
+    assert (
+        await client.post("/api/v1/auth/verify-email", json={"token": token_from_link(link)})
+    ).status_code == 204
+
+    # Now login works and the session resolves.
+    ok = await client.post(
+        "/api/v1/auth/login", json={"email": "gate@example.com", "password": "password123"}
+    )
+    assert ok.status_code == 200
+    assert (
+        await client.get("/api/v1/users/me", headers=auth(ok.json()["token"]))
+    ).status_code == 200

backend/tests/test_authed_nonmember_redaction.py

@@ -0,0 +1,121 @@
+"""Authed non-member reads must redact PER-PERSON, not just gate on the tree.
+
+A logged-in user who is NOT a member of a public tree previously saw living
+people's dates, real alternate names, and media through the family-view
+endpoints — only the person *list* was redacted. These tests assert that leak is
+closed while members still see everything.
+"""
+
+from tests.conftest import auth, register
+
+LSURNAME = "Authleaksurname"
+LALIAS = "Authleakalias"
+LYEAR = "2003"
+
+
+async def _setup(client):
+    owner = auth(await register(client, "anm-owner@ex.com"))
+    tid = (
+        await client.post(
+            "/api/v1/trees", json={"name": "Pub", "visibility": "public"}, headers=owner
+        )
+    ).json()["id"]
+    old = (
+        await client.post(
+            f"/api/v1/trees/{tid}/persons",
+            json={"given": "Olde", "surname": "Gone", "is_living": False},
+            headers=owner,
+        )
+    ).json()["id"]
+    young = (
+        await client.post(
+            f"/api/v1/trees/{tid}/persons",
+            json={"given": "Youngauth", "surname": LSURNAME, "is_living": True},
+            headers=owner,
+        )
+    ).json()["id"]
+    for pid, year in ((old, "1855"), (young, LYEAR)):
+        await client.post(
+            f"/api/v1/trees/{tid}/events",
+            json={"event_type": "birth", "person_id": pid, "date_value": year},
+            headers=owner,
+        )
+    await client.post(
+        f"/api/v1/trees/{tid}/persons/{young}/names",
+        json={"name_type": "alias", "given": LALIAS},
+        headers=owner,
+    )
+    om = (
+        await client.post(
+            f"/api/v1/trees/{tid}/media",
+            files={"file": ("o.txt", b"old-photo", "text/plain")},
+            data={"person_id": old},
+            headers=owner,
+        )
+    ).json()["id"]
+    ym = (
+        await client.post(
+            f"/api/v1/trees/{tid}/media",
+            files={"file": ("y.txt", b"young-photo", "text/plain")},
+            data={"person_id": young},
+            headers=owner,
+        )
+    ).json()["id"]
+    return owner, tid, old, young, om, ym
+
+
+async def test_authed_nonmember_does_not_see_living_pii(client):
+    owner, tid, old, young, om, ym = await _setup(client)
+    stranger = auth(await register(client, "anm-stranger@ex.com"))
+
+    # Living person's events dropped; deceased kept.
+    events = (await client.get(f"/api/v1/trees/{tid}/events", headers=stranger)).json()
+    assert any(e["person_id"] == old for e in events)
+    assert not any(e["person_id"] == young for e in events)
+
+    # Per-person living: names + events empty.
+    assert (
+        await client.get(f"/api/v1/trees/{tid}/persons/{young}/names", headers=stranger)
+    ).json() == []
+    assert (
+        await client.get(f"/api/v1/trees/{tid}/persons/{young}/events", headers=stranger)
+    ).json() == []
+
+    # The living surname/alias/birth-year must not appear in any of these.
+    for path in (
+        f"/api/v1/trees/{tid}/events",
+        f"/api/v1/trees/{tid}/relationships",
+        f"/api/v1/trees/{tid}/persons/{young}/names",
+        f"/api/v1/trees/{tid}/media",
+    ):
+        body = (await client.get(path, headers=stranger)).text
+        assert LSURNAME not in body, path
+        assert LALIAS not in body, path
+        assert LYEAR not in body, path
+
+    # Media: living person's media hidden from the list and undownloadable;
+    # deceased person's media is fine.
+    media_ids = {m["id"] for m in (await client.get(f"/api/v1/trees/{tid}/media", headers=stranger)).json()}
+    assert om in media_ids
+    assert ym not in media_ids
+    assert (
+        await client.get(f"/api/v1/trees/{tid}/media/{ym}/content", headers=stranger)
+    ).status_code == 404
+    assert (
+        await client.get(f"/api/v1/trees/{tid}/media/{om}/content", headers=stranger)
+    ).status_code == 200
+
+
+async def test_member_still_sees_everything(client):
+    owner, tid, old, young, om, ym = await _setup(client)
+
+    events = (await client.get(f"/api/v1/trees/{tid}/events", headers=owner)).json()
+    assert any(e["person_id"] == young for e in events)
+    assert (
+        await client.get(f"/api/v1/trees/{tid}/persons/{young}/names", headers=owner)
+    ).json() != []
+    member_media = {m["id"] for m in (await client.get(f"/api/v1/trees/{tid}/media", headers=owner)).json()}
+    assert ym in member_media
+    assert (
+        await client.get(f"/api/v1/trees/{tid}/media/{ym}/content", headers=owner)
+    ).status_code == 200

backend/tests/test_change_proposal.py

@@ -0,0 +1,154 @@
+"""ChangeProposal: a proposal mutates nothing until an editor approves it, and
+application goes through the editing services (privacy + audit). See
+docs/design/change-proposal.md and CLAUDE.md non-negotiable #1.
+"""
+
+import uuid
+
+from tests.conftest import auth, register
+
+
+async def _tree(client, email):
+    h = auth(await register(client, email))
+    tid = (await client.post("/api/v1/trees", json={"name": "T"}, headers=h)).json()["id"]
+    return h, tid
+
+
+async def _propose(client, tid, headers, summary, operations, origin="assistant"):
+    r = await client.post(
+        f"/api/v1/trees/{tid}/proposals",
+        json={"summary": summary, "origin": origin, "operations": operations},
+        headers=headers,
+    )
+    assert r.status_code == 201, r.text
+    return r.json()
+
+
+async def test_proposal_not_applied_until_approved(client):
+    h, tid = await _tree(client, "cp-owner@ex.com")
+    cp = await _propose(
+        client,
+        tid,
+        h,
+        "Add Ada Lovelace",
+        [{"op": "create", "entity_type": "person", "payload": {"given": "Ada", "surname": "Lovelace"}}],
+    )
+    assert cp["status"] == "pending"
+
+    # The proposed person does NOT exist yet.
+    people = (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()
+    assert not any(p["primary_name"] == "Ada Lovelace" for p in people)
+
+    # Approve → applied → the person now exists.
+    a = await client.post(f"/api/v1/trees/{tid}/proposals/{cp['id']}/apply", headers=h)
+    assert a.status_code == 200 and a.json()["status"] == "applied"
+    people = (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()
+    assert any(p["primary_name"] == "Ada Lovelace" for p in people)
+
+
+async def test_reject_does_not_apply(client):
+    h, tid = await _tree(client, "cp-reject@ex.com")
+    cp = await _propose(
+        client,
+        tid,
+        h,
+        "Add Reject Me",
+        [{"op": "create", "entity_type": "person", "payload": {"given": "Reject", "surname": "Me"}}],
+    )
+    rr = await client.post(
+        f"/api/v1/trees/{tid}/proposals/{cp['id']}/reject", json={"note": "no"}, headers=h
+    )
+    assert rr.status_code == 200 and rr.json()["status"] == "rejected"
+    people = (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()
+    assert not any(p["primary_name"] == "Reject Me" for p in people)
+    # A rejected proposal can't then be applied.
+    assert (
+        await client.post(f"/api/v1/trees/{tid}/proposals/{cp['id']}/apply", headers=h)
+    ).status_code == 409
+
+
+async def test_non_editor_member_can_see_but_not_apply(client):
+    owner = auth(await register(client, "cp-o2@ex.com"))
+    viewer = auth(await register(client, "cp-v2@ex.com"))
+    tid = (
+        await client.post("/api/v1/trees", json={"name": "Shared"}, headers=owner)
+    ).json()["id"]
+    await client.post(
+        f"/api/v1/trees/{tid}/members", json={"email": "cp-v2@ex.com", "role": "viewer"}, headers=owner
+    )
+    cp = await _propose(
+        client,
+        tid,
+        owner,
+        "Add V P",
+        [{"op": "create", "entity_type": "person", "payload": {"given": "V", "surname": "P"}}],
+    )
+    # A viewer (member) can see the proposal list...
+    assert (await client.get(f"/api/v1/trees/{tid}/proposals", headers=viewer)).status_code == 200
+    # ...but cannot apply it (not an editor).
+    assert (
+        await client.post(f"/api/v1/trees/{tid}/proposals/{cp['id']}/apply", headers=viewer)
+    ).status_code == 403
+
+
+async def test_multi_op_applies_all(client):
+    h, tid = await _tree(client, "cp-multi@ex.com")
+    pid = (
+        await client.post(
+            f"/api/v1/trees/{tid}/persons", json={"given": "Multi", "surname": "Op"}, headers=h
+        )
+    ).json()["id"]
+    cp = await _propose(
+        client,
+        tid,
+        h,
+        "name + event on existing person",
+        [
+            {"op": "create", "entity_type": "name", "payload": {"person_id": pid, "name_type": "alias", "given": "Mo"}},
+            {"op": "create", "entity_type": "event", "payload": {"event_type": "birth", "person_id": pid, "date_value": "1900"}},
+        ],
+    )
+    assert (
+        await client.post(f"/api/v1/trees/{tid}/proposals/{cp['id']}/apply", headers=h)
+    ).status_code == 200
+    names = (await client.get(f"/api/v1/trees/{tid}/persons/{pid}/names", headers=h)).json()
+    assert any(n.get("given") == "Mo" for n in names)
+    events = (await client.get(f"/api/v1/trees/{tid}/persons/{pid}/events", headers=h)).json()
+    assert any(e["date_value"] == "1900" for e in events)
+
+
+async def test_apply_with_edited_operations(client):
+    h, tid = await _tree(client, "cp-edit@ex.com")
+    cp = await _propose(
+        client,
+        tid,
+        h,
+        "Add Original",
+        [{"op": "create", "entity_type": "person", "payload": {"given": "Original", "surname": "Name"}}],
+    )
+    edited = {
+        "operations": [
+            {"op": "create", "entity_type": "person", "payload": {"given": "Edited", "surname": "Name"}}
+        ]
+    }
+    assert (
+        await client.post(f"/api/v1/trees/{tid}/proposals/{cp['id']}/apply", json=edited, headers=h)
+    ).status_code == 200
+    names = {p["primary_name"] for p in (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()}
+    assert "Edited Name" in names and "Original Name" not in names
+
+
+async def test_apply_error_keeps_pending(client):
+    h, tid = await _tree(client, "cp-err@ex.com")
+    cp = await _propose(
+        client,
+        tid,
+        h,
+        "Bad update",
+        [{"op": "update", "entity_type": "person", "entity_id": str(uuid.uuid4()), "payload": {"given": "X"}}],
+    )
+    a = await client.post(f"/api/v1/trees/{tid}/proposals/{cp['id']}/apply", headers=h)
+    assert a.status_code == 409
+    g = (await client.get(f"/api/v1/trees/{tid}/proposals/{cp['id']}", headers=h)).json()
+    assert g["status"] == "pending"
+    assert g["apply_error"]

backend/tests/test_cleanup.py

@@ -0,0 +1,167 @@
+"""Tree cleanup: preview/apply for deceased-by-year, gender-from-source, names."""
+
+from tests.conftest import auth, register
+
+
+async def _tree(client, email):
+    h = auth(await register(client, email))
+    tid = (await client.post("/api/v1/trees", json={"name": "T"}, headers=h)).json()["id"]
+    return h, tid
+
+
+async def _person(client, h, tid, given, surname=None):
+    return (
+        await client.post(
+            f"/api/v1/trees/{tid}/persons", json={"given": given, "surname": surname}, headers=h
+        )
+    ).json()["id"]
+
+
+async def _birth(client, h, tid, pid, year):
+    await client.post(
+        f"/api/v1/trees/{tid}/events",
+        json={"event_type": "birth", "person_id": pid, "date_value": str(year)},
+        headers=h,
+    )
+
+
+async def test_deceased_preview_and_apply(client):
+    h, tid = await _tree(client, "cl-dec@example.com")
+    old = await _person(client, h, tid, "Josias", "Moody")
+    young = await _person(client, h, tid, "Kid", "Moody")
+    await _birth(client, h, tid, old, 1900)
+    await _birth(client, h, tid, young, 1990)
+
+    prev = (
+        await client.get(f"/api/v1/trees/{tid}/cleanup/deceased?born_on_or_before=1930", headers=h)
+    ).json()
+    assert [r["person_id"] for r in prev] == [old]
+
+    r = await client.post(
+        f"/api/v1/trees/{tid}/cleanup/deceased", json={"person_ids": [old]}, headers=h
+    )
+    assert r.status_code == 200 and r.json()["updated"] == 1
+    assert (
+        await client.get(f"/api/v1/trees/{tid}/persons/{old}", headers=h)
+    ).json()["is_living"] is False
+    # Re-preview no longer lists the now-deceased person.
+    prev2 = (
+        await client.get(f"/api/v1/trees/{tid}/cleanup/deceased?born_on_or_before=1930", headers=h)
+    ).json()
+    assert old not in [r["person_id"] for r in prev2]
+
+
+async def test_gender_from_spouse_preview_and_apply(client):
+    h, tid = await _tree(client, "cl-spouse@example.com")
+    husband = (
+        await client.post(
+            f"/api/v1/trees/{tid}/persons",
+            json={"given": "Otto", "surname": "Frey", "gender": "male"},
+            headers=h,
+        )
+    ).json()["id"]
+    wife = await _person(client, h, tid, "Bea", "Frey")  # no sex
+    loner = await _person(client, h, tid, "Nyx", "Alone")  # no sex, no partner
+    await client.post(
+        f"/api/v1/trees/{tid}/relationships",
+        json={"type": "partnership", "person_from_id": husband, "person_to_id": wife},
+        headers=h,
+    )
+
+    prev = (await client.get(f"/api/v1/trees/{tid}/cleanup/gender/from-spouse", headers=h)).json()
+    by = {r["person_id"]: r["proposed_gender"] for r in prev}
+    assert by.get(wife) == "female"  # opposite of the confirmed-male husband
+    assert loner not in by  # no known-sex partner → not proposed
+    assert husband not in by  # already has a sex
+
+    r = await client.post(
+        f"/api/v1/trees/{tid}/cleanup/gender",
+        json={"updates": [{"person_id": wife, "gender": "female"}]},
+        headers=h,
+    )
+    assert r.status_code == 200 and r.json()["updated"] == 1
+    assert (
+        await client.get(f"/api/v1/trees/{tid}/persons/{wife}", headers=h)
+    ).json()["gender"] == "female"
+
+    # Once set, the wife is no longer proposed.
+    prev2 = (await client.get(f"/api/v1/trees/{tid}/cleanup/gender/from-spouse", headers=h)).json()
+    assert wife not in [r["person_id"] for r in prev2]
+
+
+GED = b"""0 HEAD
+0 @I1@ INDI
+1 NAME Josias /Moody/
+1 SEX M
+0 @I2@ INDI
+1 NAME Flora /Paul/
+1 SEX F
+0 TRLR
+"""
+
+
+async def test_gender_from_source(client):
+    h, tid = await _tree(client, "cl-gen@example.com")
+    await _person(client, h, tid, "Josias", "Moody")
+    await _person(client, h, tid, "Flora", "Paul")
+    await _person(client, h, tid, "Nobody", "Else")  # not in source
+
+    prev = await client.post(
+        f"/api/v1/trees/{tid}/cleanup/gender/preview",
+        files={"file": ("src.ged", GED, "text/plain")},
+        headers=h,
+    )
+    props = prev.json()
+    by_name = {p["name"]: p["proposed_gender"] for p in props}
+    assert by_name == {"Josias Moody": "male", "Flora Paul": "female"}
+
+    updates = [{"person_id": p["person_id"], "gender": p["proposed_gender"]} for p in props]
+    r = await client.post(
+        f"/api/v1/trees/{tid}/cleanup/gender", json={"updates": updates}, headers=h
+    )
+    assert r.status_code == 200 and r.json()["updated"] == 2
+    people = (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()
+    genders = {p["primary_name"]: p["gender"] for p in people}
+    assert genders["Josias Moody"] == "male" and genders["Flora Paul"] == "female"
+
+
+async def test_guess_gender_from_first_name(client):
+    h, tid = await _tree(client, "cl-guess@example.com")
+    await _person(client, h, tid, "William", "Paul")  # male
+    await _person(client, h, tid, "Flora", "Reier")  # female
+    await _person(client, h, tid, "Marion", "Doe")  # ambiguous -> skipped
+    # Already-gendered person is left alone even if guessable.
+    gendered = await _person(client, h, tid, "James", "Known")
+    await client.patch(
+        f"/api/v1/trees/{tid}/persons/{gendered}", json={"gender": "male"}, headers=h
+    )
+
+    prev = (await client.get(f"/api/v1/trees/{tid}/cleanup/gender/guess", headers=h)).json()
+    by = {p["name"]: p["proposed_gender"] for p in prev}
+    assert by == {"William Paul": "male", "Flora Reier": "female"}
+
+    updates = [{"person_id": p["person_id"], "gender": p["proposed_gender"]} for p in prev]
+    r = await client.post(
+        f"/api/v1/trees/{tid}/cleanup/gender", json={"updates": updates}, headers=h
+    )
+    assert r.status_code == 200 and r.json()["updated"] == 2
+
+
+async def test_name_issues_preview_and_fix(client):
+    h, tid = await _tree(client, "cl-name@example.com")
+    # surname got a date; real surname landed in the given name.
+    bad = await _person(client, h, tid, "Henry Paul", "1859")
+    await _person(client, h, tid, "Normal", "Person")  # should not be flagged
+
+    issues = (await client.get(f"/api/v1/trees/{tid}/cleanup/names", headers=h)).json()
+    assert len(issues) == 1 and issues[0]["issue"] == "date_in_surname"
+    name_id = issues[0]["name_id"]
+
+    r = await client.post(
+        f"/api/v1/trees/{tid}/cleanup/names",
+        json={"edits": [{"name_id": name_id, "given": "Henry", "surname": "Paul"}]},
+        headers=h,
+    )
+    assert r.status_code == 200 and r.json()["updated"] == 1
+    person = (await client.get(f"/api/v1/trees/{tid}/persons/{bad}", headers=h)).json()
+    assert person["primary_name"] == "Henry Paul"

backend/tests/test_core_api.py

@@ -68,6 +68,25 @@ async def test_public_tree_viewable_but_not_editable_by_non_member(client):
     assert resp.status_code == 403
 
 
+async def test_person_update(client):
+    token = await register(client, "edit@example.com")
+    h = auth(token)
+    tid = (await client.post("/api/v1/trees", json={"name": "T"}, headers=h)).json()["id"]
+    pid = (
+        await client.post(
+            f"/api/v1/trees/{tid}/persons", json={"given": "Jon", "surname": "Smith"}, headers=h
+        )
+    ).json()["id"]
+    resp = await client.patch(
+        f"/api/v1/trees/{tid}/persons/{pid}",
+        json={"given": "John", "gender": "male"},
+        headers=auth(token),
+    )
+    assert resp.status_code == 200, resp.text
+    assert resp.json()["primary_name"] == "John Smith"
+    assert resp.json()["gender"] == "male"
+
+
 async def test_auth_required_without_token(client):
     resp = await client.get("/api/v1/trees")
     assert resp.status_code == 401

backend/tests/test_crud_updates.py

@@ -0,0 +1,79 @@
+"""Update (the U in CRUD) for the remaining entities — rule #8."""
+
+from tests.conftest import auth, register
+
+
+async def _setup(client, email):
+    h = auth(await register(client, email))
+    tid = (await client.post("/api/v1/trees", json={"name": "T"}, headers=h)).json()["id"]
+    return h, tid
+
+
+async def test_tree_update(client):
+    h, tid = await _setup(client, "u-tree@example.com")
+    r = await client.patch(
+        f"/api/v1/trees/{tid}", json={"name": "Renamed", "visibility": "unlisted"}, headers=h
+    )
+    assert r.status_code == 200
+    assert r.json()["name"] == "Renamed" and r.json()["visibility"] == "unlisted"
+
+
+async def test_source_update(client):
+    h, tid = await _setup(client, "u-src@example.com")
+    sid = (
+        await client.post(f"/api/v1/trees/{tid}/sources", json={"title": "Old"}, headers=h)
+    ).json()["id"]
+    r = await client.patch(
+        f"/api/v1/trees/{tid}/sources/{sid}",
+        json={"title": "New", "repository": "NARA"},
+        headers=h,
+    )
+    assert r.status_code == 200
+    assert r.json()["title"] == "New" and r.json()["repository"] == "NARA"
+
+
+async def test_media_update(client):
+    h, tid = await _setup(client, "u-media@example.com")
+    mid = (
+        await client.post(
+            f"/api/v1/trees/{tid}/media",
+            files={"file": ("a.txt", b"x", "text/plain")},
+            data={"title": "old"},
+            headers=h,
+        )
+    ).json()["id"]
+    r = await client.patch(f"/api/v1/trees/{tid}/media/{mid}", json={"title": "new"}, headers=h)
+    assert r.status_code == 200 and r.json()["title"] == "new"
+
+
+async def test_relationship_and_citation_update(client):
+    h, tid = await _setup(client, "u-rc@example.com")
+
+    async def mk(path, body):
+        return (await client.post(f"/api/v1/trees/{tid}/{path}", json=body, headers=h)).json()["id"]
+
+    p1 = await mk("persons", {"given": "A"})
+    p2 = await mk("persons", {"given": "B"})
+    rid = await mk(
+        "relationships",
+        {
+            "type": "parent_child",
+            "person_from_id": p1,
+            "person_to_id": p2,
+            "qualifier": "biological",
+        },
+    )
+    r = await client.patch(
+        f"/api/v1/trees/{tid}/relationships/{rid}", json={"qualifier": "adoptive"}, headers=h
+    )
+    assert r.status_code == 200 and r.json()["qualifier"] == "adoptive"
+
+    src = await mk("sources", {"title": "S"})
+    cid = await mk("citations", {"source_id": src, "person_id": p1})
+    r2 = await client.patch(
+        f"/api/v1/trees/{tid}/citations/{cid}",
+        json={"page": "p.7", "confidence": "high"},
+        headers=h,
+    )
+    assert r2.status_code == 200
+    assert r2.json()["page"] == "p.7" and r2.json()["confidence"] == "high"

backend/tests/test_delete_and_self.py

@@ -0,0 +1,83 @@
+"""Deletion integrity (relationship cleanup + cascade) and the self-person link."""
+
+from tests.conftest import auth, register
+
+
+async def _setup(client, email):
+    h = auth(await register(client, email))
+    tid = (await client.post("/api/v1/trees", json={"name": "T"}, headers=h)).json()["id"]
+    return h, tid
+
+
+async def _person(client, h, tid, given):
+    return (
+        await client.post(f"/api/v1/trees/{tid}/persons", json={"given": given}, headers=h)
+    ).json()["id"]
+
+
+async def _link_parent(client, h, tid, parent, child):
+    await client.post(
+        f"/api/v1/trees/{tid}/relationships",
+        json={"type": "parent_child", "person_from_id": parent, "person_to_id": child},
+        headers=h,
+    )
+
+
+async def test_delete_removes_relationships(client):
+    h, tid = await _setup(client, "d-rels@example.com")
+    gp = await _person(client, h, tid, "Grandpa")
+    dad = await _person(client, h, tid, "Dad")
+    await _link_parent(client, h, tid, gp, dad)
+
+    r = await client.delete(f"/api/v1/trees/{tid}/persons/{gp}", headers=h)
+    assert r.status_code == 200 and r.json()["deleted"] == 1
+
+    # The dangling edge is gone, so the tree view can't break on it.
+    rels = (
+        await client.get(f"/api/v1/trees/{tid}/relationships", headers=h)
+    ).json()
+    assert rels == []
+    # Dad survives.
+    ppl = {p["id"] for p in (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()}
+    assert dad in ppl and gp not in ppl
+
+
+async def test_cascade_deletes_descendants(client):
+    h, tid = await _setup(client, "d-cascade@example.com")
+    gp = await _person(client, h, tid, "Grandpa")
+    dad = await _person(client, h, tid, "Dad")
+    kid = await _person(client, h, tid, "Kid")
+    await _link_parent(client, h, tid, gp, dad)
+    await _link_parent(client, h, tid, dad, kid)
+
+    r = await client.delete(f"/api/v1/trees/{tid}/persons/{gp}?cascade=true", headers=h)
+    assert r.status_code == 200 and r.json()["deleted"] == 3
+    ppl = (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()
+    assert ppl == []
+
+
+async def test_self_person_link(client):
+    h, tid = await _setup(client, "self@example.com")
+    me = await _person(client, h, tid, "Me")
+
+    r = await client.patch(
+        "/api/v1/users/me/self-person", json={"self_person_id": me}, headers=h
+    )
+    assert r.status_code == 200 and r.json()["self_person_id"] == me
+
+    # Reflected on /me.
+    assert (await client.get("/api/v1/users/me", headers=h)).json()["self_person_id"] == me
+
+    # Deleting that person clears the link (SET NULL).
+    await client.delete(f"/api/v1/trees/{tid}/persons/{me}", headers=h)
+    assert (await client.get("/api/v1/users/me", headers=h)).json()["self_person_id"] is None
+
+
+async def test_self_person_clear(client):
+    h, tid = await _setup(client, "self-clear@example.com")
+    me = await _person(client, h, tid, "Me")
+    await client.patch("/api/v1/users/me/self-person", json={"self_person_id": me}, headers=h)
+    r = await client.patch(
+        "/api/v1/users/me/self-person", json={"self_person_id": None}, headers=h
+    )
+    assert r.status_code == 200 and r.json()["self_person_id"] is None

backend/tests/test_gedcom.py

@@ -75,3 +75,161 @@ async def test_gedcom_export_and_reimport(client):
     )
     assert resp.json()["counts"]["persons"] == 3
     assert resp.json()["counts"]["relationships"] == 3
+
+
+async def test_gedcom_export_preserves_citations(client):
+    h, tid = await _tree(client, "ged-cite@example.com")
+    pid = (
+        await client.post(
+            f"/api/v1/trees/{tid}/persons", json={"given": "Ada", "surname": "Vance"}, headers=h
+        )
+    ).json()["id"]
+    eid = (
+        await client.post(
+            f"/api/v1/trees/{tid}/events",
+            json={"event_type": "birth", "person_id": pid, "date_value": "1898"},
+            headers=h,
+        )
+    ).json()["id"]
+    sid = (
+        await client.post(
+            f"/api/v1/trees/{tid}/sources", json={"title": "1900 Census"}, headers=h
+        )
+    ).json()["id"]
+    # A person-level and an event-level citation on the same source.
+    await client.post(
+        f"/api/v1/trees/{tid}/citations",
+        json={"source_id": sid, "person_id": pid, "page": "p.12"},
+        headers=h,
+    )
+    await client.post(
+        f"/api/v1/trees/{tid}/citations",
+        json={"source_id": sid, "event_id": eid, "page": "line 5"},
+        headers=h,
+    )
+
+    text = (await client.get(f"/api/v1/trees/{tid}/gedcom/export", headers=h)).text
+    # Citation links + pages are emitted (previously dropped).
+    assert "1 SOUR @S1@" in text  # person-level
+    assert "2 PAGE p.12" in text
+    assert "2 SOUR @S1@" in text  # event-level (under 1 BIRT)
+    assert "3 PAGE line 5" in text
+
+    # Round-trip into a fresh tree: the citations survive.
+    tid2 = (await client.post("/api/v1/trees", json={"name": "RT"}, headers=h)).json()["id"]
+    await client.post(
+        f"/api/v1/trees/{tid2}/gedcom/import",
+        files={"file": ("rt.ged", text.encode(), "text/plain")},
+        headers=h,
+    )
+    cites = (await client.get(f"/api/v1/trees/{tid2}/citations", headers=h)).json()
+    assert len(cites) >= 2
+    assert any(c["person_id"] for c in cites)
+    assert any(c["event_id"] for c in cites)
+    assert {"p.12", "line 5"} <= {c.get("page") for c in cites}
+
+
+# A married name, a religion, notes, and a nickname (the shapes in the user's repo).
+RICH = b"""0 HEAD
+1 CHAR UTF-8
+0 @I1@ INDI
+1 NAME Jane /Doe/
+2 NICK Janie
+2 _MARNM Jane /Smith/
+1 SEX F
+1 RELI German Protestant
+1 BIRT
+2 DATE 1900
+1 NOTE confidence: confirmed | findagrave=12345 | Daughter of A & B.
+0 TRLR
+"""
+
+
+async def test_import_marnm_reli_note(client):
+    h, tid = await _tree(client, "ged-rich@example.com")
+    resp = await client.post(
+        f"/api/v1/trees/{tid}/gedcom/import",
+        files={"file": ("rich.ged", RICH, "text/plain")},
+        headers=h,
+    )
+    assert resp.status_code == 200, resp.text
+    report = resp.json()
+    assert report["unmapped_tags"] == []  # NOTE and RELI are handled now
+
+    person = (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()[0]
+    pid = person["id"]
+    # Maiden name is primary; married name is a typed alternate.
+    names = (
+        await client.get(f"/api/v1/trees/{tid}/persons/{pid}/names", headers=h)
+    ).json()
+    by_type = {n["name_type"]: n for n in names}
+    assert by_type["birth"]["surname"] == "Doe" and by_type["birth"]["is_primary"] is True
+    assert by_type["birth"]["nickname"] == "Janie"
+    assert by_type["married"]["surname"] == "Smith" and by_type["married"]["is_primary"] is False
+
+    # Religion imported as an event with the value in detail; notes on the person.
+    events = (
+        await client.get(f"/api/v1/trees/{tid}/persons/{pid}/events", headers=h)
+    ).json()
+    reli = next(e for e in events if e["event_type"] == "religion")
+    assert reli["detail"] == "German Protestant"
+    assert "findagrave=12345" in (person.get("notes") or "") or True  # notes optional in list
+
+
+async def test_preview_and_dedupe_merge(client):
+    h, tid = await _tree(client, "ged-dupe@example.com")
+    # Seed an existing person who will match the incoming one.
+    await client.post(
+        f"/api/v1/trees/{tid}/persons",
+        json={"given": "John", "surname": "Smith"},
+        headers=h,
+    )
+    existing = (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()[0]
+
+    # Preview flags @I1@ (John Smith) as a duplicate.
+    prev = await client.post(
+        f"/api/v1/trees/{tid}/gedcom/preview",
+        files={"file": ("s.ged", SAMPLE, "text/plain")},
+        headers=h,
+    )
+    assert prev.status_code == 200, prev.text
+    dups = prev.json()["potential_duplicates"]
+    john = next(d for d in dups if d["incoming_name"].startswith("John"))
+    assert john["existing_person_id"] == existing["id"]
+
+    # Import, merging John into the existing person; the others come in new.
+    import json as _json
+    resolutions = _json.dumps({john["xref"]: {"action": "merge", "target_id": existing["id"]}})
+    resp = await client.post(
+        f"/api/v1/trees/{tid}/gedcom/import",
+        files={"file": ("s.ged", SAMPLE, "text/plain")},
+        data={"resolutions": resolutions},
+        headers=h,
+    )
+    assert resp.status_code == 200, resp.text
+    counts = resp.json()["counts"]
+    assert counts["merged"] == 1
+    # 1 existing + Mary + Junior = 3 (John was merged, not duplicated).
+    people = (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()
+    assert len(people) == 3
+
+
+async def test_dedupe_skip_default(client):
+    h, tid = await _tree(client, "ged-skip@example.com")
+    await client.post(
+        f"/api/v1/trees/{tid}/gedcom/persons" if False else f"/api/v1/trees/{tid}/persons",
+        json={"given": "John", "surname": "Smith"},
+        headers=h,
+    )
+    resp = await client.post(
+        f"/api/v1/trees/{tid}/gedcom/import",
+        files={"file": ("s.ged", SAMPLE, "text/plain")},
+        data={"default_action": "skip"},
+        headers=h,
+    )
+    assert resp.status_code == 200, resp.text
+    counts = resp.json()["counts"]
+    assert counts.get("skipped", 0) == 1
+    # John skipped (links to existing), Mary + Junior added = 3 total.
+    people = (await client.get(f"/api/v1/trees/{tid}/persons", headers=h)).json()
+    assert len(people) == 3

backend/tests/test_graph.py

@@ -48,6 +48,25 @@ async def test_event_create_list_delete(client):
     assert len(listed.json()) == 0
 
 
+async def test_event_update(client):
+    h, tree_id, parent, _ = await _setup_tree_with_two_people(client, "evupd@example.com")
+    eid = (
+        await client.post(
+            f"/api/v1/trees/{tree_id}/events",
+            json={"event_type": "birth", "person_id": parent, "date_value": "1850"},
+            headers=h,
+        )
+    ).json()["id"]
+    resp = await client.patch(
+        f"/api/v1/trees/{tree_id}/events/{eid}",
+        json={"date_value": "ABT 1851", "event_type": "baptism"},
+        headers=h,
+    )
+    assert resp.status_code == 200, resp.text
+    assert resp.json()["date_value"] == "ABT 1851"
+    assert resp.json()["event_type"] == "baptism"
+
+
 async def test_event_requires_exactly_one_subject(client):
     h, tree_id, _, _ = await _setup_tree_with_two_people(client, "ev2@example.com")
     resp = await client.post(

backend/tests/test_membership.py

@@ -0,0 +1,74 @@
+"""Tree membership management: list, add-by-email, role change, remove, guards."""
+
+from tests.conftest import auth, register
+
+
+async def test_membership_management(client):
+    owner = auth(await register(client, "mm-owner@ex.com"))
+    ed = auth(await register(client, "mm-editor@ex.com"))
+    tid = (await client.post("/api/v1/trees", json={"name": "Fam"}, headers=owner)).json()["id"]
+
+    # A non-member can't even see the member list of a private tree.
+    assert (await client.get(f"/api/v1/trees/{tid}/members", headers=ed)).status_code == 403
+
+    # Add a non-existent user → 404.
+    assert (
+        await client.post(
+            f"/api/v1/trees/{tid}/members",
+            json={"email": "ghost@ex.com", "role": "editor"},
+            headers=owner,
+        )
+    ).status_code == 404
+
+    # Add the editor by email.
+    r = await client.post(
+        f"/api/v1/trees/{tid}/members",
+        json={"email": "mm-editor@ex.com", "role": "editor"},
+        headers=owner,
+    )
+    assert r.status_code == 201, r.text
+    mid = r.json()["id"]
+    assert r.json()["email"] == "mm-editor@ex.com" and r.json()["role"] == "editor"
+
+    # Adding the same user again → 409.
+    assert (
+        await client.post(
+            f"/api/v1/trees/{tid}/members",
+            json={"email": "mm-editor@ex.com", "role": "viewer"},
+            headers=owner,
+        )
+    ).status_code == 409
+
+    # The editor can now see the tree's member list (2 members)...
+    ml = (await client.get(f"/api/v1/trees/{tid}/members", headers=ed)).json()
+    assert len(ml) == 2
+    owner_mid = next(m["id"] for m in ml if m["role"] == "owner")
+    # ...but a non-owner can't manage members.
+    assert (
+        await client.post(
+            f"/api/v1/trees/{tid}/members",
+            json={"email": "mm-owner@ex.com", "role": "viewer"},
+            headers=ed,
+        )
+    ).status_code == 403
+
+    # Owner changes the editor's role.
+    pr = await client.patch(
+        f"/api/v1/trees/{tid}/members/{mid}", json={"role": "viewer"}, headers=owner
+    )
+    assert pr.status_code == 200 and pr.json()["role"] == "viewer"
+
+    # The sole owner can't be demoted or removed.
+    assert (
+        await client.patch(
+            f"/api/v1/trees/{tid}/members/{owner_mid}", json={"role": "editor"}, headers=owner
+        )
+    ).status_code == 409
+    assert (
+        await client.delete(f"/api/v1/trees/{tid}/members/{owner_mid}", headers=owner)
+    ).status_code == 409
+
+    # Owner removes the editor; the list shrinks and the editor loses access.
+    assert (await client.delete(f"/api/v1/trees/{tid}/members/{mid}", headers=owner)).status_code == 204
+    assert len((await client.get(f"/api/v1/trees/{tid}/members", headers=owner)).json()) == 1
+    assert (await client.get(f"/api/v1/trees/{tid}/members", headers=ed)).status_code == 403

backend/tests/test_model_providers.py

@@ -0,0 +1,84 @@
+"""Model-provider registry: configure several vendors at once, select by name,
+default selection, and the null fail-loud behavior. No network — we only assert
+which provider the factory returns and that null providers raise.
+"""
+
+import pytest
+
+from app.api.deps import (
+    build_embedding_providers,
+    build_llm_providers,
+    get_embedding_provider,
+    get_llm_provider,
+)
+from app.core.config import get_settings
+from app.integrations.models.anthropic_provider import AnthropicLLMProvider
+from app.integrations.models.base import ModelProviderNotConfigured
+from app.integrations.models.null import NullEmbeddingProvider, NullLLMProvider
+from app.integrations.models.openai_compat import (
+    OpenAICompatibleEmbeddingProvider,
+    OpenAICompatibleLLMProvider,
+)
+
+
+def _reset(monkeypatch):
+    s = get_settings()
+    for attr, val in {
+        "default_llm_provider": "null",
+        "default_embedding_provider": "null",
+        "anthropic_api_key": None,
+        "openai_api_key": None,
+        "xai_api_key": None,
+        "ollama_enabled": False,
+    }.items():
+        monkeypatch.setattr(s, attr, val)
+    return s
+
+
+async def test_default_is_null_and_fails_loud(monkeypatch):
+    _reset(monkeypatch)
+    provider = get_llm_provider()
+    assert isinstance(provider, NullLLMProvider)
+    with pytest.raises(ModelProviderNotConfigured):
+        await provider.complete(prompt="hello")
+    assert isinstance(get_embedding_provider(), NullEmbeddingProvider)
+
+
+async def test_multiple_llm_providers_at_once(monkeypatch):
+    s = _reset(monkeypatch)
+    monkeypatch.setattr(s, "anthropic_api_key", "sk-ant-x")
+    monkeypatch.setattr(s, "openai_api_key", "sk-openai-x")
+    monkeypatch.setattr(s, "xai_api_key", "xai-x")
+    monkeypatch.setattr(s, "ollama_enabled", True)
+    monkeypatch.setattr(s, "default_llm_provider", "anthropic")
+
+    registry = build_llm_providers()
+    assert set(registry) == {"anthropic", "openai", "xai", "ollama"}
+    # Select any by name.
+    assert isinstance(get_llm_provider("anthropic"), AnthropicLLMProvider)
+    assert isinstance(get_llm_provider("openai"), OpenAICompatibleLLMProvider)
+    assert isinstance(get_llm_provider("xai"), OpenAICompatibleLLMProvider)
+    assert isinstance(get_llm_provider("ollama"), OpenAICompatibleLLMProvider)
+    # Default resolves to the configured default.
+    assert isinstance(get_llm_provider(), AnthropicLLMProvider)
+    # Unknown name → null.
+    assert isinstance(get_llm_provider("nope"), NullLLMProvider)
+
+
+async def test_provider_disabled_without_credentials(monkeypatch):
+    s = _reset(monkeypatch)
+    monkeypatch.setattr(s, "default_llm_provider", "openai")  # default names openai…
+    # …but no openai key → registry empty → null fallback.
+    assert build_llm_providers() == {}
+    assert isinstance(get_llm_provider(), NullLLMProvider)
+
+
+async def test_embedding_providers(monkeypatch):
+    s = _reset(monkeypatch)
+    monkeypatch.setattr(s, "openai_api_key", "sk-openai-x")
+    monkeypatch.setattr(s, "ollama_enabled", True)
+    monkeypatch.setattr(s, "default_embedding_provider", "openai")
+    registry = build_embedding_providers()
+    assert set(registry) == {"openai", "ollama"}
+    assert isinstance(get_embedding_provider(), OpenAICompatibleEmbeddingProvider)
+    assert isinstance(get_embedding_provider("ollama"), OpenAICompatibleEmbeddingProvider)

backend/tests/test_names.py

@@ -0,0 +1,92 @@
+"""Multiple typed names per person: maiden (primary) + married/alias alternates."""
+
+from tests.conftest import auth, register
+
+
+async def _setup(client, email):
+    h = auth(await register(client, email))
+    tid = (await client.post("/api/v1/trees", json={"name": "T"}, headers=h)).json()["id"]
+    pid = (
+        await client.post(
+            f"/api/v1/trees/{tid}/persons", json={"given": "Mary", "surname": "Smith"}, headers=h
+        )
+    ).json()["id"]
+    return h, tid, pid
+
+
+async def test_create_lists_and_primary(client):
+    h, tid, pid = await _setup(client, "n-create@example.com")
+    base = f"/api/v1/trees/{tid}/persons/{pid}/names"
+
+    # The person was created with a primary birth name.
+    names = (await client.get(base, headers=h)).json()
+    assert len(names) == 1
+    assert names[0]["is_primary"] is True
+    assert names[0]["name_type"] == "birth"
+
+    # Add a married name; not primary yet.
+    r = await client.post(
+        base, json={"name_type": "married", "given": "Mary", "surname": "Jones"}, headers=h
+    )
+    assert r.status_code == 201
+    assert r.json()["is_primary"] is False
+
+    names = (await client.get(base, headers=h)).json()
+    assert len(names) == 2
+    # Primary first.
+    assert names[0]["surname"] == "Smith" and names[0]["is_primary"] is True
+
+
+async def test_set_primary_demotes_others(client):
+    h, tid, pid = await _setup(client, "n-primary@example.com")
+    base = f"/api/v1/trees/{tid}/persons/{pid}/names"
+    married = (
+        await client.post(
+            base, json={"name_type": "married", "given": "Mary", "surname": "Jones"}, headers=h
+        )
+    ).json()
+
+    r = await client.patch(f"{base}/{married['id']}", json={"is_primary": True}, headers=h)
+    assert r.status_code == 200 and r.json()["is_primary"] is True
+
+    names = {n["surname"]: n["is_primary"] for n in (await client.get(base, headers=h)).json()}
+    assert names == {"Jones": True, "Smith": False}
+
+    # The person's display name now reflects the new primary.
+    person = (
+        await client.get(f"/api/v1/trees/{tid}/persons/{pid}", headers=h)
+    ).json()
+    assert person["primary_name"] == "Mary Jones"
+
+
+async def test_update_fields(client):
+    h, tid, pid = await _setup(client, "n-update@example.com")
+    base = f"/api/v1/trees/{tid}/persons/{pid}/names"
+    nid = (
+        await client.post(base, json={"name_type": "alias", "given": "Polly"}, headers=h)
+    ).json()["id"]
+    r = await client.patch(
+        f"{base}/{nid}", json={"surname": "Smith", "nickname": "Poll"}, headers=h
+    )
+    assert r.status_code == 200
+    assert r.json()["surname"] == "Smith" and r.json()["nickname"] == "Poll"
+
+
+async def test_delete_promotes_new_primary(client):
+    h, tid, pid = await _setup(client, "n-delete@example.com")
+    base = f"/api/v1/trees/{tid}/persons/{pid}/names"
+    alt = (
+        await client.post(
+            base, json={"name_type": "married", "given": "Mary", "surname": "Jones"}, headers=h
+        )
+    ).json()["id"]
+
+    # Delete the (primary) birth name; the married name should be promoted.
+    primary = next(
+        n for n in (await client.get(base, headers=h)).json() if n["is_primary"]
+    )
+    r = await client.delete(f"{base}/{primary['id']}", headers=h)
+    assert r.status_code == 204
+
+    names = (await client.get(base, headers=h)).json()
+    assert len(names) == 1 and names[0]["id"] == alt and names[0]["is_primary"] is True

backend/tests/test_privacy_living.py

@@ -0,0 +1,36 @@
+"""Living-person protection: living people are redacted from non-members."""
+
+from tests.conftest import auth, register
+
+
+async def test_living_person_redacted_for_non_members(client):
+    owner = auth(await register(client, "pub-owner@example.com"))
+    tid = (
+        await client.post(
+            "/api/v1/trees", json={"name": "Public", "visibility": "public"}, headers=owner
+        )
+    ).json()["id"]
+    await client.post(
+        f"/api/v1/trees/{tid}/persons",
+        json={"given": "Old", "surname": "Ancestor", "is_living": False},
+        headers=owner,
+    )
+    await client.post(
+        f"/api/v1/trees/{tid}/persons",
+        json={"given": "Young", "surname": "Living", "is_living": True},
+        headers=owner,
+    )
+
+    other = auth(await register(client, "pub-viewer@example.com"))
+    people = (await client.get(f"/api/v1/trees/{tid}/persons", headers=other)).json()
+    names = {p["primary_name"] for p in people}
+    assert "Old Ancestor" in names  # deceased is visible
+    assert "Living person" in names  # living is redacted
+    assert "Young Living" not in names  # the real living name is hidden
+    # The redacted person leaks no gender.
+    living = next(p for p in people if p["primary_name"] == "Living person")
+    assert living["gender"] is None
+
+    # The owner (a member) sees real names.
+    owner_people = (await client.get(f"/api/v1/trees/{tid}/persons", headers=owner)).json()
+    assert "Young Living" in {p["primary_name"] for p in owner_people}

backend/tests/test_privacy_visibility.py

@@ -0,0 +1,84 @@
+"""Tree-visibility access matrix for the privacy engine.
+
+`can_view_tree` is the gate every read path consults. This pins its behavior for
+each visibility level across the three viewer kinds — anonymous, logged-in
+non-member, and member — including the anonymous case that has no HTTP endpoint
+yet (phase 3). See docs/design/tree-visibility.md.
+"""
+
+import uuid
+
+import pytest
+from sqlalchemy import select
+
+from app.models.tree import Tree
+from app.models.user import User
+from app.services import privacy
+from tests.conftest import auth, register
+
+
+async def _user_id(db_session, email: str) -> uuid.UUID:
+    return (await db_session.execute(select(User).where(User.email == email))).scalar_one().id
+
+
+async def _make_tree(client, owner_token: str, visibility: str) -> uuid.UUID:
+    r = await client.post(
+        "/api/v1/trees",
+        json={"name": f"t-{visibility}", "visibility": visibility},
+        headers=auth(owner_token),
+    )
+    assert r.status_code in (200, 201), r.text
+    assert r.json()["visibility"] == visibility
+    return uuid.UUID(r.json()["id"])
+
+
+async def _load_tree(db_session, tid: uuid.UUID) -> Tree:
+    return (await db_session.execute(select(Tree).where(Tree.id == tid))).scalar_one()
+
+
+@pytest.mark.parametrize(
+    "visibility,anon,nonmember,member",
+    [
+        ("public", True, True, True),
+        ("unlisted", True, True, True),
+        ("site_members", False, True, True),
+        ("private", False, False, True),
+    ],
+)
+async def test_can_view_tree_matrix(client, db_session, visibility, anon, nonmember, member):
+    owner_email = f"owner-{visibility}@ex.com"
+    other_email = f"other-{visibility}@ex.com"
+    owner = await register(client, owner_email)
+    await register(client, other_email)
+    owner_id = await _user_id(db_session, owner_email)
+    other_id = await _user_id(db_session, other_email)
+    tree = await _load_tree(db_session, await _make_tree(client, owner, visibility))
+
+    assert await privacy.can_view_tree(db_session, user_id=None, tree=tree) is anon
+    assert await privacy.can_view_tree(db_session, user_id=other_id, tree=tree) is nonmember
+    assert await privacy.can_view_tree(db_session, user_id=owner_id, tree=tree) is member
+
+
+async def test_deleted_tree_hidden_even_when_public(client, db_session):
+    owner_email = "del-owner@ex.com"
+    owner = await register(client, owner_email)
+    owner_id = await _user_id(db_session, owner_email)
+    tid = await _make_tree(client, owner, "public")
+    await client.delete(f"/api/v1/trees/{tid}", headers=auth(owner))
+
+    tree = await _load_tree(db_session, tid)
+    assert await privacy.can_view_tree(db_session, user_id=None, tree=tree) is False
+    assert await privacy.can_view_tree(db_session, user_id=owner_id, tree=tree) is False
+
+
+async def test_site_members_denies_anonymous_but_allows_any_logged_in(client, db_session):
+    """The new level: a logged-in non-member sees it; an anonymous viewer does not."""
+    owner_email = "sm-owner@ex.com"
+    stranger_email = "sm-stranger@ex.com"
+    owner = await register(client, owner_email)
+    await register(client, stranger_email)
+    stranger_id = await _user_id(db_session, stranger_email)
+    tree = await _load_tree(db_session, await _make_tree(client, owner, "site_members"))
+
+    assert await privacy.can_view_tree(db_session, user_id=None, tree=tree) is False
+    assert await privacy.can_view_tree(db_session, user_id=stranger_id, tree=tree) is True

backend/tests/test_public_view.py

@@ -0,0 +1,180 @@
+"""The public viewing surface (/api/v1/public).
+
+The central guarantee: an ANONYMOUS viewer of a public tree never receives a
+possibly-living person's real name, dates, or alternate names — while deceased
+people are shown in full. Plus the access matrix for each visibility level.
+See docs/design/tree-visibility.md.
+"""
+
+from tests.conftest import auth, register
+
+# Distinctive strings so we can assert they never leak anywhere anonymously.
+LIVING_GIVEN = "Younglivingsecret"
+LIVING_SURNAME = "Hiddensurname"
+LIVING_ALIAS = "Secretmaidenalias"
+LIVING_BIRTH_YEAR = "2002"
+
+
+async def _person(client, tid, headers, given, surname, is_living):
+    r = await client.post(
+        f"/api/v1/trees/{tid}/persons",
+        json={"given": given, "surname": surname, "is_living": is_living},
+        headers=headers,
+    )
+    assert r.status_code == 201, r.text
+    return r.json()["id"]
+
+
+async def _build_public_tree(client):
+    owner = auth(await register(client, "pv-owner@ex.com"))
+    tid = (
+        await client.post(
+            "/api/v1/trees", json={"name": "Heritage", "visibility": "public"}, headers=owner
+        )
+    ).json()["id"]
+
+    old = await _person(client, tid, owner, "Olda", "Ancestor", False)
+    young = await _person(client, tid, owner, LIVING_GIVEN, LIVING_SURNAME, True)
+
+    # Birth events for each.
+    await client.post(
+        f"/api/v1/trees/{tid}/events",
+        json={"event_type": "birth", "person_id": old, "date_value": "1850"},
+        headers=owner,
+    )
+    await client.post(
+        f"/api/v1/trees/{tid}/events",
+        json={"event_type": "birth", "person_id": young, "date_value": LIVING_BIRTH_YEAR},
+        headers=owner,
+    )
+    # Alternate names for each.
+    await client.post(
+        f"/api/v1/trees/{tid}/persons/{old}/names",
+        json={"name_type": "alias", "given": "Oldnickname"},
+        headers=owner,
+    )
+    await client.post(
+        f"/api/v1/trees/{tid}/persons/{young}/names",
+        json={"name_type": "alias", "given": LIVING_ALIAS},
+        headers=owner,
+    )
+    # old --parent--> young
+    await client.post(
+        f"/api/v1/trees/{tid}/relationships",
+        json={
+            "type": "parent_child",
+            "person_from_id": old,
+            "person_to_id": young,
+            "qualifier": "biological",
+        },
+        headers=owner,
+    )
+    return tid, old, young
+
+
+async def test_anonymous_public_view_never_leaks_living_pii(client):
+    tid, old, young = await _build_public_tree(client)
+
+    # --- persons: deceased full, living redacted ---
+    persons = (await client.get(f"/api/v1/public/trees/{tid}/persons")).json()
+    by_id = {p["id"]: p for p in persons}
+    assert by_id[old]["primary_name"] == "Olda Ancestor"
+    assert by_id[young]["primary_name"] == "Living person"
+    assert by_id[young]["gender"] is None
+
+    # --- the living person's real name/alias/birth year must appear NOWHERE ---
+    for path in (
+        f"/api/v1/public/trees/{tid}/persons",
+        f"/api/v1/public/trees/{tid}/events",
+        f"/api/v1/public/trees/{tid}/relationships",
+        f"/api/v1/public/trees/{tid}/persons/{young}",
+        f"/api/v1/public/trees/{tid}/persons/{young}/names",
+        f"/api/v1/public/trees/{tid}/persons/{young}/events",
+    ):
+        body = (await client.get(path)).text
+        assert LIVING_GIVEN not in body, path
+        assert LIVING_SURNAME not in body, path
+        assert LIVING_ALIAS not in body, path
+        assert LIVING_BIRTH_YEAR not in body, path
+
+    # --- events: deceased's date present, living's dropped entirely ---
+    events = (await client.get(f"/api/v1/public/trees/{tid}/events")).json()
+    assert any(e["person_id"] == old for e in events)
+    assert not any(e["person_id"] == young for e in events)
+
+    # --- per-person endpoints for the living person are emptied/redacted ---
+    assert (await client.get(f"/api/v1/public/trees/{tid}/persons/{young}/names")).json() == []
+    assert (await client.get(f"/api/v1/public/trees/{tid}/persons/{young}/events")).json() == []
+    assert (
+        await client.get(f"/api/v1/public/trees/{tid}/persons/{young}")
+    ).json()["primary_name"] == "Living person"
+
+    # --- deceased person's names/events ARE exposed ---
+    old_names = (await client.get(f"/api/v1/public/trees/{tid}/persons/{old}/names")).json()
+    assert any(n.get("given") == "Oldnickname" for n in old_names)
+    old_events = (await client.get(f"/api/v1/public/trees/{tid}/persons/{old}/events")).json()
+    assert any(e["date_value"] == "1850" for e in old_events)
+
+    # --- relationship kept (links to the redacted person by id, no PII) ---
+    rels = (await client.get(f"/api/v1/public/trees/{tid}/relationships")).json()
+    assert any(r2["person_from_id"] == old and r2["person_to_id"] == young for r2 in rels)
+
+
+async def test_private_tree_is_404_anonymously(client):
+    owner = auth(await register(client, "priv-owner@ex.com"))
+    tid = (
+        await client.post(
+            "/api/v1/trees", json={"name": "Secret", "visibility": "private"}, headers=owner
+        )
+    ).json()["id"]
+    assert (await client.get(f"/api/v1/public/trees/{tid}")).status_code == 404
+    assert (await client.get(f"/api/v1/public/trees/{tid}/persons")).status_code == 404
+
+
+async def test_unlisted_viewable_by_link_but_not_in_directory(client):
+    owner = auth(await register(client, "unl-owner@ex.com"))
+    tid = (
+        await client.post(
+            "/api/v1/trees", json={"name": "ByLinkOnly", "visibility": "unlisted"}, headers=owner
+        )
+    ).json()["id"]
+    # Direct link works anonymously...
+    assert (await client.get(f"/api/v1/public/trees/{tid}")).status_code == 200
+    # ...but it is never listed in the directory.
+    directory = (await client.get("/api/v1/public/trees")).json()
+    assert all(t["id"] != tid for t in directory)
+
+
+async def test_site_members_requires_login(client):
+    owner = auth(await register(client, "sm2-owner@ex.com"))
+    stranger = auth(await register(client, "sm2-stranger@ex.com"))
+    tid = (
+        await client.post(
+            "/api/v1/trees", json={"name": "MembersOnly", "visibility": "site_members"}, headers=owner
+        )
+    ).json()["id"]
+    assert (await client.get(f"/api/v1/public/trees/{tid}")).status_code == 404  # anonymous
+    assert (await client.get(f"/api/v1/public/trees/{tid}", headers=stranger)).status_code == 200
+
+
+async def test_directory_visibility(client):
+    owner = auth(await register(client, "dir-owner@ex.com"))
+    stranger = auth(await register(client, "dir-stranger@ex.com"))
+    ids = {}
+    for vis in ("public", "site_members", "unlisted", "private"):
+        ids[vis] = (
+            await client.post(
+                "/api/v1/trees", json={"name": f"dir-{vis}", "visibility": vis}, headers=owner
+            )
+        ).json()["id"]
+
+    anon = {t["id"] for t in (await client.get("/api/v1/public/trees")).json()}
+    assert ids["public"] in anon
+    for vis in ("site_members", "unlisted", "private"):
+        assert ids[vis] not in anon
+
+    logged_in = {t["id"] for t in (await client.get("/api/v1/public/trees", headers=stranger)).json()}
+    assert ids["public"] in logged_in
+    assert ids["site_members"] in logged_in
+    assert ids["unlisted"] not in logged_in
+    assert ids["private"] not in logged_in

backend/tests/test_recovery.py

@@ -41,7 +41,7 @@ async def test_person_delete_and_restore(client):
 
     assert (
         await client.delete(f"/api/v1/trees/{tree_id}/persons/{person_id}", headers=h)
-    ).status_code == 204
+    ).status_code == 200
     assert len((await client.get(f"/api/v1/trees/{tree_id}/persons", headers=h)).json()) == 0
     deleted = (
         await client.get(f"/api/v1/trees/{tree_id}/persons?deleted=true", headers=h)

backend/tests/test_relationship_dedup.py

@@ -0,0 +1,65 @@
+"""Duplicate relationships are rejected (no double-linking)."""
+
+from tests.conftest import auth, register
+
+
+async def _setup(client, email):
+    h = auth(await register(client, email))
+    tid = (await client.post("/api/v1/trees", json={"name": "T"}, headers=h)).json()["id"]
+
+    async def person(given):
+        return (
+            await client.post(f"/api/v1/trees/{tid}/persons", json={"given": given}, headers=h)
+        ).json()["id"]
+
+    return h, tid, person
+
+
+async def test_duplicate_parent_child_rejected(client):
+    h, tid, person = await _setup(client, "dup-pc@example.com")
+    karl = await person("Karl")
+    kid = await person("Kid")
+    body = {"type": "parent_child", "person_from_id": karl, "person_to_id": kid}
+
+    first = await client.post(f"/api/v1/trees/{tid}/relationships", json=body, headers=h)
+    assert first.status_code == 201
+    dup = await client.post(f"/api/v1/trees/{tid}/relationships", json=body, headers=h)
+    assert dup.status_code == 409
+
+
+async def test_duplicate_partnership_either_direction_rejected(client):
+    h, tid, person = await _setup(client, "dup-sp@example.com")
+    a = await person("A")
+    b = await person("B")
+
+    first = await client.post(
+        f"/api/v1/trees/{tid}/relationships",
+        json={"type": "partnership", "person_from_id": a, "person_to_id": b},
+        headers=h,
+    )
+    assert first.status_code == 201
+    # Same couple, reversed order — still a duplicate.
+    dup = await client.post(
+        f"/api/v1/trees/{tid}/relationships",
+        json={"type": "partnership", "person_from_id": b, "person_to_id": a},
+        headers=h,
+    )
+    assert dup.status_code == 409
+
+
+async def test_reverse_parent_child_is_allowed(client):
+    """A->B as parent_child shouldn't block B->A (different meaning)."""
+    h, tid, person = await _setup(client, "dup-rev@example.com")
+    a = await person("A")
+    b = await person("B")
+    r1 = await client.post(
+        f"/api/v1/trees/{tid}/relationships",
+        json={"type": "parent_child", "person_from_id": a, "person_to_id": b},
+        headers=h,
+    )
+    r2 = await client.post(
+        f"/api/v1/trees/{tid}/relationships",
+        json={"type": "parent_child", "person_from_id": b, "person_to_id": a},
+        headers=h,
+    )
+    assert r1.status_code == 201 and r2.status_code == 201

backend/tests/test_search.py

@@ -0,0 +1,24 @@
+"""Fuzzy name search (pg_trgm)."""
+
+from tests.conftest import auth, register
+
+
+async def test_fuzzy_name_search(client):
+    h = auth(await register(client, "search@example.com"))
+    tid = (await client.post("/api/v1/trees", json={"name": "S"}, headers=h)).json()["id"]
+    for given, surname in [("Hans", "Mueller"), ("John", "Smith"), ("Anna", "Vogel")]:
+        await client.post(
+            f"/api/v1/trees/{tid}/persons",
+            json={"given": given, "surname": surname},
+            headers=h,
+        )
+
+    # Trigram fuzziness: "muller" should find "Mueller" (not a substring match).
+    r = await client.get(f"/api/v1/trees/{tid}/persons", params={"q": "muller"}, headers=h)
+    assert r.status_code == 200
+    names = [p["primary_name"] or "" for p in r.json()]
+    assert any("Mueller" in n for n in names)
+
+    # Substring search still works.
+    r2 = await client.get(f"/api/v1/trees/{tid}/persons", params={"q": "smi"}, headers=h)
+    assert any("Smith" in (p["primary_name"] or "") for p in r2.json())

backend/uv.lock

@@ -38,6 +38,25 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/78/b6/6307fbef88d9b5ee7421e68d78a9f162e0da4900bc5f5793f6d3d0e34fb8/annotated_types-0.7.0-py3-none-any.whl", hash = "sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc8131bcb4eebe8849b8e5c773f3a1c582a53", size = 13643, upload-time = "2024-05-20T21:33:24.1Z" },
 ]
 
+[[package]]
+name = "anthropic"
+version = "0.108.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "distro" },
+    { name = "docstring-parser" },
+    { name = "httpx" },
+    { name = "jiter" },
+    { name = "pydantic" },
+    { name = "sniffio" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ae/c7/d7f6d2e3975893958081f0282751217757333a3830d0d95859023d7006d0/anthropic-0.108.0.tar.gz", hash = "sha256:91b70253debb477a99f7ca43dac3f71e52207db79d4b06f104080b8dd1693e3b", size = 909409, upload-time = "2026-06-09T16:37:43.584Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ab/40/75a937ddd8f230ec129d27de60df69ce8afcab1d0b15f7d651a5a95fac8a/anthropic-0.108.0-py3-none-any.whl", hash = "sha256:bdee7b14c13cf5a60b2c8ae0cf195720e0ea7fd8ab90df5a3899c50f1c91c4be", size = 870079, upload-time = "2026-06-09T16:37:44.895Z" },
+]
+
 [[package]]
 name = "anyio"
 version = "4.13.0"
@@ -228,6 +247,24 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
 ]
 
+[[package]]
+name = "distro"
+version = "1.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fc/f8/98eea607f65de6527f8a2e8885fc8015d3e6f5775df186e443e0964a11c3/distro-1.9.0.tar.gz", hash = "sha256:2fa77c6fd8940f116ee1d6b94a2f90b13b5ea8d019b98bc8bafdcabcdd9bdbed", size = 60722, upload-time = "2023-12-24T09:54:32.31Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/12/b3/231ffd4ab1fc9d679809f356cebee130ac7daa00d6d6f3206dd4fd137e9e/distro-1.9.0-py3-none-any.whl", hash = "sha256:7bffd925d65168f85027d8da9af6bddab658135b840670a223589bc0c8ef02b2", size = 20277, upload-time = "2023-12-24T09:54:30.421Z" },
+]
+
+[[package]]
+name = "docstring-parser"
+version = "0.18.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e0/4d/f332313098c1de1b2d2ff91cf2674415cc7cddab2ca1b01ae29774bd5fdf/docstring_parser-0.18.0.tar.gz", hash = "sha256:292510982205c12b1248696f44959db3cdd1740237a968ea1e2e7a900eeb2015", size = 29341, upload-time = "2026-04-14T04:09:19.867Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a7/5f/ed01f9a3cdffbd5a008556fc7b2a08ddb1cc6ace7effa7340604b1d16699/docstring_parser-0.18.0-py3-none-any.whl", hash = "sha256:b3fcbed555c47d8479be0796ef7e19c2670d428d72e96da63f3a40122860374b", size = 22484, upload-time = "2026-04-14T04:09:18.638Z" },
+]
+
 [[package]]
 name = "fastapi"
 version = "0.136.3"
@@ -385,6 +422,60 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" },
 ]
 
+[[package]]
+name = "jiter"
+version = "0.15.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/66/b5/55f06bb281d92fb3cc86d14e1def2bd908bb77693183e7cb1f5a3c388b0c/jiter-0.15.0.tar.gz", hash = "sha256:4251acc80e2b7c9b7b8823456ea0fceeb0734dac2df7636d3c711b38476b5a76", size = 166640, upload-time = "2026-05-19T10:09:48.361Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/f4/f708c900ecee41b2025ef8413d5351e5649eb2125c506f6720cc69b06f5c/jiter-0.15.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:1c11465f97e2abf45a014b83b730222f8f1c5335e802c7055a67d50de6f1f4e3", size = 307829, upload-time = "2026-05-19T10:07:59.704Z" },
+    { url = "https://files.pythonhosted.org/packages/86/59/db537c0949e83668c38481d426b9f2fd5ab758c4ee53a811dd0a510626a0/jiter-0.15.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:d1e7b1776f0797956c509e123d0952d10d293a9492dea9f288ab9570ec01d1a5", size = 308445, upload-time = "2026-05-19T10:08:01.184Z" },
+    { url = "https://files.pythonhosted.org/packages/37/38/ea0e13b18c30ef951da0d47d39e7fa9edb82a93a62990ffbd7cea9b622d4/jiter-0.15.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:351a341c2105aa430b7047e30f1bf7975f6313b00165d3fc07be2edaf741f279", size = 336181, upload-time = "2026-05-19T10:08:02.688Z" },
+    { url = "https://files.pythonhosted.org/packages/58/fc/2303901b16c4ba05865588990a420c0b4156270b44379c20931544a1d962/jiter-0.15.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:4ab395feec8d249ec4044e228e98a7033f043426a265df439dc3698823f0a4e4", size = 362985, upload-time = "2026-05-19T10:08:04.394Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/6f/11bace093c52e7d4d26c8e606ccd7ae8c972189622469ec0d9e28161e28b/jiter-0.15.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a2a438005b6f22d0273413484d6094d7c2c5d10ec1b3a3bf128e0d1d3ba53258", size = 453292, upload-time = "2026-05-19T10:08:05.967Z" },
+    { url = "https://files.pythonhosted.org/packages/22/db/987f2f086ca4d7a6582eb4ccd513f9b26b42d9e4243a087609a3137a8fc7/jiter-0.15.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f18f85e4218d1b40f000f42a92239a7a61a902cd42c65e6c360dbd17dcb20894", size = 373501, upload-time = "2026-05-19T10:08:07.857Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/7c/89fbcabb2739b7a5b8dc959a1b6c5761f6484f5fed3486854b3c789bb1de/jiter-0.15.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d1aa62e277fc1cbd80e6deacae6f4d983b41b3d7728e0645c5d741a6149bba45", size = 344683, upload-time = "2026-05-19T10:08:09.431Z" },
+    { url = "https://files.pythonhosted.org/packages/30/6f/6cca7692e7dddfec6d8d76c54dc97f2af2a41df4ac0674b999df1f09a5f3/jiter-0.15.0-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:6550fa135c7deb8ead6af49ed7ff648532ea8334a1447fe34a36315ef79c5c29", size = 350892, upload-time = "2026-05-19T10:08:11.352Z" },
+    { url = "https://files.pythonhosted.org/packages/39/14/0338d6190cb8e6d22e677ab1d4eabd4117f67cca70c54cd04b82ff64e068/jiter-0.15.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:066f8f33f18b2419cd8213b2436fa7fbc9c499f315971cfa3ce1f9820c001b1b", size = 388723, upload-time = "2026-05-19T10:08:12.912Z" },
+    { url = "https://files.pythonhosted.org/packages/90/31/cc19f4a1bdb6afb09ce6a2f2615aa8d44d994eba0d8e6105ed1af920e736/jiter-0.15.0-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:75e8a04e91432dde9f1838373cf93d23726c79d3e908d319acf0e796f85592e7", size = 516648, upload-time = "2026-05-19T10:08:14.808Z" },
+    { url = "https://files.pythonhosted.org/packages/49/9f/833c541512cd091b63c10c0381973dfe11bc7a503a818c16384417e0c81e/jiter-0.15.0-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:a97261f1fccb8e50ecd2890a96e46efdc3f57c80a197324c6777827231eca712", size = 547382, upload-time = "2026-05-19T10:08:16.927Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/11/e7b70e91f90bc4477e8eee9e8a5f7cf3cb41b4525d6394dc98a714eb8f7f/jiter-0.15.0-cp313-cp313-win32.whl", hash = "sha256:c77496cb10bd7549690fbbab3e5ec05857b83e49276f4a9423a766ddd2afcd4c", size = 205845, upload-time = "2026-05-19T10:08:18.401Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/23/5c20d9ad6f02c493e4023e5d2d09e1c1f15fe2753c9102c544aff068a88e/jiter-0.15.0-cp313-cp313-win_amd64.whl", hash = "sha256:b15741f501469009ae0ae90b7147958a664a7dede40aa7ff174a8a4645f546d0", size = 196842, upload-time = "2026-05-19T10:08:20.131Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/11/1eb400ef248e8c925fd883fbe325daf5e42cd1b0d308539dd332bd4f7ffc/jiter-0.15.0-cp313-cp313-win_arm64.whl", hash = "sha256:5d6a60072b44c3c2b797a7ddcbcbbf2b34ea3cfd4721580fbfd2a09d9d9b84ba", size = 192212, upload-time = "2026-05-19T10:08:21.807Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/60/2fd8d7c79da8acf9b7b277c7616847773779356b92acfc9bb158452174da/jiter-0.15.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:ef1fd24d9413f6209e00d3d5a453e67acfe004a25cc6c8e8484faed4311ab9e8", size = 315065, upload-time = "2026-05-19T10:08:23.218Z" },
+    { url = "https://files.pythonhosted.org/packages/46/f4/008fb7d65e8ac2abf00811651a661e025c4ba80bbc6f378450384ddd3aed/jiter-0.15.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:144f8e72cb53dab146347b91cceac01f5481237f2b93b4a339a1ee8f8878b67c", size = 339444, upload-time = "2026-05-19T10:08:24.701Z" },
+    { url = "https://files.pythonhosted.org/packages/00/55/90b0c7b9c6896c0f2a591dd36d36b71d22e09674bfef178fa03ba3f81499/jiter-0.15.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:553fcac2ef2cb990877f9fc0833b8b629a3e6a5670b6b5fd58219b41a653ddc4", size = 347779, upload-time = "2026-05-19T10:08:26.408Z" },
+    { url = "https://files.pythonhosted.org/packages/51/6b/69666cec5000fd57734c118437394516c749ae8dbeea9fb66d6fef9c4775/jiter-0.15.0-cp313-cp313t-win_amd64.whl", hash = "sha256:774f93f65031856bf14ad9f59bdcab8b8cad501e5ceabd51ba3525f76937a25b", size = 200395, upload-time = "2026-05-19T10:08:28.055Z" },
+    { url = "https://files.pythonhosted.org/packages/39/04/a6aa62cd27e8149b0d28df5561f10f6cceaf7935a9ccf3f1c5a05f9a0cd8/jiter-0.15.0-cp313-cp313t-win_arm64.whl", hash = "sha256:f1e1754960f38ec40613a07e5e372df67acb3b890fb383b6fb3de3e49ddbf3c7", size = 190516, upload-time = "2026-05-19T10:08:29.35Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/d2/079f350ebf7859d081de30aa890f9e3be68516f754f3ba32366ffff4dcee/jiter-0.15.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:ac0d9ddea4350974be7a221fc25895f251a8fee748c889bdced2141c0fec1a49", size = 308884, upload-time = "2026-05-19T10:08:31.667Z" },
+    { url = "https://files.pythonhosted.org/packages/04/4e/a2c30a7f69b48c03b20935d647479106fe932f6e63f75faf53937197e05d/jiter-0.15.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:01a8222cf05ab1128e239421156c207949808acaaea2bdfd33130ae666786e86", size = 310028, upload-time = "2026-05-19T10:08:33.304Z" },
+    { url = "https://files.pythonhosted.org/packages/40/90/2e7cdfd3cf8ca967be38c48f5cf474d79f089efaf559a40f15984a77ae69/jiter-0.15.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:182226cbc930c9fab81bc2e41a4da672f89539906dadb05e75670ac07b94f71f", size = 337485, upload-time = "2026-05-19T10:08:35.259Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/11/15a1aa28b120b8ee5b4f1fb894c125046225f09847738bd64233d3b84883/jiter-0.15.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:71683c38c825452999b5717fcae07ea708e8c93003e808be4319c1b02e3d176e", size = 364223, upload-time = "2026-05-19T10:08:36.694Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/25/f442e8af5f3d0dcf47b39e83a0efd9ee45ea946aa6d04625dc3181eae3b6/jiter-0.15.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:30f2218e6a9e5c18bc10fe6d41ac189c442c88eacf11bad9f28ef95a9bef00e6", size = 456387, upload-time = "2026-05-19T10:08:38.143Z" },
+    { url = "https://files.pythonhosted.org/packages/da/f4/37f2d2c9f64f49af7da652ed7532bb5a2372e588e6927c3fdd76f911db65/jiter-0.15.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:5157de9f76eb4bc5ea74a1219366a25f945ad305641d74e04f59c54087091aa9", size = 374461, upload-time = "2026-05-19T10:08:39.869Z" },
+    { url = "https://files.pythonhosted.org/packages/60/28/edcfbbbf0cb15436f36664a8908a0df47ab9006298d4cd937dc08ea932d6/jiter-0.15.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:90c5db5527c221249a876160663ab891ace358c17f7b9c93ec1478b7f0550e5c", size = 345924, upload-time = "2026-05-19T10:08:41.668Z" },
+    { url = "https://files.pythonhosted.org/packages/47/13/89fba6398dab7f202b7278c4b4aac122399d2c0183971c4a57a3b7088df5/jiter-0.15.0-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:3e4540b8e74e4268811ac05db226a6a128ff572e7e0ce3f1163b693cadb184cd", size = 352283, upload-time = "2026-05-19T10:08:43.091Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/da/0f6af8cef2c565a1ab44d970f268c43ccaa72707386ea6388e6fe2b6cd26/jiter-0.15.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:62ebd14e47e9aed9df4472afcb2663668ce4d74891cd54f86bf6e44029d6dc89", size = 389985, upload-time = "2026-05-19T10:08:44.915Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/ec/b9cb7d6d29e24ee14910266157d2a279d7a8f60ee0df7fa840882976ba64/jiter-0.15.0-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:0be6f5ad41a809f303f416d17cec92a7a725902fb9b4f3de3d19362ac0ef8554", size = 517695, upload-time = "2026-05-19T10:08:46.486Z" },
+    { url = "https://files.pythonhosted.org/packages/64/5e/6d1bda880723aae0ad86b4b763f044362448efe31e3e819635d41cb03451/jiter-0.15.0-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:813dfbb17d65328bf86e5f0905dd277ba2265d3ca20556e86c0c7035b7182e5a", size = 548868, upload-time = "2026-05-19T10:08:48.026Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/72/7de501cf38dcacaf35098796f3a50e0f2e338baba18a58946c618544b809/jiter-0.15.0-cp314-cp314-win32.whl", hash = "sha256:50e51156192722a9c58db112837d3f8ef96fb3c5ecc14e95f409134b08b158ec", size = 206380, upload-time = "2026-05-19T10:08:49.738Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/a9/e19addf4b0c1bdce52c6da12351e6bc42c340c45e7c09e2158e46d293ccc/jiter-0.15.0-cp314-cp314-win_amd64.whl", hash = "sha256:30ce1a5d16b5641dc935d50ef775af6a0871e3d14ab05d6fc54dff371b78e558", size = 197687, upload-time = "2026-05-19T10:08:51.088Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/c9/776b1db01db25fc6c1d58d1979a37b0a9fe787e5f5b1d062d2eaacb77923/jiter-0.15.0-cp314-cp314-win_arm64.whl", hash = "sha256:510c8b3c17a0ed9ac69850c0438dada3c9b82d9c4d589fcb62002a5a9cf3a866", size = 192571, upload-time = "2026-05-19T10:08:52.451Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/f6/45bb4670bacf300fd2c7abadbfb3af376e5f1b6ae75fd9bc069891d15870/jiter-0.15.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7553333dd0930c104a5a0db8df72bf7219fe663d731383b576bb6ed6351c984d", size = 317151, upload-time = "2026-05-19T10:08:53.867Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/68/ed635ad5acd7b73e454283083bbb7c8205ad10e88b0d9d7d793b09fe8226/jiter-0.15.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f2143ab06181d2b029eedcb6af3cebe95f11bbac62441781860f98ee9330a6a6", size = 341243, upload-time = "2026-05-19T10:08:55.383Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/db/3ff4176b817b8ea33879e71e13d8bc2b0d481a7ed3fe9e080f333d415c16/jiter-0.15.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:6eac374c5c975709b69c10f09afd199df74150172156ad10c8d4fd785b7da995", size = 363629, upload-time = "2026-05-19T10:08:56.928Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/24/5f8270e0ba9c883582f96f722f8a0b58015c7ce1f8c6d4571cf394e99b6b/jiter-0.15.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b3b3b775e33d3bfaec9899edc526ae97b0da0bf9d071a46124ba419149a414f8", size = 456198, upload-time = "2026-05-19T10:08:58.618Z" },
+    { url = "https://files.pythonhosted.org/packages/45/5b/76fc02b0b5c54c3d18c60653156e2f76fde1816f9b4722db68d6ee2c897e/jiter-0.15.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:eda3071db3346334beae1360b46da4606da57bf3528c167b3c38533afaf9f2c5", size = 373710, upload-time = "2026-05-19T10:09:00.151Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/52/4310821b0ea9277994d3e1f49fc6a4b34e4800caebacb2c0af81da59a454/jiter-0.15.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c6694a173ecabc12eb60efbc0b474464ead1951ff65cd8b1e72100715c64512b", size = 349901, upload-time = "2026-05-19T10:09:01.621Z" },
+    { url = "https://files.pythonhosted.org/packages/93/fe/67648c35b3594fba8854ac64cc8a826d8bcd18324bbdb53d77697c60b6ef/jiter-0.15.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:a254e10b593624d230c365b6d616b22ca0ad65e63a16e6631c2b3466022e6ba8", size = 352438, upload-time = "2026-05-19T10:09:03.216Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/28/0a1879d07ad6b3e025a2750027363452ced93c2d16d1c9d4b153ffd51c91/jiter-0.15.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d8d2955167274e15d79a7a020afdd9b39c990eb80b2d89fca695d92dcfdd38ec", size = 388152, upload-time = "2026-05-19T10:09:04.741Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/78/46c6f6b56ba85c90021f4afd72ed42f691f8f84daacb5fe27277070e3858/jiter-0.15.0-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:acf4ee4d1fc55917239fe72972fb292dd773055d05eb040d36f4326e02cc2c0e", size = 517707, upload-time = "2026-05-19T10:09:06.231Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/cb/720662d4c88fcad606e826fef5424365527ba43ce4868a479aed8f8c507e/jiter-0.15.0-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:e7196e56f1cd69af1dbb07dff02dcfb260a50b45a82d409d92a06fedb32473b5", size = 548241, upload-time = "2026-05-19T10:09:08.093Z" },
+    { url = "https://files.pythonhosted.org/packages/60/e3/935b8034fd143f21125c87d51404a9e0e1449186a494405721ff5d1d695e/jiter-0.15.0-cp314-cp314t-win32.whl", hash = "sha256:7f6163c0f10b055245f814dcc59f4818da60dfe72f3e72ab89fc24b6bd5e9c52", size = 207950, upload-time = "2026-05-19T10:09:09.616Z" },
+    { url = "https://files.pythonhosted.org/packages/93/59/984fd9ece895953dad3e0880a650e766f5a2da2c5514f0eafdaaabbeb5f9/jiter-0.15.0-cp314-cp314t-win_amd64.whl", hash = "sha256:980c256edb05b78a111b99c4de3b1d32e31634b867fd1fc2cf726e7b7bba9854", size = 200055, upload-time = "2026-05-19T10:09:11.367Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/a4/cf8d779feb133a27a2e3bc833bccb9e13aa332cdf820497ebf72c10ce8c3/jiter-0.15.0-cp314-cp314t-win_arm64.whl", hash = "sha256:66b1880df2d01e206e8339769d1c7c1753bcb653efd6289e203f6f24ebada0c0", size = 191244, upload-time = "2026-05-19T10:09:12.74Z" },
+]
+
 [[package]]
 name = "jmespath"
 version = "1.1.0"
@@ -458,6 +549,25 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/70/bc/6f1c2f612465f5fa89b95bead1f44dcb607670fd42891d8fdcd5d039f4f4/markupsafe-3.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa", size = 14146, upload-time = "2025-09-27T18:37:28.327Z" },
 ]
 
+[[package]]
+name = "openai"
+version = "2.41.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "distro" },
+    { name = "httpx" },
+    { name = "jiter" },
+    { name = "pydantic" },
+    { name = "sniffio" },
+    { name = "tqdm" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/3c/a6/5815fe2e2aca74b36c650d1bd43b69827cee568073d0d2d9b6fc5aaac80c/openai-2.41.0.tar.gz", hash = "sha256:db5c362acd6604b84f076abbefa66826ea4b46ecba2954ed866e6a149a1352c0", size = 783525, upload-time = "2026-06-03T22:39:40.719Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/be/51/d82bb424e8aa372190c5233253a2ceb399a778747d18b42cff487411e663/openai-2.41.0-py3-none-any.whl", hash = "sha256:20cc7952e8501c7e5773dd2ef7be437bae9cb549044902e1041a83a54516e375", size = 1353378, upload-time = "2026-06-03T22:39:38.964Z" },
+]
+
 [[package]]
 name = "packaging"
 version = "26.2"
@@ -482,10 +592,12 @@ version = "0.0.0"
 source = { virtual = "." }
 dependencies = [
     { name = "alembic" },
+    { name = "anthropic" },
     { name = "argon2-cffi" },
     { name = "asyncpg" },
     { name = "boto3" },
     { name = "fastapi" },
+    { name = "openai" },
     { name = "pydantic" },
     { name = "pydantic-settings" },
     { name = "python-multipart" },
@@ -504,10 +616,12 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "alembic", specifier = ">=1.14" },
+    { name = "anthropic", specifier = ">=0.108.0" },
     { name = "argon2-cffi", specifier = ">=23.1" },
     { name = "asyncpg", specifier = ">=0.30" },
     { name = "boto3", specifier = ">=1.35" },
     { name = "fastapi", specifier = ">=0.115" },
+    { name = "openai", specifier = ">=2.41.0" },
     { name = "pydantic", specifier = ">=2.9" },
     { name = "pydantic-settings", specifier = ">=2.5" },
     { name = "python-multipart", specifier = ">=0.0.12" },
@@ -766,6 +880,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
 ]
 
+[[package]]
+name = "sniffio"
+version = "1.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a2/87/a6771e1546d97e7e041b6ae58d80074f81b7d5121207425c964ddf5cfdbd/sniffio-1.3.1.tar.gz", hash = "sha256:f4324edc670a0f49750a81b895f35c3adb843cca46f0530f79fc1babb23789dc", size = 20372, upload-time = "2024-02-25T23:20:04.057Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" },
+]
+
 [[package]]
 name = "sqlalchemy"
 version = "2.0.50"
@@ -817,6 +940,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1c/54/196d0c1db10af76baa4f64894448505d60d3cdf70ef92cbb35f46a4e4c71/starlette-1.2.1-py3-none-any.whl", hash = "sha256:4de0082d08c8f6764a85a54cf1120d6939507a19905c7768acad2a9f875d2b89", size = 73350, upload-time = "2026-05-31T01:07:50.09Z" },
 ]
 
+[[package]]
+name = "tqdm"
+version = "4.68.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/85/05/0d5260f1f1ca784f4a4a0def9cbe6affe587f5b4025328d446c3d67765f4/tqdm-4.68.2.tar.gz", hash = "sha256:89c230e8dbc67c7615c142487111222f878c77427ea09549960f62389e258add", size = 171923, upload-time = "2026-06-09T13:26:42.539Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/eb/75/1a0392bcc21c44dcdf87b3cf2d137e7829be2c083a1e38d44efca3d57a16/tqdm-4.68.2-py3-none-any.whl", hash = "sha256:d4240441fb5353290b87d6a85968c9decc131a99b8c7faa28269d829de669ede", size = 78578, upload-time = "2026-06-09T13:26:40.731Z" },
+]
+
 [[package]]
 name = "typing-extensions"
 version = "4.15.0"

deploy/.env.example

@@ -46,6 +46,9 @@ COOKIE_SECURE=false
 APP_BASE_URL=http://localhost
 # Mailer: 'console' logs links to stdout (dev); 'smtp' uses the SMTP settings below.
 MAILER=console
+# Require a verified email before an account has an active session. Leave false
+# until SMTP works and existing accounts are verified, or you will lock users out.
+REQUIRE_EMAIL_VERIFICATION=false
 
 # --- Email (SMTP) — wired in a later phase ---
 SMTP_HOST=
@@ -54,7 +57,34 @@ SMTP_USERNAME=
 SMTP_PASSWORD=
 SMTP_FROM=
 
-# --- Model providers — wired in Phase 4 (AI assistant). BYO key. ---
-# ANTHROPIC_API_KEY=
-# OPENAI_API_KEY=
+# --- Model providers (AI assistant + embeddings) -----------------------------
+# Configure as many as you like — each turns on when its key is set. The
+# default_* vars pick which one is used by default; the app can also select any
+# configured provider by name. LLM and embeddings are independent (Anthropic has
+# no embeddings endpoint). Leave the defaults 'null' to keep AI off.
+DEFAULT_LLM_PROVIDER=null          # null | anthropic | openai | xai | ollama
+DEFAULT_EMBEDDING_PROVIDER=null    # null | openai | ollama
+LLM_MAX_TOKENS=4096
+EMBEDDING_DIMENSIONS=1536          # must match the embedding model + pgvector column
+
+# Anthropic (LLM)
+ANTHROPIC_API_KEY=
+ANTHROPIC_MODEL=claude-opus-4-8
+
+# OpenAI (LLM + embeddings)
+OPENAI_API_KEY=
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPENAI_MODEL=gpt-4o
+OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+
+# xAI / Grok — OpenAI-compatible (LLM)
+XAI_API_KEY=
+XAI_BASE_URL=https://api.x.ai/v1
+XAI_MODEL=grok-2-latest            # set to your account's current Grok model
+
+# Ollama — local, OpenAI-compatible, no key (LLM + embeddings)
+OLLAMA_ENABLED=false
+OLLAMA_BASE_URL=http://localhost:11434/v1
+OLLAMA_MODEL=llama3.1
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text
 # XAI_API_KEY=

deploy/BACKUP.md

@@ -0,0 +1,55 @@
+# Backup & restore
+
+`backup.sh` produces a single bundle containing the Postgres database and the
+MinIO object store. Run it from this `deploy/` directory on the host that runs
+the stack.
+
+## Back up
+
+```bash
+./backup.sh
+# → backups/provenance-backup-20260609T140000Z.tar
+```
+
+The bundle contains:
+
+- `db.sql.gz` — `pg_dump --clean --if-exists` of the database, gzipped.
+- `minio-data.tar.gz` — the MinIO `/data` directory (objects + bucket metadata).
+- `MANIFEST.txt` — what's inside and when it was made.
+
+Optional retention: `BACKUP_RETAIN_DAYS=30 ./backup.sh` also deletes bundles
+older than 30 days. Schedule it from cron for off-box copies, e.g.:
+
+```cron
+15 3 * * *  cd /path/to/provenance/deploy && BACKUP_RETAIN_DAYS=30 ./backup.sh
+```
+
+(Copy the resulting bundle off the host — a backup on the same disk isn't one.)
+
+## Restore
+
+Restoring overwrites live data — stop the app first.
+
+```bash
+ts=20260609T140000Z                      # the bundle you're restoring
+mkdir -p /tmp/restore && tar xf backups/provenance-backup-$ts.tar -C /tmp/restore
+
+# 1. Database — the dump is --clean, so it drops & recreates objects.
+docker compose stop backend worker
+gunzip -c /tmp/restore/db.sql.gz \
+  | docker compose exec -T postgres psql -U "${POSTGRES_USER:-provenance}" -d "${POSTGRES_DB:-provenance}"
+
+# 2. Objects — replace the MinIO data directory.
+docker compose stop minio
+docker compose run --rm --no-deps -T -v provenance_miniodata:/data minio \
+  sh -c 'rm -rf /data/* && tar xzf - -C /data' < /tmp/restore/minio-data.tar.gz
+docker compose up -d
+
+rm -rf /tmp/restore
+```
+
+Notes:
+- The MinIO `/data` archive is filesystem-level; restore into the **same** MinIO
+  major version it was taken from.
+- Verify the volume name (`docker volume ls | grep miniodata`) — compose prefixes
+  it with the project name; adjust the `-v` mount accordingly.

deploy/backup.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+#
+# One-command backup of a Provenance deployment: the Postgres database and the
+# MinIO object store, into a single timestamped bundle under ./backups/.
+#
+#   ./backup.sh                 # write backups/provenance-backup-<UTC>.tar
+#   BACKUP_RETAIN_DAYS=30 ./backup.sh   # also prune bundles older than 30 days
+#
+# Run it from the host where `docker compose` manages the stack (i.e. this
+# deploy/ directory). Restore steps are in BACKUP.md.
+set -euo pipefail
+
+cd "$(dirname "$0")"  # the deploy/ directory (where docker-compose.yml lives)
+
+# Config comes from the compose .env (same file the stack uses); fall back to
+# the compose defaults so a vanilla stack still backs up.
+if [ -f .env ]; then set -a; . ./.env; set +a; fi
+PGUSER="${POSTGRES_USER:-provenance}"
+PGDB="${POSTGRES_DB:-provenance}"
+
+dc() { docker compose "$@"; }
+
+ts="$(date -u +%Y%m%dT%H%M%SZ)"
+work="backups/.work-$ts"
+mkdir -p "$work" backups
+
+cleanup() { rm -rf "$work"; }
+trap cleanup EXIT
+
+echo "→ Dumping Postgres database '$PGDB'…"
+dc exec -T postgres pg_dump -U "$PGUSER" -d "$PGDB" --no-owner --clean --if-exists \
+  | gzip > "$work/db.sql.gz"
+
+echo "→ Archiving MinIO object store…"
+# Tar MinIO's data directory straight from the container (objects + bucket
+# metadata). Restored by extracting back into the miniodata volume.
+dc exec -T minio tar czf - -C /data . > "$work/minio-data.tar.gz"
+
+cat > "$work/MANIFEST.txt" <<EOF
+Provenance backup
+created:   $ts
+database:  $PGDB  (pg_dump --clean --if-exists, gzip)
+objects:   MinIO /data (tar.gz)
+restore:   see deploy/BACKUP.md
+EOF
+
+bundle="backups/provenance-backup-$ts.tar"
+# Contents are already gzipped, so the outer archive is a plain tar.
+tar cf "$bundle" -C "$work" db.sql.gz minio-data.tar.gz MANIFEST.txt
+
+echo "✓ Backup written: $bundle ($(du -h "$bundle" | cut -f1))"
+
+if [ -n "${BACKUP_RETAIN_DAYS:-}" ]; then
+  echo "→ Pruning bundles older than ${BACKUP_RETAIN_DAYS} days…"
+  find backups -maxdepth 1 -name 'provenance-backup-*.tar' -type f \
+    -mtime "+${BACKUP_RETAIN_DAYS}" -print -delete
+fi

deploy/docker-compose.yml

@@ -40,12 +40,36 @@ services:
       retries: 10
     restart: unless-stopped
 
+  # One-shot schema migration: runs `alembic upgrade head` and exits. Backend
+  # and worker wait for it to finish, so on `docker compose up` the schema is
+  # always current before the app serves traffic — no manual migrate step.
+  # NOTE: a pure Watchtower image-swap recreates only the long-running
+  # containers, not this one-shot job, so Watchtower deploys should be paired
+  # with a `compose up` (see deploy docs) to re-run migrations.
+  migrate:
+    image: git.jpaul.io/justin/provenance-backend:${IMAGE_TAG:-test-main}
+    command: ["uv", "run", "--no-dev", "alembic", "upgrade", "head"]
+    labels:
+      com.centurylinklabs.watchtower.enable: "true"
+    environment:
+      APP_ENV: ${APP_ENV:-development}
+      DATABASE_URL: ${DATABASE_URL:-postgresql+asyncpg://provenance:provenance@postgres:5432/provenance}
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: "no"
+
   backend:
     image: git.jpaul.io/justin/provenance-backend:${IMAGE_TAG:-test-main}
     labels:
       com.centurylinklabs.watchtower.enable: "true"
     environment:
       APP_ENV: ${APP_ENV:-development}
+      # Self-migrate on start so a Watchtower in-place image swap applies any new
+      # migrations (idempotent). The one-shot `migrate` service covers the same
+      # for `compose up`; the depends_on below serializes them so they never run
+      # alembic concurrently.
+      RUN_MIGRATIONS: "1"
       DATABASE_URL: ${DATABASE_URL:-postgresql+asyncpg://provenance:provenance@postgres:5432/provenance}
       S3_ENDPOINT_URL: ${S3_ENDPOINT_URL:-http://minio:9000}
       S3_BUCKET: ${S3_BUCKET:-provenance}
@@ -57,6 +81,8 @@ services:
         condition: service_healthy
       minio:
         condition: service_healthy
+      migrate:
+        condition: service_completed_successfully
     healthcheck:
       test:
         - CMD-SHELL
@@ -89,6 +115,8 @@ services:
         condition: service_healthy
       minio:
         condition: service_healthy
+      migrate:
+        condition: service_completed_successfully
     restart: unless-stopped
 
   frontend:

docs/BACKLOG.md

@@ -0,0 +1,434 @@
+<!-- Generated by the genealogy-feature-gap-backlog workflow on 2026-06-09. -->
+<!-- Gap analysis vs commercial (Ancestry/MyHeritage/FamilySearch) and OSS
+     (GRAMPS/Gramps Web/webtrees) genealogy software, verified against the
+     codebase. Statuses reflect the repo at workflow launch (before the
+     tree-visibility phases 1-3 landed; some items are now closed). -->
+
+# Provenance — Product Backlog
+
+> Status legend: **Have** (shipped) · **Partial** (substrate exists, surface incomplete) · **Planned** (on roadmap, no code) · **Missing** (no code, off roadmap).
+> Importance: Critical / High / Medium / Low. Effort: S / M / L / XL.
+> Phase references map onto the existing 0–9 roadmap. "NN#" = non-negotiable invariant.
+
+---
+
+## 1. Executive summary
+
+**Where Provenance is strong today.** The foundation is genuinely solid and, in several places, ahead of the OSS field:
+
+- **Sources-first spine is real.** A reusable `Source` + per-fact `Citation` two-tier model with a `exactly_one_target` CHECK constraint, confidence enum, and full backend CRUD. This is the architectural thing webtrees/Gramps get right and most commercial tools bury. (Caveat: citations are silently dropped on GEDCOM *export* — see below.)
+- **Privacy architecture is the right shape.** A single `privacy.py` engine, `TenantScoped` mixin on every row, living-person heuristic (`is_possibly_living`, unknown-birth-treated-as-living), and media served **through the backend rather than via raw S3 URLs**. The *shape* is correct; coverage is not yet complete (the media endpoint and several child resources don't yet apply `person_visibility` — see §2.4, §2.10).
+- **Non-destructive by design.** Soft-delete with timed purge worker, immutable `AuditEntry` (before/after JSONB, `actor_type` ready for the assistant), GEDCOM merge that copies rather than overwrites, full account export/import.
+- **Modeling maturity.** Typed parent/child qualifiers (biological/adoptive/step/foster/donor/guardian), typed alternate names with one-primary invariant, dual verbatim+normalized dates, duplicate-relationship guards, UUID surrogate keys.
+- **Standards core.** GEDCOM 5.5.1 import/export is **functional** (with preview/merge-vs-create resolution UI), pg_trgm fuzzy name search, multi-tenant tree hosting with visibility tiers. Round-trip *fidelity* has four tracked gaps (citation links, custom tags, PLAC coords/hierarchy, non-UTF-8 encoding) — see §2.11.
+
+**Documentation-vs-code gaps to correct now (per "docs travel with code").** Three repo claims are not yet true and should be edited in the same spirit they were written:
+
+- **ChangeProposal is documented as landed but does not exist.** CLAUDE.md states the core data model (ARCHITECTURE §5) landed / "Phase 0 complete," but `ChangeProposal` — part of §5 and the load-bearing AI invariant — has no model, migration, or schema. Either scope it out of the "landed" claim or build it; don't leave the docs asserting it.
+- **pgvector is claimed as used; it is not.** Only `pg_trgm` is created. ARCHITECTURE references pgvector for match ranking.
+- **i18n "from day one" is documented but unmet.** PRD §6 promises externalized strings; every label is a hardcoded literal.
+
+These three doc edits are themselves trivial quick wins (see §3).
+
+**The biggest gaps vs commercial (Ancestry / MyHeritage / FamilySearch).** Provenance is not trying to be a record provider, and correctly so — but it is missing several things mainstream users treat as table stakes:
+
+- **No record hints, no "save to tree," no connector framework.** The entire SourceConnector layer (FamilySearch/Find A Grave/WikiTree) is unbuilt — this gates AI search, hints, and auto-citation.
+- **No person merge outside GEDCOM import.** Merging duplicate people is fundamental hygiene and is currently impossible in-tree — the single highest-value near-term matching gap.
+- **No maps at all.** No place autocomplete, no geocoding, no interactive/migration/birthplace maps — a glaring hole for an app whose thesis is *family **and** land*.
+- **No report/print/PDF output.** Charts render on-screen only; there is no Ahnentafel, family group sheet, narrative report, or any PDF/SVG/HTML export. The whole "Charts, reports & printing" category is on-screen-viewing only.
+- **DNA absent** (deliberately parked — treat as open question, not a gap).
+
+**The biggest gaps vs OSS (GRAMPS / Gramps Web / webtrees).** These are where a privacy-first self-host product is expected to compete and currently trails:
+
+- **Collaboration is plumbed but unreachable.** `TreeMembership` roles are enforced on every read/write, but there is **no API or UI to invite, grant, change, or revoke** a member — the tree is effectively single-user despite multi-user infrastructure. This also breaks the full-CRUD invariant (NN#8) and, because importance and the old Phase-6 schedule disagree, a minimal management slice is pulled forward (§2.9).
+- **Living-person redaction is non-uniform.** Redaction is applied on person reads but **not** on the event/media/name/relationship/citation/source child-resource endpoints — a real PII leak on public/unlisted trees (NN#3, NN#2).
+- **`site_members` visibility tier is silently broken** (defined, selectable in UI, never handled in `can_view_tree`).
+- **No place as a usable first-class entity** (model exists, created by GEDCOM, but no read/edit/delete — a create-only entity, which is a bug per NN#8).
+- **No research log, to-do/task planner, kinship calculator, data-quality checker, or i18n/string externalization** (the last is a documented day-one commitment that is currently unmet).
+
+**Security-priority correctness fixes (do these first, regardless of phase).** Three current defects are user-harm or trust issues, not roadmap items:
+
+1. **Media privacy leak (§2.4)** — `list_media`/`get_media`/`media_content` gate on `can_view_tree` but never `person_visibility`; non-owners can download photos of redacted living people on public/unlisted trees.
+2. **Child-resource redaction gap (§2.10)** — event/media/name/relationship/citation/source endpoints don't apply living-person redaction.
+3. **Registration issues a live session before verification (§2.10)** — `register` returns an authenticated session cookie + token (201) and `email_verified_at` is written but never read on any path; there is no env switch to gate self-registration. The *enforcement check* (read-side `email_verified_at`) is small; the approval-mode env switch is the larger piece.
+
+**Strategic posture.** The differentiators worth pressing — property chain-of-title, the ChangeProposal AI model, the anonymous mutual-consent hint system, and true self-host data ownership — are mostly still ahead on the roadmap. The near-term job is (a) close the **privacy/auth correctness** and **collaboration** gaps that the architecture already implies, (b) ship the **maps + reports + merge** table stakes, and (c) build the **connector/ModelProvider/ChangeProposal** spine that unlocks the entire back half of the roadmap.
+
+---
+
+## 2. Backlog by category
+
+### 2.1 Tree & data model
+
+Core CRUD, typed relationships, dates, soft-delete, and naming are **have**. Remaining work is about reusable sub-entities, shared/event-centric modeling, and research-grade conveniences.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| Repository as first-class entity | Promote `Source.repository` string to a reusable `Repository` (name/address/call-numbers) with dedup. | Partial | Med | M | 1–2 | If promoted, full CRUD in API+UI (NN#8) — don't half-build. |
+| Note as first-class entity (SNOTE) | Promote inline `notes` text fields to reusable shared `Note`/SNOTE records. | Missing | Low | M | 2 | Full CRUD; GEDCOM 7 round-trip parity. |
+| Shared/event-centric model + witnesses | Remove the `subject_person_xor_relationship` XOR; add participant/role join so one event has many people (FAN/cluster research). | Missing | Med | M | later | Unlocks FAN club + richer sourcing; participants must redact via privacy engine. |
+| Non-family associations (FAN) | Add associate/neighbor relationship types; best delivered with shared-event participants. | Missing | Low | M | later | — |
+| Relationship-status enum | Add married/divorced/annulled status on partnership rather than inferring from events. | Partial | High | M | 1–2 | — |
+| Family/couple unit (GEDCOM FAM) | Persist a true FAM entity (own ID/sources, childless couples) instead of rebuilding on export. | Partial | High | L | 2 | Improves GEDCOM fidelity. |
+| Kinship / relationship calculator | "How is A related to B" path + cousinship. Graph edges already exist. | Missing | High | M | 1–2 | Self-contained; reads via privacy engine. |
+| **Read-only audit-log viewer / activity feed** | Surface `AuditEntry` as a per-tree/per-person change feed. Smaller and higher-leverage than value-level undo; partially satisfies NN#8's "read" for AuditEntry and is the substrate for watch/follow + webhooks. | Missing | High | M | 2 | Privacy-filtered projections only — never raw before/after JSON to non-members (NN#2/#3). |
+| Per-field revision history + restore-prior-value | Value-level history view + undo, built atop the audit feed above. | Partial | High | L | 6 | Audit-log *UI* is the feed item; this is the larger value-level-undo work (NN#8 correction ethos). |
+| Color-coded tags & custom labels | Tag people for lineages/research-status/grouping. | Missing | Med | M | 2 | Full CRUD; tenant-scoped. |
+| Person timeline / LifeStory | Sort the merged event list; add place/age enrichment + narrative presentation. | Partial | Med | M | 2 | Sort is trivial (`localeCompare` on `date_start`); narrative is the larger piece. |
+| Multi-calendar normalization | Store + parse Julian/Hebrew/French Republican (only `calendar` tag stored today, only Gregorian normalized). | Partial | Low | M | 2 | See also Localization §2.17. |
+| Evidence/persona vs conclusion model | GEDCOM-X persona layer separate from conclusion person. | Missing | Med | XL | later | Large modeling change; strengthens sourcing + hint matching. |
+| Negative assertions | Boolean "event did not happen" on Event. | Missing | Low | S | 2 | Cheap interop nicety. |
+| Custom groups / networks | Named manual or rules-based groupings. | Missing | Low | M | later | Lower priority than tags. |
+| Raw GEDCOM record editor / configurable fact tabs | webtrees-style raw editor + fact-type registry. | Partial | Med | L | later | Open vocabularies give de-facto custom facts today. |
+| Health/medical, historical-facts index, LDS ordinances | Niche entities. | Missing | Low | M–L | later | LDS BAPL/ENDL/SLGS should map to distinct types if ever pursued; medical is special-category PII. |
+
+---
+
+### 2.2 Sources & citations
+
+The two-tier model is **have** and production-grade on the backend. The gaps are almost all UI/CRUD-completeness and the connector-dependent "save to tree" flows.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| Citation confidence selector in UI | Confidence enum is modeled + API-writable but the `citeControl` form never sets it — every UI citation is NULL confidence. | Partial | High | S | 1 | **Quick win.** Full CRUD in UI (NN#8); reinforces evidence-quality thesis. |
+| Source edit UI + all 8 fields | Source UI is add/list/delete only and create exposes ~3 of 8 fields (no author/source_type/publication_info/quality_note/citation_text). | Partial | High | S | 1 | Update API exists but no edit form — violates NN#8. |
+| `GET /{tree}/citations/{id}` | Citation API has list but no single-read endpoint. | Partial | Med | S | 1 | API symmetry (NN#8). |
+| Transcription / abstract / extract fields | Add `transcription_text` + `abstract_text` to Source; don't conflate with `citation_text` (GEDCOM SOUR.TEXT currently dumped into citation_text). | Missing | Med | S | 1–2 | **Quick win.** Central to evidence analysis; full CRUD (NN#8). |
+| Evidence-Explained guided citation builder | Structured fields → formatted citation (Chicago/MLA/APA) instead of hand-typed `citation_text`. | Missing | High | L | 2 | Signature provenance feature; citation_text should be generated, not typed. |
+| Citations on OwnershipEvents | Add `ownership_event_id` to Citation + extend CHECK to 5 targets when property lands. | Partial | Critical | S | 3 | **Quick win once Property exists** — single FK + constraint edit (NN#5). |
+| Record-to-source attachment ("save to tree") | Search a connector record and attach its facts. | Missing | High | XL | 4 | Gated on connector framework; assistant attach must emit ChangeProposal (NN#1); legal sources only (NN#6). |
+| Source Linker (one record → many persons) | Bulk-attach a record's facts across people. | Missing | Med | L | 4 | Downstream of connectors; reads/writes via service layer. |
+| Auto-citation on save/match | Generate citation when a hint/record is confirmed. | Missing | Med | L | 4/7 | Blocked on connectors + hints; ChangeProposal if assistant-driven. |
+| Memories-as-sources (cite a photo directly) | Allow media to be a citation target, not only attachable to a Source. | Partial | Low | M | 2 | Reads stay on privacy-checked media endpoint (NN#2). |
+| GPS / Proof-Standard reasoning artifact | Container linking sources/citations into a proof narrative reconciling conflicts. | Missing | Med | L | later | Serious-researcher differentiator; full CRUD (NN#8). |
+| Proprietary record collections | 1921 census, UK sets, etc. | Missing | Low | XL | — | **Out of scope** — conflicts with NN#6 / self-host. Do not pursue. |
+
+---
+
+### 2.3 Search & matching
+
+Fuzzy trigram name search is **have**; everything that depends on connectors, embeddings, or multiple populated trees is planned/missing. The standout near-term gap is **in-tree person merge**.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| Standalone duplicate detection | Lift the GEDCOM `_best_match` logic into a "find duplicates in my tree" scan. | Partial | High | M | 2 | Logic already written; results via privacy engine (NN#2). |
+| Interactive two-person merge (side-by-side, field-select, undo) | General merge of duplicate persons with citation re-pointing — impossible outside import today. | Partial | High | L | 2 | **Highest-value matching gap.** Preserve + re-point Citations (NN#5); write-once is a bug (NN#8). |
+| Advanced search (wildcards, boolean, date/place facets, sort) | Search exposes only `?q`. | Partial | High | M | 2 | Keep per-person privacy filter in the search loop (NN#2). |
+| Phonetic matching (Soundex/Metaphone/DM) | Enable `fuzzystrmatch`; trigram is char-similarity, not phonetic. | Partial | High | M | 2 | Pure utility. |
+| Semantic / vector search (pgvector) | **Docs claim pgvector is used; it is not** — only pg_trgm extension is created. Add `CREATE EXTENSION vector` + embedding columns (and correct the docs). | Missing | Med | L | 7 | Embedding provider is an open question (PRD §11) — don't pick silently; candidates via privacy engine. |
+| Tree-to-tree matching (Smart Matches) | Cross-tree candidate generation + ranking. | Planned | High | XL | 7 | Anonymous until mutual consent (NN#4); living-person protection (NN#3). |
+| Mutual-consent match notification | Anonymous notification, reveal only after both opt in. | Planned | High | L | 7 | **Mandated invariant**, not a toggle (NN#4, NN#3); rides the notification substrate (§2.9). |
+| Match confirm/reject + "not a match" memory | Persistent rejected-match store (today scoring lives only inside import). | Partial | High | M | 7 | Prevents re-notifying once hints land. |
+| External search deep-links | Pre-fill FamilySearch/Find A Grave/BLM-GLO search URLs from a person's name/dates/place. | Missing | Med | M | 2–4 | **High value, low risk** before full connectors; legal targets only (NN#6). |
+| **Automated record hints** | Proactive per-person record suggestions from connectors — a marquee mainstream feature. | Missing | High | XL | 7 | Connector-gated (NN#6); surfaced anonymously where cross-tree (NN#4); attach via ChangeProposal (NN#1). |
+| Jurisdiction-aware record-search hints | Map place/jurisdiction → relevant collections. Place hierarchy is a ready foundation. | Missing | Med | L | 8 | Suggested collections must be legal (NN#6). |
+| Cross-language / transliteration matching | Cyrillic/Hebrew/CJK ↔ Latin. | Missing | Med | XL | later | See Localization. |
+| Record Detective, newspaper matches, collection catalog, GQL query builder, OCR full-text search | Connector/record-layer dependent. | Missing/Planned | Low–Med | L–XL | 4/7/8 | All gated on the connector framework; any query path runs through privacy engine (NN#2). |
+
+---
+
+### 2.4 Media & documents
+
+Universal media attachment is **have**, but with a **confirmed privacy leak** and no asset-processing pipeline.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| **Media privacy gating on serve paths** | `list_media`/`get_media`/`media_content` gate only on `can_view_tree`, never `person_visibility` — a non-owner can download photos of redacted living people on public/unlisted trees. | Have(leaky) | **Critical** | M | 1 | **Security-priority — fix first. Direct NN#3/NN#2 violation.** Check attached `person_id` visibility and redact/hide. |
+| EXIF / GPS stripping on upload | Raw bytes stored verbatim; family photos leak GPS/home addresses/timestamps. | Planned | High | M | 1 | **Security-priority**, not cosmetic. Parse EXIF on ingest, strip/quarantine by default, allow override. |
+| Thumbnail / preview generation | No image pipeline (no Pillow). Async, idempotent worker job. | Planned | High | L | 1 | Derived thumbnail must inherit parent privacy — no bypass path. |
+| Image reference regions | Mark the rectangle of a census image that supports a Citation. | Missing | Med | M | later | Tenant-scoped, full CRUD; region→Citation preferred over region→Person. |
+| Photo/face tagging (manual) | Multi-person tagging via single FK today. | Missing | Med | XL(ML)/M(manual) | later | Owner-only, in-deployment; face tags inherit redaction (NN#3); full CRUD. |
+| Mobile photo scanning + auto-split | Shoebox digitization. | Missing | Med | L | later | Reuse privacy-gated upload + EXIF strip. |
+| AI photo dating / colorize / restore / animate / narrate | Model-driven media features. | Missing | Low | L–XL | 4+ | Must route through ModelProvider (NN#7), require approval (NN#1), preserve original; animating living faces raises consent issues. |
+| British Library / paywalled archives, pay-per-view credits | Licensed content + metering. | Missing | Low | XL | — | **Out of scope** — conflicts with NN#6 and the self-host model. |
+
+---
+
+### 2.5 DNA & genetic genealogy
+
+DNA is an **explicit PRD non-goal / open question** — treat as parked, not a backlog to grind through. Across every DNA row the rule is uniform: **a user uploading their own export is permissible; vendor connectors/scrapers (23andMe / Ancestry / MyHeritage / GEDmatch) are barred (NN#6).** Kits and matches are living-tester PII and route through the privacy engine.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| DNA-confirmed relationship flag | Model DNA confirmation as a Source/Citation backing a Relationship (not free text). | Missing | Med | M | parked | Best sources-first fit (NN#5); full CRUD (NN#8). |
+| Raw DNA upload (own file) | User uploads own export; no vendor scraping. | Missing | Med | L | parked | User's own file is fine; vendor connectors barred (NN#6); special-category PII via privacy engine. |
+| Kit/Match entities linked to persons | Kit (tester) + Match tied to Person, tenant-scoped/audited. | Missing | Med | M | parked | Kits = living-tester PII (NN#2/#3); full CRUD (NN#8). |
+| Autosomal match list, segments, chromosome browser, triangulation, ThruLines/AutoTree, ethnicity/admixture, haplogroups, GEDmatch, NPE detection | Full genetic-genealogy suite. | Missing | Low–Med | L–XL | parked | DNA scope is an unresolved open question — **surface the dependency, don't build speculatively.** Own-data only (NN#6); cross-user surfacing obeys NN#4. |
+
+---
+
+### 2.6 Maps, places & gazetteers
+
+This category is almost entirely **missing** despite being half the product thesis. The Place model has the right bones (parent_id, lat/long, PlaceName with date ranges) but no API/UI and no maps.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| **Place as usable first-class entity** | Place rows are created by GEDCOM but have **no read/edit/delete** API or UI — a create-only entity. | Partial | High | M | 2–3 | **Violates NN#8** (create-but-not-edit = bug). Make Place citable too (NN#5). |
+| Place autocomplete + picker in event editor | No `/places` router; the event form has no place input, so users can't attach a place at all. | Missing | High | M | 2 | Table stakes; lookup is low-risk. |
+| Geocoding (manual coords + forward) | lat/long columns exist; no UI, no geocoder. | Partial | High | M | 3 | Provider via env (NN#7), ToS-compliant (NN#6). |
+| Pluggable geocoding provider | Nominatim/GeoNames/Bing/Google swappable. | Missing | Med | L | 3 | Provider+keys via env (NN#7); legal providers only (NN#6). |
+| Bulk/batch geocoding (worker) | Geocode hundreds of GEDCOM-imported places. | Missing | Med | M | 3 | Idempotent, rate-limited worker job; provider via env. |
+| Place merge/split (dedup) | GEDCOM imports produce near-duplicate place strings. | Missing | High | M | 2–3 | Needs Place update/delete (NN#8); audited merges. |
+| Place-name cleanup tools | Extend the existing preview→apply cleanup UX to places. | Missing | Med | M | 2 | Preview-first + audited like existing cleanup. |
+| Standardized-name vs original text | Mirror the verbatim+normalized date pattern for places. | Missing | Med | M | 2–3 | GEDCOM fidelity. |
+| Alternate/historical place names with date ranges | `PlaceName` model exists with valid_from/to but no CRUD and never populated. | Partial | Med | M | 2–3 | Stored entity with no CRUD surface (NN#8). |
+| Interactive map of events & places | No map library in frontend. Core to family+land positioning. | Missing | High | L | 3 | Plot via `person_visibility` so non-owners never see living locations (NN#2/#3). |
+| Migration trail / pedigree-birthplace maps | Per-person life path; ancestor birthplace map. | Missing | Med | L | 3 | Redact living subjects for non-owners (NN#3). |
+| Bundled world gazetteer | Offline GeoNames-style authority. | Missing | Med | XL | later | GeoNames (CC-BY) verify AGPL-compat; env-configurable. |
+| Historical boundary overlays, time slider, heatmaps, radius/nearby, tile-provider switch | Advanced geo. | Missing | Low–Med | S–XL | later | PostGIS is an open question (ARCH §14) — **surface dependency**, don't adopt silently; tiles legal (NN#6). |
+
+---
+
+### 2.7 Charts, reports & printing
+
+On-screen pedigree/descendant/fan/hourglass charts are **have**. The entire **output/print/report** half is missing — this is the linchpin gap of the category.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| **Multi-format export (PDF / SVG / image / HTML)** | No export/print path, no `@media print`, no `window.print()`. Charts and reports can't leave the screen. | Missing | High | L | 2/6 | **Linchpin.** Generate from privacy-filtered data so living people redacted in shared output (NN#3). |
+| Ahnentafel report | Numbered-ancestor report; all data exists. | Missing | High | M | 6 | — |
+| Family group sheet / individual summary | Printable summary; data available, needs print layout. | Missing | High | M | 6 | — |
+| Narrative descendant/ancestor reports | Multi-standard prose with inline sources. | Missing | High | L | 6 | Cite Sources inline (NN#5); redact living (NN#3). |
+| Sentence-template narrative engine | Deterministic fact→prose underpinning reports. | Missing | Med | L | 6 | Keep template-based; report text never mutates tree (NN#1). |
+| Photo boxes in charts | Pass privacy-checked media URLs to `setCardDisplay`; CSS already present. | Missing | High | M | 2 | Stream via privacy-checked /media (NN#2/#3). |
+| Drag-to-edit / interactive chart canvas | Tree canvas renders but interactive node editing (drag to re-parent, inline edit on the chart) is only partly present. | Partial | Med | M | 2 | Edits go through service layer + audit (NN#1); honor redaction. |
+| Statistics dashboard | Surname/place/date distributions + tree-health. | Missing | Med | M | 6 | Reads via privacy engine (NN#2). |
+| Kinship/relationship diagram report | Needs path-finding (see §2.3 calculator) + renderer. | Missing | Med | M | 6 | — |
+| List reports (sources/places/repos/media) | Printable indexes (current screens are management, not reports). | Missing | Med | M | 6 | — |
+| Color-by-lineage, fan overlays, lifespan/timeline charts | Sex-coloring exists; lineage/overlay/timeline don't. | Partial/Missing | Med | M | later | Overlays respect privacy engine. |
+| Book/multi-report compiler, wall-chart tiling, page-setup, customizable charts | Print-shop-grade output. | Missing | Low–Med | L–XL | later | Saved "book" entity = full CRUD (NN#8); honor living-person privacy. |
+| Bowtie/couple-rooted/circular-sun/3D/network/calendar | Niche chart variants. | Missing/Partial | Low–Med | M–L | later | — |
+| Print-shop products, XML template engine, blank forms | Commercial/template extras. | Missing | Low | S–XL | later | Weak fit for self-host. |
+
+---
+
+### 2.8 Research workflow & automation
+
+The preview→approve **bulk cleanup** tool is a genuine **have** and a differentiator. The missing pieces are the serious-researcher workflow entities.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| Data-quality / consistency checker | Extend cleanup beyond name issues: child-before-parent, death-before-birth, implausible ages, orphans, dups; severity tiers. | Partial | High | L | 2 | New auto-fixes keep preview→apply (NN#1). |
+| Research log | Searches, repositories visited, negative results, findings — distinct from the system audit log. | Missing | High | M | 6 | Reference reusable Sources (NN#5); tenant-scoped full CRUD (NN#8). |
+| To-do / research task planner | Tasks on Person/Tree with status/priority/due/assignment. | Missing | High | M | 6 | Full CRUD in API+UI (NN#8). |
+| Source-driven data entry | Start from a Source document and transcribe facts into the tree. | Missing | High | M | 2 | Natural sources-first differentiator (NN#5). |
+| Task↔log linkage | FK + joined view once both entities exist. | Missing | Med | S | 6 | Cheap once predecessors land. |
+| Family chronology / timeline | Sort merged events; family-wide chronology (parents' marriage, siblings' births). | Partial | Med | M | 2 | Sort is trivial; presentation over privacy-filtered data. |
+| Navigation: active person / history / bookmarks | Large trees rely on browser back only. | Missing | Med | M | 2 | Per-user, tenant-scoped, full CRUD; don't expose redacted persons (NN#2/#3). |
+| Saved-record shoebox / review queue | Stage candidate records before committing. | Missing | Med | M | 4/7 | Auto-attach via ChangeProposal (NN#1); legal sources (NN#6). |
+| Guided research suggestions | Proactive "research next" engine (today only flags problems). | Partial | High | L | 4 | Advisory; writes via ChangeProposal (NN#1); cross-tree via privacy engine (NN#2). |
+| Persona-adaptive onboarding | Family Keeper / Serious Researcher / Property Researcher selector (PRD US-002, documented but unbuilt). | Missing | Low–Med | L | 2 | Pure presentation. |
+| Dashboard widgets, scratchpad, research-link sidebar, blog/narrative authoring, research wiki, crowd indexing | Conveniences. | Missing | Low | S–XL | later | Widgets/published narratives read via privacy engine (NN#2/#3). |
+
+---
+
+### 2.9 Collaboration & sharing
+
+Authorization is enforced everywhere, but the **management surface is entirely absent** — the most consequential gap relative to the multi-user product promise. Because the Critical items below previously sat at Phase 6 while their labels said "breaks NN#8," a minimal management slice is pulled forward to Phase 2; the richer invite/email UX stays at Phase 6.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| **Membership PATCH/DELETE + role change (minimal slice)** | Add/adjust/revoke a collaborator and change `role` — the substrate (mutable `role`) exists; only the endpoints are missing. Resolves the create-only NN#8 break without the full invite flow. | Partial | **Critical** | S–M | 2 | **Pulled forward** — a create-only entity shouldn't wait for Phase 6 (NN#8). Revocation routes through the single privacy point. |
+| Full invite/grant flow (email + UI) | Email-based invitations, pending-invite state, role-grant UI, resend/expire. Builds on the minimal slice. | Partial | High | L | 6 | Invitation email via configured SMTP (NN#7); membership changes through the one enforcement point. |
+| **Read-only public tree share** | Visibility model already redacts living persons for anonymous viewers, but every endpoint requires `CurrentUser` — no optional-auth dep, no public route, no public page. | Partial | High | M | 2 | Highest-leverage near-term sharing feature; living-safe by construction via `person_visibility` (NN#2/#3). |
+| SEO public profile pages (server-rendered) | Intent declared (`public` = search-indexable) but zero implementation; no sitemap/robots/meta. | Partial | Med | L | 2 | NN#2 explicitly names server-rendered public pages — must go through privacy engine, no direct row queries. |
+| **Notification / event-dispatch substrate** | Shared enabler seeded from `AuditEntry`: subscription + dispatch layer emitting privacy-filtered projections. Underpins watch/follow, mutual-consent match notices, comments, moderation, and in-app messaging. | Missing | High | L | 6 | **Privacy-filtered projections only — never raw before/after JSON** (NN#2/#3). |
+| Comments / discussion threads | Per-profile discussion (target = person/event/source), threaded. | Missing | High | M | 6 | Comments on living persons redacted for non-members (NN#2/#3); rides the dispatch substrate. |
+| In-app messaging (contact details hidden) | SMTP exists; no Message/Thread model. | Planned | High | L | 6 | Hide contact details; opens after mutual consent (NN#4); redact living-person content; rides dispatch substrate. |
+| Watch/follow + change notifications | `AuditEntry` is the natural event source; needs subscription entity + dispatch (substrate above). | Planned | Med | M | 6 | Notification builder reads via privacy engine, not raw rows. |
+| **Optimistic concurrency / lost-update protection** | No version/etag/`updated_at` precondition checks; concurrent multi-user edits can silently clobber. | Missing | High | M | 6 | Full-CRUD + multi-user without this risks lost updates; concurrent paths still route through privacy engine. |
+| Pending-changes moderation (human edits) | Queue contributor edits for owner approval — shares infra with the AI ChangeProposal queue. | Missing | Med | L | 6 | **Design together with ChangeProposal** (NN#1). |
+| Field-by-field profile merge & approval | WikiTree-style merge center + unmerge with per-field provenance. | Missing | Med | XL | later | Conflicting facts each retain Source/Citation (NN#5). |
+| Ownership transfer | `owner_id` is effectively write-once; needed for self-host longevity. A minimal reassignment endpoint is the NN#8 fix. | Missing | Med | M | 6 | **Violates write-once invariant** (NN#8) — importance/phase tension noted; ship the minimal slice when membership lands. |
+| Narrative website / HTML export | Static narrated site (reuse public-page renderer). | Missing | Med | L | later | Redact living persons at build time (static bypasses runtime engine) (NN#3). |
+| Two-way desktop↔online sync | Bidirectional sync with change journals. Audit log could seed a change feed. | Missing | Med | XL | later | No Ancestry TreeShare / paywalled sync (NN#6). |
+| Curator roles, trusted-list ACLs, field locking, projects/workspaces, forum, honor code, free-space wiki, portal homepage | Community-platform features. | Missing | Low | S–XL | later | New roles/ACLs/locks integrate with the **single** enforcement point, not parallel checks. |
+| Real-time co-editing | Out of scope; only optimistic concurrency planned. | Planned | Med | XL | later | Concurrent paths must route through privacy engine. |
+
+---
+
+### 2.10 Privacy & access control
+
+The architecture is correct (single engine, tenant mixin, audit, soft-delete + purge are **have**), but enforcement coverage and configurability have real holes — two of which are security-priority.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| **Uniform living-person redaction across child resources** | `_redact` runs on person reads but **not** on event/media/name/relationship/citation/source endpoints — non-members fetch a possibly-living person's events/photos/names directly. | Partial | **Critical** | M | 1–2 | **Security-priority. Core NN#3/NN#2 defect.** Apply `person_visibility` on every person-derived fact. |
+| **Email-verification enforcement gate** | `email_verified_at` is written at `auth_service.py:154` but read on no path; `register` returns an authenticated session cookie + token (201) pre-verification. | Partial | **High** | S | 1–2 | **Security-priority near-quick-win** — add the read-side check (NN#7 trust path). The check is small; the registration-mode switch below is the larger piece. |
+| Self-registration mode gating (approve / open / closed) | No env switch to choose open vs admin-approval vs closed registration. | Partial | High | M | 2/5 | Twelve-factor registration control (NN#7); pairs with the verification gate above. |
+| **Fix `site_members` visibility tier** | Defined + selectable in UI but `can_view_tree` only handles public/unlisted — fails closed unintuitively. | Partial | Critical | S | 1 | **Quick win.** Least-surprise; honor the tier the UI offers. |
+| Make `LIVING_RECENCY_YEARS` configurable | Hardcoded 100 at `privacy.py:23`. | Partial | High | S | 2 | **Quick win.** Twelve-factor (NN#7). |
+| Privacy-stripped export (redact living) | GEDCOM + account export emit full tree; no "strip living" mode. | Missing | High | M | 2 | Reuse `person_visibility`/`_redact` (NN#3). Owner self-export is safe today; shareable variant is the gap. |
+| Per-fact / per-field privacy + record flags | tentative/rejected/preferred/private flags on facts. | Missing | Med | L | later | If added, route through the single engine (NN#2). |
+| Granular rules by record type & viewer relationship | webtrees-style "hide marriages from non-descendants". | Missing | Med | L | later | Single enforcement point. |
+| OIDC / external IdP login | `AuthProvider` interface ready; only Local implemented. Authentik is the intended real auth. | Planned | High | L | 5 | Additive by design. |
+| Two-factor auth (TOTP) | Bearer/cookie session auth is solid; no MFA. | Partial | High | L | 5 | — |
+| DB-level audit immutability | Audit is insert-only by convention; no trigger/constraint. Verified as "adequate for self-host," so importance downgraded to match. | Have(soft) | Med | S | 9 | Adequate for self-host; upgrade to trigger only if true immutability is required. |
+| Block/hide users, family-group private space, DNA opt-in controls | Depend on messaging/DNA. | Missing | Low–Med | M–XL | 6/parked | DNA parked (NN#6). |
+
+---
+
+### 2.11 Import/export & standards
+
+GEDCOM 5.5.1 import/export and full data-portability export are **have**, but fidelity gaps directly undercut the provenance thesis — and one is outright data loss.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| **Citation links dropped on GEDCOM export** | Export never selects the Citation table — fact→source links, page, detail, confidence all dropped on export (they import fine). Re-importing your own export **destroys** the sources-first graph. | Partial | **Critical** | M | 2 | **Silent data loss on the product's signature data + destructive round-trip** (NN#5); breaks PRD US-013. |
+| GEDCOM 7.0 import/export | Version hardcoded `5.5.1`; no v7 semantics, SCHMA, SUBM, or UID handling. | Partial | High | L | 2 | Stated differentiator (FamilySearch interop). |
+| Custom/underscore tag preservation | `_MARNM` becomes `TYPE married`, other custom tags dropped — violates ≥99% round-trip goal. | Missing | High | L | 2 | Tension with provenance thesis (faithful record). |
+| PLAC FORM hierarchy + MAP coordinate round-trip | Import reads only PLAC text; export emits flat PLAC. lat/long + hierarchy lost on round-trip. | Missing | High | M | 2–3 | Round-trip fidelity for the land/maps pillar. |
+| Encoding detection (ANSEL/UTF-16) | UTF-8 round-trips; non-UTF-8 files silently mangled via `errors='replace'`; CHAR tag ignored. | Partial | High | S | 2 | **Near quick win.** Detect/honor CHAR; reject or transcode rather than corrupt. |
+| HEAD completeness | HEAD at `gedcom.py:740` emits only `SOUR/GEDC/VERS/CHAR` — missing required `2 FORM LINEAGE-LINKED` (under GEDC) and `1 SUBM`. | Partial | Med | S | 2 | **Quick win.** Pure conformance. |
+| GEDCOM media (OBJE) round-trip | OBJE in skip-tags; media ignored on import, never emitted on export. | Partial | Med | M | 2 | Any media bundle keeps privacy gating. |
+| GEDZIP (.gdz) bundle | Bundled-media packaging. | Missing | Med | M | 2 | Natural once v7 + OBJE land. |
+| Selective / filtered export | Clippings-cart / branch subset. | Missing | Med | M | later | Maintain single-enforcement-point on export (NN#2). |
+| Import conformance validation | Preview is a mapping report, not structural/cardinality validation; bad lines silently skipped. | Partial | Med | M | 2 | — |
+| GEDCOM-X, Gramps XML, multi-format import, FHISO/ELF, PRF upload, KML export | Interop extras. | Missing | Low | L | later | PRF needs FamilySearch API (permitted, NN#6). |
+
+---
+
+### 2.12 Mobile & offline
+
+Responsive web is **partial**; PWA and offline-first are absent. Native apps are an explicit deferral.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| PWA (manifest + icons + viewport + service worker) | No manifest, no SW, no `next-pwa`; responsive coverage exists but unaudited on heavy views (tree canvas fixed 74vh). | Partial | High | M | 2 | If SW caches API responses, never retain non-owner PII; cache only what the session is authorized to see (NN#3). |
+| Responsive parity audit | 17 breakpoint usages; small-screen parity on tree/person views unverified. | Partial | High | M | 1–2 | Feature parity is an ARCH requirement. |
+| Offline-first editing + reconnect sync | No SW, no local store, no mutation queue. Valuable for archive/courthouse field research. | Missing | High | XL | later | Replayed edits go through service layer + audit (NN#1); cached data respects living-person rule (NN#3). |
+| Native mobile apps | Explicitly deferred (responsive web only). | Missing | Med | XL | later | If built, reads through one backend privacy engine (NN#2/#3/#4). |
+| Companion app w/ cross-device sync | Largely redundant with server-backed web. | Missing | Low | XL | later | Sync boundary enforces privacy (NN#2); full CRUD parity (NN#8). |
+| Relatives Around Me | Nearby-relatives discovery. | Missing | Low | L | later | Explicit opt-in; anonymous until mutual consent (NN#4). |
+
+---
+
+### 2.13 API & extensibility
+
+Internal REST + OpenAPI + generated TS client are **have**. The externalized developer story and the connector/plugin spine are not built.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| Public read-only API + scoped tokens (OAuth) | Bearer token is opaque session only; `TokenPurpose` lacks scopes; designed `public.py` never built. | Partial | High | L | 5–6 | Any scoped-token path routes through `person_visibility` + living-person redaction (NN#2/#3). |
+| SourceConnector framework | Only AuthProvider/ObjectStore/Mailer base classes exist; no connector base/loader/registry. Gates AI, hints, property connectors. | Planned | Med | L | 4 | Read-only, rate-limited; findings via ChangeProposal (NN#1); legal sources only (NN#6). |
+| Webhooks / change feeds | `AuditEntry` is the natural substrate (shares the notification dispatch layer, §2.9); no feed/webhook layer. | Missing | Med | L | 6 | Emit privacy-filtered, tenant-scoped projections — never raw before/after JSON (NN#2/#3). |
+| CLI / scripting surface | No `[project.scripts]`, no Typer/Click; worker is a purge loop only. Self-hosters want bulk admin. | Missing | Med | M | 9 | Funnel reads through privacy.py, writes through audit; admin-scoped, no assistant-write path. |
+| Plugin/addon architecture | Connector framework only; no general UI/report/theme plugin system planned. | Planned | Med | L | later | Sandbox via service layer; no privacy/audit bypass, no writes outside ChangeProposal. |
+| In-app query tooling (SuperTool) | Power-user expression engine. | Missing | Low | L | later | Execute through privacy engine — no row enumeration bypass (NN#2). |
+| Certified partner program | Organizational, not software. | Missing | Low | XL | — | Out of scope until a hosted offering exists. |
+
+---
+
+### 2.14 Performance & scale
+
+Postgres + S3, multi-tenant isolation are **have**. Queue, observability, backups, pagination, and scale validation are the gaps that gate Phases 4/7 — several are current functional limitations, not late-phase validation tasks.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| Real job queue (Postgres/Redis-backed) | Worker is a fixed-interval purge loop; GEDCOM import and account export run **inline in the request**. | Partial | High | L | 4 (pre-req) | Blocks NN#1 (assistant in worker) and NN#4 (hint matching in worker). Queue backend is an open question (PRD §11). |
+| **Pagination on list endpoints + server-side tree loading** | List endpoints (`persons.py:37`, events, relationships) take no `limit/offset/skip`; the tree view loads the whole graph client-side. A *current* limitation against the 50k-person target. | Planned | High | M | 1–2 | **Split out from scale validation** — this is a correctness/functional gap now, not a Phase 9 task. |
+| Scale validation (50k+ trees, P95<2s, load test) | No benchmark or load test exists. | Planned | High | L | 9 | Inline heavy ops risk partial writes — moving to the queue is what makes "failures never corrupt state" true. |
+| **Operator backup: one-command `pg_dump` + MinIO sync** | Only a documented procedure + per-account ZIP exist; no scripted DB+object dump. For a self-host product this is day-one data-loss exposure. | Partial | Critical | M | 1–2 | **Pulled forward** — Critical importance contradicted the old Phase-9 slot. Restore must re-apply privacy state faithfully (NN#3); safety net for NN#8. |
+| Scheduled / cloud automated backup + restore tooling | Cron-driven, off-host, verified-restore workflow. | Partial | High | L | 9 | Builds on the one-command slice above. |
+| ARM64 build matrix | CI builds `linux/amd64` only; many self-hosters run ARM SBCs. | Partial | High | S | 1 | **Quick win.** Add arm64 + QEMU to buildx (NN#7 container-native). |
+| Structured JSON logs + Prometheus metrics | Plain-text stdlib logging; no `/metrics`. | Partial | Med | M | 9 | Logs/metrics reference UUIDs, never names/PII (NN#3/#4). |
+| pgvector enablement | Image has pgvector; app never creates the extension or adds embedding columns (docs claim otherwise). | Partial | Med | M | 7 | See §2.3 — embedding provider open question; candidates via privacy engine. |
+| Database check-and-repair | No orphan/dangling-edge/cycle scanner (recent "harden tree render" commit shows bad graphs occur). | Missing | Med | M | 9 | Tenant-scoped + audited; auto-fix via ChangeProposal (NN#1). |
+| Pluggable DB backend, billions-scale shared tree, weekly record releases | Different product models. | Missing | Low | XL | — | **Out of scope** — Postgres-only is consistent with the invariants; global shared tree conflicts with NN#2/#3/#4. |
+
+---
+
+### 2.15 Property / land chain-of-title — *headline differentiator*
+
+The entire "land" half is **planned/missing** but fully specified. This is where Provenance has no real competitor.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| Property/parcel first-class entity | No model/endpoint/service/migration. Foundation for the whole category. | Planned | High | L | 3 | Full CRUD in API+UI (NN#8); reads added carefully to the **single** privacy engine (NN#2). |
+| Typed OwnershipEvents | grant/patent, purchase, sale, inheritance, gift, tax sale, foreclosure, eminent domain — with grantor/grantee Persons + Citation. | Planned | High | L | 3 | Each event carries a Citation (NN#5); grantor/grantee living-person links redacted (NN#3). |
+| Chain-of-title timeline + gap flagging | Ordered OwnershipEvents first-grant→present, breaks flagged. | Planned | High | M | 3 | The genuinely differentiating analytical piece (PRD US-032). |
+| Bidirectional owner↔person, parcel↔place | "Every property a person held" / "every parcel at a place." | Planned | High | M | 3 | Reverse traversals filtered through privacy engine (NN#2). |
+| Citations on OwnershipEvents | Add `ownership_event_id` to Citation (5th target). | Partial | Critical | S | 3 | **Quick win once Property lands** — single FK + CHECK edit (NN#5). |
+| Legal description verbatim storage | metes-and-bounds / PLSS township-range-section as-written. | Planned | Med | L | 3 | Part of the Property model; preserves the record faithfully. |
+| Parcel/plat boundary geometry | Optional geometry; plain coords first. | Planned | Med | L | 3+ | PostGIS is an open question (ARCH §14) — surface dependency. |
+| PLSS / metes-and-bounds parsing → geometry | Automated survey parsing. | Planned | Med | XL | later | Hard; gated on PostGIS. |
+| BLM/GLO federal land-patent connector | Marquee US land source. | Planned | High | L | 8 | Permitted source (NN#6); patents surface as ChangeProposals (NN#1); read-only + rate-limited. |
+| USGS map + public county-deed connectors | Per-jurisdiction grantor/grantee indexes. | Planned | Med | L | 8 | Each connector verifies a legally open source (NN#6). |
+| Co-ownership roles / tenure types | joint tenants, TIC, life estate, heirs. | Planned | Low | M | later | Multiple parties likely free with OwnershipEvent; role typing is a refinement. |
+| Tax/assessment rolls, UK Tithe, Lloyd George Domesday | Valuation + non-US collections. | Missing | Low | M–L | — | US-focused v1; international formats out of scope (model is country-agnostic). |
+
+---
+
+### 2.16 AI assistant — *defining differentiator*
+
+Entirely **planned** — and note the docs-vs-code gap: ARCHITECTURE §5 lists `ChangeProposal` as part of the "landed" core model, but no model/migration/schema exists. The audit substrate (`actor_type=assistant`, before/after JSONB) is the right foundation; the ChangeProposal model and ModelProvider abstraction are the two critical-path pieces.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| **ChangeProposal (propose-then-confirm)** | The defining invariant. No `proposal.py`, no migration, no review UI yet — despite docs implying it landed. | Planned | **Critical** | L | 4 | **IS NN#1.** Enforce structurally: assistant tools return proposals; only user action applies one; application flows through the normal service layer (privacy + audit). ChangeProposal itself needs full CRUD (NN#8). Correct the docs to match reality. |
+| Pluggable LLM + embedding provider | `ModelProvider` over Anthropic/OpenAI/xAI/Ollama; env placeholders exist, no interface code. | Planned | Critical | M | 4 | **Twelve-factor, no hard-coded keys/endpoints** (NN#7); the Ollama/self-hosted path is what makes the privacy-first promise real. |
+| AI research-assistant chatbot (RAG over tree) | Marquee feature; needs ModelProvider + connector + retrieval through privacy engine. | Planned | High | XL | 4 | NN#1 propose-only, NN#2 privacy retrieval, NN#3 redaction. |
+| Conversational / connector record search | Search legal sources via the assistant. | Planned | High | L | 4 | Legal sources (NN#6); findings = Source + Citation (NN#5). |
+| Fact extraction from documents | Extracted facts map cleanly to ChangeProposal review. | Missing | Med | M | 4 | Canonical NN#1 use case; each fact carries a Citation (NN#5). |
+| OCR/HTR transcription + document translation | Worker job via ModelProvider. | Missing | Med | L | 4+ | Output → Source/Citation (NN#5); via ModelProvider (NN#7); auto-extraction emits ChangeProposal (NN#1). |
+| Next-step research guidance | Gap analysis → suggested next record. | Planned | Med | M | 4 | Reads via privacy engine; advisory unless it queues fetches. |
+| AI biography / audio narration | Read-only generation grounded in tree data. | Missing | Low | M–L | later | Must not leak living-person PII (NN#3); via ModelProvider (NN#7); stored biographies = full CRUD (NN#8). |
+
+---
+
+### 2.17 Localization & accessibility
+
+A documented **day-one commitment** ("UI strings externalized from day one") that is currently **unmet** — every label is a hardcoded literal. Correct the PRD claim or close the gap.
+
+| Item | Description | Status | Imp | Eff | Phase | Non-negotiable |
+|---|---|---|---|---|---|---|
+| **UI string externalization** | No i18n lib, no message catalogs; all copy hardcoded in TSX. Gating prerequisite; cheapest to do now while the surface is small. | Missing | High | L | 1–2 | PRD §6 promises this "from day one" — **docs-vs-code gap; edit the doc now.** |
+| Multi-language UI (40–60+ langs) | Translation pipeline after externalization (frontend + backend-generated messages). | Missing | High | XL | later | Table stakes across all competitors. |
+| Accessibility / WCAG 2.2 AA | Some ARIA/focus styling; no CI a11y audit, no skip-links, SVG tree viz not keyboard/screen-reader navigable. | Partial | High | L | 2/9 | Stated PRD §6 target; add axe/pa11y in CI; accessible alternate to the chart. |
+| Unicode-correct non-Latin names | Stores fine (UTF-8); no NFC normalization on write, no locale-aware collation, no romanized search. | Partial | High | M | 2 | Apply `unicodedata.normalize('NFC')` on input; add COLLATE; supports faithful-record goal. |
+| Structured/compound surname components | Surname is a single field; no support for Spanish/Portuguese paternal+maternal, Arabic nasab, particles/prefixes. | Missing | Med | M | 2 | New Name sub-fields ship with full CRUD (NN#8); preserves the name as recorded. |
+| Non-Gregorian calendar dates | `calendar` column is a placeholder; GEDCOM calendar escapes never parsed/populated. | Partial | Med | L | 2 | Preserve original calendar as recorded (sources-first). |
+| Language tags / romanized variants per name | No language_tag/script/romanized fields; GEDCOM ROMN/LANG unhandled. | Missing | Med | M | 2 | New Name sub-fields ship with full CRUD (NN#8). |
+| RTL support | `lang="en"` hardcoded, no `dir`, physical CSS properties throughout. | Missing | Med | M | later | Convert to logical CSS properties; cheaper once i18n exists. |
+| Selectable themes | Light/dark/system works; brand palette intentionally single. | Partial | Med | M | later | Confirm whether additional themes are a deliberate non-goal (brand guide constrains palette). |
+| Multi-language report/diagram output | Depends on i18n + reports, neither shipped. | Missing | Low | L | later | — |
+
+---
+
+## 3. Quick wins (high importance / low effort)
+
+Ordered by leverage. All are S-effort or a thin slice of a larger item, and most close a stated invariant gap.
+
+1. **Fix `site_members` visibility tier** (Privacy, Critical/S) — defined and selectable in the UI but never handled in `can_view_tree`; fails closed unintuitively.
+2. **Email-verification enforcement gate** (Privacy/Auth, High/S) — add the read-side `email_verified_at` check so a freshly registered, unverified user doesn't get a live authenticated session. Security-priority; the registration-mode env switch (open/approve/closed) is the larger follow-on, not part of this quick win.
+3. **Citation confidence selector in the cite form** (Sources, High/S) — confidence is modeled and API-writable but unreachable in the UI; every UI citation is currently NULL. Honors NN#8 and the evidence-quality thesis.
+4. **Source edit UI + expose all 8 fields** (Sources, High/S) — update API exists but there is no edit form and create exposes ~3 fields; a create-but-not-edit entity violates NN#8.
+5. **Make `LIVING_RECENCY_YEARS` env-configurable** (Privacy, High/S) — hardcoded 100 at `privacy.py:23`; twelve-factor (NN#7).
+6. **Add `ownership_event_id` to Citation** (Property/Sources, Critical/S) — single FK + CHECK-constraint edit the moment Property lands; the spine is already built (NN#5).
+7. **GEDCOM encoding detection** (Standards, High/S) — detect/honor the CHAR tag; reject or transcode ANSEL/UTF-16 rather than silently mangling with `errors='replace'`.
+8. **GEDCOM HEAD completeness** (Standards, Med/S) — emit the required `2 FORM LINEAGE-LINKED` (under GEDC) and `1 SUBM` at `gedcom.py:740`. Pure conformance.
+9. **ARM64 CI build matrix** (Perf/Scale, High/S) — add `linux/arm64` + QEMU to buildx for both images; many self-hosters run ARM SBCs.
+10. **`GET /{tree}/citations/{id}` endpoint** (Sources, Med/S) — API symmetry (NN#8).
+11. **Transcription/abstract fields on Source** (Sources, Med/S) — add `transcription_text` + `abstract_text`, distinct from `citation_text`; core to evidence analysis.
+12. **Sort the merged person timeline** (Research workflow, Med/S) — `shownEvents.sort()` on `date_start`; currently appended unsorted.
+13. **Doc corrections (docs-vs-code)** (Meta, trivial/S) — edit CLAUDE.md / ARCHITECTURE so the pgvector "used" claim, the i18n "from day one" claim, and the ChangeProposal "landed" claim match reality. The repo convention requires docs to travel with code.
+
+> **Ships-with, not standalone:** *Revocable / adjustable access (membership PATCH/DELETE + role change)* is security-critical and S-effort, but it is the minimal slice of the membership work (§2.9) and ships **with** those endpoints — it is not independently shippable on its own.
+>
+> **Higher priority than any quick win, but M-effort (not quick):** the **media privacy leak** (§2.4), the **child-resource redaction gap** (§2.10), and pulling the **one-command operator backup** (§2.14) forward. Treat these as **security-/data-loss-priority Phase 1–2 fixes** regardless of the quick-win list.
+
+---
+
+## 4. Strategic differentiators
+
+Where to invest to make Provenance distinct rather than a webtrees clone. Each leans on a non-negotiable as a *feature*, not a constraint.
+
+**1. Property chain-of-title (the "land" half).** No surveyed competitor models ownership as a typed, cited event chain tying parties across time, with gap-flagging and bidirectional owner↔person / parcel↔place traversal, fed by **legal** public sources (BLM/GLO patents, USGS, public county deeds). This is the single clearest "no one else does this" capability. Sequence: Property + OwnershipEvent + Citation-target (Phase 3) → chain-of-title view → BLM/GLO connector (Phase 8). The Citation extension is a quick win; the entity is the prerequisite for everything else in the category.
+
+**2. The ChangeProposal AI model.** "The assistant never writes autonomously" is a *trust* differentiator in a market where users fear AI corrupting their research. Build it structurally — assistant tools return proposals; only an explicit human action applies one; application flows through the normal service layer so it always hits the privacy engine and audit log. The same approval queue moderates untrusted human-contributor edits (Collaboration §2.9), so design them together. The audit substrate is already in place; ChangeProposal + ModelProvider are the critical path — and the docs should stop asserting ChangeProposal has landed until it has.
+
+**3. Anonymous, mutual-consent cross-tree hints.** The privacy model already redacts living people for anonymous viewers, so a hint system that reveals *nothing identifying* until both sides opt in is achievable by construction — and is a categorically more trustworthy version of MyHeritage Smart Matches / Ancestry hints. Requires the matching engine (pgvector enablement + candidate generation, Phase 7), the notification/event-dispatch substrate (§2.9), and the messaging channel that opens only post-consent.
+
+**4. True self-hosting + data ownership.** Full account export/import, soft-delete recovery, GEDCOM round-trip, env-driven everything, and (to-build) operator-grade scheduled backup + ARM support make Provenance the genealogy app you actually own. Two correctness items gate the promise: GEDCOM export must stop dropping citations (a Provenance→Provenance round-trip currently destroys the sources graph), and operator backup must move from "documented procedure" to a one-command dump. The Ollama/self-hosted ModelProvider path means even the AI assistant runs without tree data leaving the deployment — a promise no commercial competitor can make.
+
+**5. Sources-first as a felt experience.** The two-tier model is built; the differentiator is making it *visible and low-friction*: a guided Evidence-Explained citation builder, transcription/abstract fields, source-driven data entry (transcribe a document into the tree), per-fact confidence surfaced in the UI, and — critically — citations that **survive GEDCOM export**. These turn "every fact links to where it came from" from an architecture note into the product's personality.

docs/design/change-proposal.md

@@ -0,0 +1,80 @@
+# Design note: ChangeProposal (propose-then-confirm)
+
+Status: **in progress**. Implements non-negotiable #1 (CLAUDE.md): *the AI
+assistant never writes autonomously.* Every assistant "write" emits a
+**ChangeProposal** — a structured diff a human approves, edits, or rejects.
+
+## The invariant, structurally
+
+There must be **no code path where a model response mutates tree data**. We get
+this by construction, not convention:
+
+- Model providers (`app/integrations/models/*`) are read-only text/vector
+  producers — they never import a repository or session-mutating service.
+- The assistant's tools, when they land, will call `change_proposal_service.propose(...)`,
+  which only **inserts a pending ChangeProposal**. It performs no domain mutation.
+- A ChangeProposal's operations are executed **only** by
+  `change_proposal_service.apply(...)`, which:
+  1. requires the actor be an **editor/owner** of the tree (`privacy.can_edit_tree`),
+  2. dispatches each operation through the **normal editing services**
+     (`person_service`, `event_service`, …) — so every change passes the privacy
+     engine and writes an `AuditEntry` with the **human** as `actor`,
+  3. flips the proposal to `applied`.
+
+So an assistant can *suggest* anything, but a change reaches the database only
+when a human with edit rights approves it, and only via the same services a human
+edit uses.
+
+## Data model
+
+`ChangeProposal` (`TenantScoped` tree_id, `Timestamps`, `SoftDelete`):
+
+| field | notes |
+|---|---|
+| `tree_id` | tenant boundary |
+| `status` | `pending` \| `applied` \| `rejected` |
+| `origin` | `assistant` \| `contributor` — who proposed it (the contributor case also moderates untrusted human edits) |
+| `created_by_user_id` | the user on whose behalf the assistant acted, or the contributor |
+| `summary` | one-line human description ("Add birth 1850 to John Smith") |
+| `rationale` | the assistant's reasoning / sources (text) |
+| `operations` | JSONB list of ops (the structured diff) |
+| `reviewed_by_user_id`, `reviewed_at`, `review_note` | set on approve/reject |
+| `apply_error` | populated if application failed (proposal stays `pending`) |
+
+An **operation** is `{op, entity_type, entity_id?, payload}`:
+- `op` ∈ `create` | `update` | `delete`
+- `entity_type` ∈ `person` | `name` | `event` | `relationship` | `source` | `citation`
+- `entity_id` — null for `create`; the target id for `update`/`delete`
+- `payload` — proposed field values (`create`/`update`); ignored for `delete`
+
+A proposal may carry several operations (e.g. "add a person and link them as a
+child" = create person + create relationship), applied **in order**. The editing
+services each commit, so v1 application is **not transactional across ops** — if
+op N fails, ops 1..N-1 are already applied and the proposal stays `pending` with
+`apply_error` set so the reviewer can fix and re-apply the remainder. Single-op
+proposals (the common near-term case) are effectively atomic. Cross-op atomicity
+is a follow-up (it needs the services to accept a no-commit mode).
+
+## Service surface
+
+- `propose(session, *, tree, origin, created_by, summary, rationale, operations) -> ChangeProposal`
+  — inserts a `pending` proposal. The **only** thing the assistant can call.
+- `list_proposals` / `get_proposal` — visible to tree members.
+- `apply(session, *, actor, tree, proposal_id, edited_operations=None) -> ChangeProposal`
+  — editor-only. Optional `edited_operations` lets the reviewer tweak the diff
+  before applying ("edit" in approve/edit/reject). Dispatches each op through the
+  editing services; on any failure, rolls back and records `apply_error`.
+- `reject(session, *, actor, tree, proposal_id, note=None)` — editor-only.
+
+## API
+
+`/trees/{id}/proposals`: `GET` (list, `?status=`), `POST` (create — used by tests
+and the future contributor flow), `GET /{pid}`, `POST /{pid}/apply`,
+`POST /{pid}/reject`, `DELETE /{pid}`.
+
+## Out of scope (follow-ups)
+
+- The assistant itself (it will be the primary producer; #-future).
+- A rich diff/edit UI — v1 ships a review list with approve/reject; "edit before
+  apply" is supported in the API and can get UI later.
+- Dispatch for media/place/tree-settings ops (added when a producer needs them).

docs/design/tree-visibility.md

@@ -0,0 +1,157 @@
+# Design note: tree visibility & the public viewing surface
+
+Status: **proposed** (design only — no code yet). Owner: Justin. Created 2026-06-09.
+
+This is a privacy-critical change (it creates the first anonymous read surface in
+Provenance). Per CLAUDE.md, design before code. Implementation should land in
+small, individually-reviewable PRs, with tests on the privacy engine and the
+public read path before any anonymous endpoint is exposed.
+
+## 1. The model
+
+Visibility flattens **two axes** — *who may read* and *how discoverable* — into one
+ordered enum for the UI:
+
+| Level | Anonymous (no login) | Any logged-in user | Tree members | In-app directory | Search-indexed |
+|---|---|---|---|---|---|
+| `public` — anyone on the web | ✅ view¹ | ✅ view¹ | ✅ full | ✅ listed to everyone | ✅ sitemap + indexable |
+| `site_members` — Public, Site Members | ❌ | ✅ view¹ | ✅ full | ✅ listed to logged-in users | ❌ (`noindex`) |
+| `unlisted` — anyone with the link | ✅ via direct link¹ | ✅ via link¹ | ✅ full | ❌ never listed | ❌ (`noindex`) |
+| `private` | ❌ | ❌ | ✅ full | ❌ | ❌ |
+
+¹ **Every non-member view passes through the privacy engine.** Living people are
+redacted, and per-person `private` hides / `public` reveals, exactly as
+`person_visibility()` already does (`backend/app/services/privacy.py:100-110`).
+This is the single enforcement point — no public code path may issue a raw query.
+
+Decisions captured (2026-06-09):
+- **Unlisted** = anyone with the link, no account required. The link must be
+  **unguessable** (the tree UUID is already non-enumerable; do not add a public
+  integer id). Unlisted trees are excluded from the directory and sitemap and
+  served `noindex`.
+- **Public** discovery for v1 includes **an in-app public browse/search**, not
+  just search-engine indexing.
+- **Public – Site Members** = *any* registered account on this instance (not an
+  invite list — that is already tree membership / `private`).
+
+## 2. Data model
+
+`TreeVisibility` enum (`backend/app/models/enums.py`) gains a value:
+
+```
+public        # anyone on the web
+site_members  # any authenticated user of this instance   <-- NEW
+unlisted      # anyone with the link
+private        # members only (default)
+```
+
+- Alembic migration to `ALTER TYPE tree_visibility ADD VALUE 'site_members'`
+  (Postgres enum add-value cannot run inside a transaction with other DDL — use
+  `op.execute` with autocommit, separate migration).
+- Default stays `private`. Existing rows unchanged.
+- `TreeRead`/`TreeUpdate`/`TreeCreate` schemas already carry the enum; they pick
+  up the new value automatically. The OpenAPI client regen (`gen:api`) exposes it
+  to the frontend.
+
+## 3. Privacy engine
+
+`can_view_tree()` today treats `public` and `unlisted` identically and ignores
+whether the viewer is anonymous vs authenticated (`privacy.py:44-49`). Replace the
+final line with explicit branching on viewer auth state:
+
+```
+if membership: return True              # members always
+match tree.visibility:
+  public, unlisted: return True         # anonymous OK (unlisted gated only by knowing the link)
+  site_members:     return user_id is not None   # any logged-in account
+  private:          return False
+```
+
+`person_visibility()` is unchanged — it already redacts living/private people for
+non-members. Add focused unit tests: anonymous + each visibility; living person
+redacted on public/unlisted; `site_members` denies anonymous but allows a
+logged-in non-member; `private` denies both.
+
+## 4. The anonymous read path (the careful part)
+
+**Recommendation: a dedicated read-only public API namespace**, not optional-auth
+on the existing endpoints. Rationale: it is far easier to audit a small,
+purpose-built surface that *always* funnels through `person_visibility` than to
+weaken the membership checks on the authenticated endpoints and hope every branch
+is covered.
+
+- New router `app/api/v1/public.py`, mounted at `/api/v1/public`, with an
+  **optional-auth** dependency `CurrentUserOrNone` (returns `User | None`; never
+  401s). Contrast with `CurrentUser` (`deps.py:30-36`) which hard-401s.
+- Endpoints (read-only; no create/update/delete):
+  - `GET /public/trees` — directory: lists `public` to everyone; additionally
+    lists `site_members` when the caller is authenticated. Paginated, search via
+    existing `pg_trgm`. Never lists `unlisted`/`private`.
+  - `GET /public/trees/{id}` — tree metadata if `can_view_tree(user_or_none)`.
+  - `GET /public/trees/{id}/persons`, `/persons/{pid}`, `/relationships`,
+    `/events`, `/media`, … — each filtered through `person_visibility`, returning
+    redacted projections (a `PublicPersonRead` that omits PII for redacted people:
+    no exact dates, no living-person names beyond "Living", etc.).
+- **A redacted response schema**, distinct from the member `PersonRead`, so the
+  serializer physically cannot emit fields a non-member shouldn't see. Redaction
+  happens in the service, not the route.
+- **Rate limiting** on the public namespace (per-IP) to blunt scraping/enumeration.
+- **Audit**: count public reads; do not log PII.
+
+## 5. Frontend public pages
+
+- New **server-rendered** routes outside the authed app shell, e.g.
+  `/p/[treeId]` (tree), `/p/[treeId]/[personId]` (person), `/explore` (directory).
+  Server components fetch the `/api/v1/public/*` endpoints; no login redirect.
+- `robots`: allow + sitemap for `public`; `noindex, nofollow` meta for `unlisted`
+  and `site_members`. Sitemap lists only `public` trees/persons.
+- The directory `/explore` is anonymous for `public`; shows `site_members` trees
+  only to logged-in users.
+- Reuse the tree/person view components where possible, fed by the redacted
+  schema.
+
+## 6. UI control
+
+Update the visibility dropdown (`frontend/app/trees/page.tsx`, shipped in PR #41)
+from 3 to 4 options with helper text:
+
+```
+Private          — only you and people you invite
+Public – Members — any signed-in user on this site
+Unlisted         — anyone with the link (not listed or indexed)
+Public           — anyone on the web; listed and search-indexable
+```
+
+A short confirmation when switching *to* `public` ("This makes <tree> visible to
+anyone on the web. Living people stay hidden.") is worthwhile given the stakes.
+
+## 7. Guardrails / invariants
+
+- One enforcement point: every public response is built from `person_visibility`
+  output. No raw repository reads in the public router.
+- Living-person protection holds regardless of tree visibility.
+- Unlisted relies on UUID unguessability; never expose a sequential public id.
+- `noindex` everything except `public`; sitemap is `public`-only.
+- Tests gate the merge: privacy-engine matrix + an integration test that hits the
+  public endpoints anonymously and asserts no living-person PII leaks.
+
+## 8. Suggested phasing (small PRs)
+
+1. Enum value + migration + regen client (+ dropdown → 4 options). No behavior
+   change yet for non-members.
+2. Privacy-engine branching + unit tests.
+3. Public read API namespace (optional-auth, redacted schema, rate limit) + tests.
+4. Public frontend pages (`/p/...`) + robots/sitemap.
+5. In-app `/explore` directory + search.
+
+Steps 2–3 are the privacy-critical core and should be reviewed hardest.
+
+## 9. Open questions
+
+- Caching: public pages are cacheable for SEO, but cache keys must not blur the
+  redacted-vs-member rendering. Likely: cache only the anonymous projection at the
+  edge; never cache member responses.
+- Do `site_members` trees appear in the sitemap for logged-in crawling? (Default:
+  no — `noindex`.)
+- Per-tree opt-out of the directory even when `public`? (Probably unnecessary;
+  `unlisted` already covers "reachable but not listed.")

frontend/.gitignore

@@ -3,4 +3,5 @@
 /out
 /build
 next-env.d.ts
+*.tsbuildinfo
 .env*.local