openapi.yaml

# FamilyHub v1 — the API contract, in OpenAPI 3.0.
#
# WHY THIS FILE EXISTS (read this before the YAML):
# v1 renders HTML, but every route was designed RESTfully so that v2 can
# serve JSON from the same URLs to an Angular frontend. This file writes
# that contract down in the industry-standard format (D288 calls this
# API-first design). Two things keep it honest:
#
#   1. tests/test_openapi.py walks Flask's live route map and FAILS if any
#      route is missing from this file — the spec cannot silently drift.
#   2. /apidocs renders this file as a browsable page (server-side, so it
#      satisfies the strict CSP — no Swagger UI inline-style exceptions).
#
# WP1 RE-FOUNDATION (Master Plan §1): this spec was trimmed to the surviving
# infrastructure surface — auth, the admin panel, and public/plumbing routes.
# The old feature routes (albums, posts, wiki, timeline, plans, search) were
# removed with the feature layer. WP2 produces the *real* v1 API contract — the
# CRUD + view endpoints for the GEDCOM-7 schema — and that becomes the stable
# interface Cowork builds the front-end against (Master Plan §7).
#
# Conventions: HTML-form routes are marked as returning text/html today;
# v2 swaps those responses to application/json without touching the paths.

openapi: "3.0.3"
info:
  title: FamilyHub API
  version: "1.0"
  description: >
    Private, GEDCOM-7-backed family portal. All family content requires a
    session cookie (login). The /api/* surface is the WP2 JSON CRUD + search
    contract Cowork builds the WP3 front-end against; reads need any logged-in
    member, writes need at least the Contributor role (§10). Deletes are SOFT
    (ADR-0001): a deleted record reads as gone but is recoverable via
    /api/restore or /api/audit/{id}/revert. State-changing /api calls
    must send the CSRF token in an X-CSRFToken header. The auth/admin/plumbing
    routes render HTML today; v2 can serve JSON from the same URLs.

tags:
  - name: Auth
    description: Login, logout, password self-service
  - name: Admin
    description: Requires the admin flag
  - name: Plumbing
    description: Health, crawler policy, PWA shell, security contact, docs
  - name: Individuals
    description: People in the tree (INDI) and their names
  - name: Families
    description: Partnerships (FAM) and parent/child links
  - name: Events
    description: Events & attributes (BIRT, DEAT, MARR, OCCU…), polymorphic
  - name: Places
    description: Reusable PLAC records
  - name: Sources
    description: Repositories, sources, and citations (the evidence layer)
  - name: Media
    description: Photo uploads (OBJE), login-walled, with polymorphic links
  - name: Notes
    description: Markdown memories/bios (NOTE/SNOTE) with polymorphic links
  - name: Search
    description: People by name + filters, and full-text over notes (§12)
  - name: WriteControl
    description: Audit trail, restore, and revert — post-moderation (ADR-0001)
  - name: Account
    description: Account↔Person link, "my person", and the tree root (ADR-0002)
  - name: Tree
    description: Pedigree graph, relationship finder, dashboard stats, On This Day
  - name: Inbox
    description: Suggestions inbox and role-change requests (§5, §10)
  - name: AdminApi
    description: Admin actions — users, settings, backups, permission matrix (§9, §10)
  - name: Views
    description: WP4 (Cowork) — HTML pages that render the app shell + call the JSON API from the browser

paths:
  # --- Plumbing ---------------------------------------------------------------
  /:
    get: {tags: [Plumbing], summary: Public welcome page (dashboard when logged in), responses: {"200": {description: HTML page}}}
  /health:
    get:
      tags: [Plumbing]
      summary: Liveness check for monitors
      responses:
        "200": {description: '{"status":"ok","database":"ok"}'}
        "503": {description: Database unreachable}
  /robots.txt:
    get: {tags: [Plumbing], summary: "Crawler policy: index nothing", responses: {"200": {description: text/plain}}}
  /manifest.webmanifest:
    get: {tags: [Plumbing], summary: PWA web-app manifest (name, icons, colors), responses: {"200": {description: application/manifest+json}}}
  /sw.js:
    get: {tags: [Plumbing], summary: Service worker (static shell cache + offline fallback; never caches photos), responses: {"200": {description: text/javascript}}}
  /offline:
    get: {tags: [Plumbing], summary: Standalone offline fallback page (precached by the service worker), responses: {"200": {description: HTML page}}}
  /.well-known/security.txt:
    get: {tags: [Plumbing], summary: RFC 9116 security contact, responses: {"200": {description: text/plain}}}
  /about:
    get: {tags: [Plumbing], summary: Admin-written about/contact page, responses: {"200": {description: HTML page}}}
  /site/hero:
    get: {tags: [Plumbing], summary: Dashboard banner image (login-walled), responses: {"200": {description: image bytes}}}
  /apidocs:
    get: {tags: [Plumbing], summary: This spec, rendered as a browsable page, responses: {"200": {description: HTML page}}}
  /openapi.yaml:
    get: {tags: [Plumbing], summary: This spec, raw, responses: {"200": {description: text/yaml}}}

  # --- Auth --------------------------------------------------------------------
  /auth/login:
    get: {tags: [Auth], summary: Login form, responses: {"200": {description: HTML form}}}
    post:
      tags: [Auth]
      summary: Authenticate (rate-limited 10/min/IP)
      responses:
        "302": {description: Redirect home with session cookie}
        "200": {description: Form re-rendered with vague error}
        "429": {description: Rate limit hit}
  /auth/logout:
    post: {tags: [Auth], summary: End the session (POST-only by design), responses: {"302": {description: Redirect home}}}
  /auth/change-password:
    get: {tags: [Auth], summary: Change-own-password form, responses: {"200": {description: HTML form}}}
    post: {tags: [Auth], summary: Change own password (current password required), responses: {"302": {description: Changed}}}
  /auth/forgot-password:
    get: {tags: [Auth], summary: Request-reset form (hidden if mail unconfigured), responses: {"200": {description: HTML form}}}
    post:
      tags: [Auth]
      summary: Email a reset link (rate-limited 5/min; identical response for unknown usernames)
      responses: {"302": {description: Same friendly message either way}}
  /auth/reset-password/{token}:
    parameters: [{name: token, in: path, required: true, schema: {type: string}, description: Signed single-use token (1h)}]
    get: {tags: [Auth], summary: New-password form (token checked first), responses: {"200": {description: HTML form}, "302": {description: Invalid/expired token}}}
    post: {tags: [Auth], summary: Set the new password, responses: {"302": {description: Reset complete}}}
  /auth/verify-email/{token}:
    parameters: [{name: token, in: path, required: true, schema: {type: string}, description: Signed email-verification token (24h)}]
    get: {tags: [Auth], summary: Confirm an email address from the emailed link (§9), responses: {"302": {description: Verified (or invalid) — redirected home with a flash}}}

  # --- Admin (legacy server-rendered flows, kept as-is by FE-6 — see the
  # Views tag's /admin* entries below for the rebuilt native-Chronicle pages)
  # -------------------------------------------------------------------------
  /admin/users/new:
    get: {tags: [Admin], summary: New-account form (no self-registration exists), responses: {"200": {description: HTML form}}}
    post: {tags: [Admin], summary: Create an account, responses: {"302": {description: Created}}}
  /admin/users/{user_id}/edit:
    parameters: [{name: user_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Admin], summary: Edit display name / role / login email, responses: {"200": {description: HTML form}}}
    post: {tags: [Admin], summary: Save account changes, responses: {"302": {description: Saved}}}
  /admin/users/{user_id}/reset-password:
    parameters: [{name: user_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Admin], summary: "Reset-password form (set a new password directly, by hand) — superseded in the FE-6 Users console by the emailed reset-link action (POST /api/admin/users/{user_id}/reset-password); kept reachable, not deleted", responses: {"200": {description: HTML form}}}
    post: {tags: [Admin], summary: Set a new password for the user, responses: {"302": {description: Set}}}
  /admin/settings:
    get: {tags: [Admin], summary: "Site text + hero image form (tagline/about/contact/banner) — a real, separate settings surface from the FE-6 grouped console (GET /admin/config); see docs/FRONTEND_DESIGN.md's FE-6 entry", responses: {"200": {description: HTML form}}}
    post: {tags: [Admin], summary: Save settings / upload hero, responses: {"302": {description: Saved}}}
  /admin/backups/run:
    post: {tags: [Admin], summary: "Create, verify, and (if configured) upload a backup via a plain form POST + flash messages — superseded in the FE-6 Backups console by POST /api/admin/backups/run (shows the report inline); kept reachable, not deleted", responses: {"302": {description: Report via flash messages}}}
  /admin/backups/{filename}/download:
    parameters: [{name: filename, in: path, required: true, schema: {type: string}, description: Must match a known backup name — no path tricks}]
    get: {tags: [Admin], summary: Download a backup zip, responses: {"200": {description: zip bytes}, "404": {description: Unknown filename}}}

  # ============================================================================
  # GENEALOGY JSON API (WP2) — the contract Cowork builds WP3 against.
  # Every write (POST/PUT/DELETE) needs the Contributor role + an X-CSRFToken header. DELETE is soft (ADR-0001).
  # Standard responses: 200/201 ok, 204 deleted, 400 validation, 401 not logged
  # in, 403 wrong role, 404 missing, 409 duplicate link.
  # ============================================================================

  # --- Individuals + Names ----------------------------------------------------
  /api/individuals:
    get:
      tags: [Individuals]
      summary: List individuals (light rows — name + vitals + a place)
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {individuals: {type: array, items: {$ref: '#/components/schemas/PersonListItem'}}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}
    post:
      tags: [Individuals]
      summary: Create an individual (optional inline primary `name` object)
      requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Individual'}}}}
      responses: {"201": {description: Created, content: {application/json: {schema: {$ref: '#/components/schemas/Individual'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "401": {$ref: '#/components/responses/Unauthorized'}, "403": {$ref: '#/components/responses/Forbidden'}}
  /api/individuals/{individual_id}:
    parameters: [{name: individual_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Individuals], summary: One individual with all names, responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Individual'}}}}, "404": {$ref: '#/components/responses/NotFound'}}}
    put: {tags: [Individuals], summary: Update fields (sex/living/restriction/gedcom_xref), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Individual'}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}}
    delete: {tags: [Individuals], summary: Soft-delete the individual (recoverable; names + attachments preserved), responses: {"204": {description: Deleted}, "403": {$ref: '#/components/responses/Forbidden'}, "404": {$ref: '#/components/responses/NotFound'}}}
  /api/individuals/{individual_id}/names:
    parameters: [{name: individual_id, in: path, required: true, schema: {type: integer}}]
    post: {tags: [Individuals], summary: Add a name (needs a given or surname), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Name'}}}}, responses: {"201": {description: Created, content: {application/json: {schema: {$ref: '#/components/schemas/Name'}}}}, "400": {$ref: '#/components/responses/BadRequest'}}}
  /api/names/{name_id}:
    parameters: [{name: name_id, in: path, required: true, schema: {type: integer}}]
    put: {tags: [Individuals], summary: Update a name (is_primary steals primary from the others), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Name'}}}}, responses: {"200": {description: Updated}, "404": {$ref: '#/components/responses/NotFound'}}}
    delete: {tags: [Individuals], summary: Soft-delete a name (recoverable), responses: {"204": {description: Deleted}, "404": {$ref: '#/components/responses/NotFound'}}}

  # --- Families + Children ----------------------------------------------------
  /api/families:
    get: {tags: [Families], summary: List families, responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {families: {type: array, items: {$ref: '#/components/schemas/Family'}}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}}
    post: {tags: [Families], summary: Create a family (partner ids must exist), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Family'}}}}, responses: {"201": {description: Created, content: {application/json: {schema: {$ref: '#/components/schemas/Family'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/families/{family_id}:
    parameters: [{name: family_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Families], summary: One family with children, responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Family'}}}}, "404": {$ref: '#/components/responses/NotFound'}}}
    put: {tags: [Families], summary: Update partners / gedcom_xref, requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Family'}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}}}
    delete: {tags: [Families], summary: Soft-delete the family (recoverable; children + attachments preserved), responses: {"204": {description: Deleted}, "404": {$ref: '#/components/responses/NotFound'}}}
  /api/families/{family_id}/children:
    parameters: [{name: family_id, in: path, required: true, schema: {type: integer}}]
    post: {tags: [Families], summary: "Add a child link (child_id required; pedigree_type: birth|adopted|foster|step)", requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/FamilyChild'}}}}, responses: {"201": {description: Linked}, "400": {$ref: '#/components/responses/BadRequest'}, "409": {description: Child already in this family}}}
  /api/families/{family_id}/children/{child_id}:
    parameters: [{name: family_id, in: path, required: true, schema: {type: integer}}, {name: child_id, in: path, required: true, schema: {type: integer}}]
    put: {tags: [Families], summary: "Update pedigree_type/child_order on an active child link (one 'update' audit entry)", requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/FamilyChild'}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}, "404": {$ref: '#/components/responses/NotFound'}}}
    delete: {tags: [Families], summary: Remove a child link, responses: {"204": {description: Removed}, "404": {$ref: '#/components/responses/NotFound'}}}

  # --- Events -----------------------------------------------------------------
  /api/events:
    get:
      tags: [Events]
      summary: List events (optionally filtered to one subject), timeline-ordered
      parameters: [{name: subject_type, in: query, schema: {type: string, enum: [individual, family]}}, {name: subject_id, in: query, schema: {type: integer}}]
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {events: {type: array, items: {$ref: '#/components/schemas/Event'}}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}
    post: {tags: [Events], summary: Create an event (subject_type/subject_id + event_tag required), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Event'}}}}, responses: {"201": {description: Created, content: {application/json: {schema: {$ref: '#/components/schemas/Event'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/events/{event_id}:
    parameters: [{name: event_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Events], summary: One event, responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Event'}}}}, "404": {$ref: '#/components/responses/NotFound'}}}
    put: {tags: [Events], summary: Update an event, requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Event'}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}}}
    delete: {tags: [Events], summary: Soft-delete an event (recoverable), responses: {"204": {description: Deleted}, "404": {$ref: '#/components/responses/NotFound'}}}

  # --- Places -----------------------------------------------------------------
  /api/places:
    get: {tags: [Places], summary: List places, responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {places: {type: array, items: {$ref: '#/components/schemas/Place'}}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}}
    post: {tags: [Places], summary: Create a place (full_name required), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Place'}}}}, responses: {"201": {description: Created, content: {application/json: {schema: {$ref: '#/components/schemas/Place'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/places/{place_id}:
    parameters: [{name: place_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Places], summary: One place, responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Place'}}}}, "404": {$ref: '#/components/responses/NotFound'}}}
    put: {tags: [Places], summary: Update a place, requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Place'}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}}}
    delete: {tags: [Places], summary: Delete a place (events that used it are detached), responses: {"204": {description: Deleted}, "404": {$ref: '#/components/responses/NotFound'}}}

  # --- Sources / Repositories / Citations -------------------------------------
  /api/repositories:
    get: {tags: [Sources], summary: List repositories, responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {repositories: {type: array, items: {$ref: '#/components/schemas/Repository'}}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}}
    post: {tags: [Sources], summary: Create a repository (name required), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Repository'}}}}, responses: {"201": {description: Created}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/repositories/{repo_id}:
    parameters: [{name: repo_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Sources], summary: One repository, responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Repository'}}}}, "404": {$ref: '#/components/responses/NotFound'}}}
    put: {tags: [Sources], summary: Update a repository, requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Repository'}}}}, responses: {"200": {description: Updated}}}
    delete: {tags: [Sources], summary: Delete a repository (its sources are detached), responses: {"204": {description: Deleted}, "404": {$ref: '#/components/responses/NotFound'}}}
  /api/sources:
    get: {tags: [Sources], summary: List sources, responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {sources: {type: array, items: {$ref: '#/components/schemas/Source'}}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}}
    post: {tags: [Sources], summary: Create a source (title required), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Source'}}}}, responses: {"201": {description: Created}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/sources/{source_id}:
    parameters: [{name: source_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Sources], summary: One source, responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Source'}}}}, "404": {$ref: '#/components/responses/NotFound'}}}
    put: {tags: [Sources], summary: Update a source, requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Source'}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}}}
    delete: {tags: [Sources], summary: Soft-delete a source (recoverable; citations preserved), responses: {"204": {description: Deleted}, "404": {$ref: '#/components/responses/NotFound'}}}
  /api/citations:
    get:
      tags: [Sources]
      summary: List citations (optionally for one subject)
      parameters: [{name: subject_type, in: query, schema: {type: string, enum: [individual, family, event, name]}}, {name: subject_id, in: query, schema: {type: integer}}]
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {citations: {type: array, items: {$ref: '#/components/schemas/Citation'}}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}
    post: {tags: [Sources], summary: Create a citation (source_id + subject required; quality 0–3), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Citation'}}}}, responses: {"201": {description: Created}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/citations/{citation_id}:
    parameters: [{name: citation_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Sources], summary: One citation, responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Citation'}}}}, "404": {$ref: '#/components/responses/NotFound'}}}
    put: {tags: [Sources], summary: Update a citation, requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Citation'}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}}}
    delete: {tags: [Sources], summary: Soft-delete a citation (recoverable), responses: {"204": {description: Deleted}, "404": {$ref: '#/components/responses/NotFound'}}}

  # --- Media ------------------------------------------------------------------
  /api/media:
    get:
      tags: [Media]
      summary: List media (optionally for one subject; order by upload or capture date)
      parameters: [{name: subject_type, in: query, schema: {type: string, enum: [individual, family, event]}}, {name: subject_id, in: query, schema: {type: integer}}, {name: order_by, in: query, schema: {type: string, enum: [uploaded, capture], default: uploaded}, description: "capture = when the photo was taken"}]
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {media: {type: array, items: {$ref: '#/components/schemas/Media'}}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}
    post:
      tags: [Media]
      summary: Upload an image (multipart); EXIF/GPS stripped, stored outside web root
      requestBody: {content: {multipart/form-data: {schema: {type: object, required: [file], properties: {file: {type: string, format: binary}, title: {type: string}, description: {type: string}, subject_type: {type: string}, subject_id: {type: integer}}}}}}
      responses: {"201": {description: Created, content: {application/json: {schema: {$ref: '#/components/schemas/Media'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}
  /api/media/{media_id}:
    parameters: [{name: media_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Media], summary: One media object (with links), responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Media'}}}}, "404": {$ref: '#/components/responses/NotFound'}}}
    put: {tags: [Media], summary: Update metadata (title/description/gedcom_xref; bytes are immutable), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Media'}}}}, responses: {"200": {description: Updated}}}
    delete: {tags: [Media], summary: Soft-delete the media object (recoverable; files kept on disk), responses: {"204": {description: Deleted}, "404": {$ref: '#/components/responses/NotFound'}}}
  /api/media/{media_id}/file:
    parameters: [{name: media_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Media], summary: Full image bytes (login-walled), responses: {"200": {description: image bytes}, "401": {$ref: '#/components/responses/Unauthorized'}, "404": {$ref: '#/components/responses/NotFound'}}}
  /api/media/{media_id}/thumb:
    parameters: [{name: media_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Media], summary: Thumbnail bytes (login-walled), responses: {"200": {description: image bytes}, "404": {$ref: '#/components/responses/NotFound'}}}
  /api/media/{media_id}/links:
    parameters: [{name: media_id, in: path, required: true, schema: {type: integer}}]
    post: {tags: [Media], summary: Attach the photo to a subject, requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Link'}}}}, responses: {"201": {description: Linked}, "400": {$ref: '#/components/responses/BadRequest'}, "409": {description: Already linked}}}
  /api/media/{media_id}/links/{subject_type}/{subject_id}:
    parameters: [{name: media_id, in: path, required: true, schema: {type: integer}}, {name: subject_type, in: path, required: true, schema: {type: string}}, {name: subject_id, in: path, required: true, schema: {type: integer}}]
    delete: {tags: [Media], summary: Remove an attachment, responses: {"204": {description: Removed}, "404": {$ref: '#/components/responses/NotFound'}}}

  # --- Notes ------------------------------------------------------------------
  /api/notes:
    get:
      tags: [Notes]
      summary: List notes (optionally for one subject), newest first
      parameters: [{name: subject_type, in: query, schema: {type: string, enum: [individual, family, event]}}, {name: subject_id, in: query, schema: {type: integer}}]
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {notes: {type: array, items: {$ref: '#/components/schemas/Note'}}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}
    post: {tags: [Notes], summary: Write a note (content required; author set from the session; optional inline subject), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Note'}}}}, responses: {"201": {description: Created, content: {application/json: {schema: {$ref: '#/components/schemas/Note'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/notes/{note_id}:
    parameters: [{name: note_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Notes], summary: One note (with links), responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Note'}}}}, "404": {$ref: '#/components/responses/NotFound'}}}
    put: {tags: [Notes], summary: Update a note (title/content/content_type/is_shared), requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Note'}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}}}
    delete: {tags: [Notes], summary: Soft-delete a note (recoverable; links preserved), responses: {"204": {description: Deleted}, "404": {$ref: '#/components/responses/NotFound'}}}
  /api/notes/{note_id}/links:
    parameters: [{name: note_id, in: path, required: true, schema: {type: integer}}]
    post: {tags: [Notes], summary: Attach the note to a subject, requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Link'}}}}, responses: {"201": {description: Linked}, "400": {$ref: '#/components/responses/BadRequest'}, "409": {description: Already linked}}}
  /api/notes/{note_id}/links/{subject_type}/{subject_id}:
    parameters: [{name: note_id, in: path, required: true, schema: {type: integer}}, {name: subject_type, in: path, required: true, schema: {type: string}}, {name: subject_id, in: path, required: true, schema: {type: integer}}]
    delete: {tags: [Notes], summary: Remove an attachment, responses: {"204": {description: Removed}, "404": {$ref: '#/components/responses/NotFound'}}}

  # --- Search -----------------------------------------------------------------
  /api/search:
    get:
      tags: [Search]
      summary: People by name + filters, and full-text over notes (§12)
      parameters:
        - {name: q, in: query, schema: {type: string}, description: free text — matches names AND notes}
        - {name: given, in: query, schema: {type: string}}
        - {name: surname, in: query, schema: {type: string}}
        - {name: sex, in: query, schema: {type: string, enum: [M, F, X, U]}}
        - {name: living, in: query, schema: {type: boolean}}
        - {name: birth_from, in: query, schema: {type: integer}}
        - {name: birth_to, in: query, schema: {type: integer}}
        - {name: place, in: query, schema: {type: string}}
      responses: {"200": {description: Grouped results, content: {application/json: {schema: {$ref: '#/components/schemas/SearchResults'}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}

  # --- Account & Security self-service (FE-5) ---------------------------------
  /api/me:
    get: {tags: [Account], summary: "My own account snapshot (display_name/email/role/email_verified_at/timezone/individual_id)", responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/MeAccount'}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}}
    put: {tags: [Account], summary: "Self-serve edit — display_name/timezone ONLY (role and email are not writable here)", requestBody: {content: {application/json: {schema: {type: object, properties: {display_name: {type: string}, timezone: {type: string, nullable: true, description: "IANA zone name, or null for the site default"}}}}}}, responses: {"200": {description: Updated, content: {application/json: {schema: {$ref: '#/components/schemas/MeAccount'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "401": {$ref: '#/components/responses/Unauthorized'}}}
  /api/me/contributions:
    get:
      tags: [Account]
      summary: "My Contributions dashboard — MY OWN audit rows only (no actor_id parameter exists; that's the Curator-only /api/activity)"
      parameters:
        - {name: action, in: query, schema: {type: string}}
        - {name: subject_type, in: query, schema: {type: string}}
        - {name: page, in: query, schema: {type: integer, default: 1}}
        - {name: per_page, in: query, schema: {type: integer, default: 50}}
      responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/MyContributionsPage'}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}
  /api/me/change-email:
    post: {tags: [Account], summary: "Self-serve change-email: requires current_password; the address only changes when the emailed verification link is clicked", requestBody: {required: true, content: {application/json: {schema: {type: object, required: [new_email, current_password], properties: {new_email: {type: string}, current_password: {type: string}}}}}}, responses: {"200": {description: "Verification email sent", content: {application/json: {schema: {type: object, properties: {status: {type: string}, pending_email: {type: string}}}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {description: Wrong current password}, "503": {description: Email not configured}}}
  /api/me/delete:
    post: {tags: [Account], summary: "\"Delete my account\" = anonymize the contributor, never erase — genealogy data, contributions, and audit rows are untouched", requestBody: {required: true, content: {application/json: {schema: {type: object, required: [current_password], properties: {current_password: {type: string}}}}}}, responses: {"200": {description: "Anonymized and logged out", content: {application/json: {schema: {type: object, properties: {status: {type: string}}}}}}, "403": {description: Wrong current password}, "409": {description: "You're the last active admin"}}}

  # --- Account ↔ Person link + tree root (ADR-0002) ---------------------------
  /api/me/person:
    get: {tags: [Account], summary: The current user's linked individual (null if unlinked), responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {individual: {$ref: '#/components/schemas/Individual', nullable: true}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}}
    put: {tags: [Account], summary: "Edit your OWN person record (self-authoring; requires a link)", requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Individual'}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}, "401": {$ref: '#/components/responses/Unauthorized'}}}
  /api/me/verify-email:
    post: {tags: [Account], summary: "Email myself a verification link for my own address (§9)", responses: {"200": {description: "{status: sent|already_verified}"}, "401": {$ref: '#/components/responses/Unauthorized'}, "503": {description: Email not configured}}}
  /api/tree/root:
    get: {tags: [Account], summary: "Where the tree opens: the linked person, else the oldest ancestor", responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/TreeRoot'}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}}
  /api/users/{user_id}/individual:
    parameters: [{name: user_id, in: path, required: true, schema: {type: integer}}]
    put: {tags: [Account], summary: "Admin: link an account to a person (permission: link_account)", requestBody: {required: true, content: {application/json: {schema: {type: object, required: [individual_id], properties: {individual_id: {type: integer}}}}}}, responses: {"200": {description: Linked, content: {application/json: {schema: {$ref: '#/components/schemas/AccountLink'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}, "404": {$ref: '#/components/responses/NotFound'}, "409": {description: That person is already linked to another account}}}
    delete: {tags: [Account], summary: "Admin: unlink an account (permission: link_account)", responses: {"200": {description: Unlinked, content: {application/json: {schema: {$ref: '#/components/schemas/AccountLink'}}}}, "403": {$ref: '#/components/responses/Forbidden'}, "404": {$ref: '#/components/responses/NotFound'}}}

  # --- Tree traversal + views (Master Plan §4) --------------------------------
  /api/individuals/{individual_id}/pedigree:
    parameters: [{name: individual_id, in: path, required: true, schema: {type: integer}}]
    get:
      tags: [Tree]
      summary: A graph slice from any node (ancestors/descendants, depth, lazy-expand)
      parameters:
        - {name: direction, in: query, schema: {type: string, enum: [ancestors, descendants, both], default: both}}
        - {name: depth, in: query, schema: {type: integer, default: 3, minimum: 1, maximum: 6}, description: generations each way}
      responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/PedigreeGraph'}}}}, "401": {$ref: '#/components/responses/Unauthorized'}, "404": {$ref: '#/components/responses/NotFound'}}
  /api/individuals/{a_id}/relationship/{b_id}:
    parameters: [{name: a_id, in: path, required: true, schema: {type: integer}}, {name: b_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Tree], summary: Shortest blood path + plain-English label (B relative to A), responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/RelationshipResult'}}}}, "401": {$ref: '#/components/responses/Unauthorized'}, "404": {$ref: '#/components/responses/NotFound'}}}
  /api/stats:
    get: {tags: [Tree], summary: Aggregate counts + storage (Home + Admin dashboard), responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Stats'}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}}
  /api/on-this-day:
    get:
      tags: [Tree]
      summary: Family births/marriages/deaths sharing today's (or a given) date
      parameters: [{name: month, in: query, schema: {type: integer, minimum: 1, maximum: 12}}, {name: day, in: query, schema: {type: integer, minimum: 1, maximum: 31}}]
      responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/OnThisDay'}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}
  /api/historical-events:
    get:
      tags: [Tree]
      summary: World/US almanac (each with a description) to blend into the timeline
      parameters: [{name: scope, in: query, schema: {type: string, enum: [US, world]}}, {name: year_from, in: query, schema: {type: integer}}, {name: year_to, in: query, schema: {type: integer}}]
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {historical_events: {type: array, items: {$ref: '#/components/schemas/HistoricalEvent'}}}}}}}, "401": {$ref: '#/components/responses/Unauthorized'}}

  # --- Admin actions (§9, §10) ------------------------------------------------
  /api/admin/users:
    get: {tags: [AdminApi], summary: All accounts with role + linked-person status, responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {users: {type: array, items: {$ref: '#/components/schemas/AdminUser'}}}}}}}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/admin/users/{user_id}/reset-password:
    parameters: [{name: user_id, in: path, required: true, schema: {type: integer}}]
    post: {tags: [AdminApi], summary: Email the user a password-reset link, responses: {"200": {description: "{status: reset_email_sent}"}, "403": {$ref: '#/components/responses/Forbidden'}, "404": {$ref: '#/components/responses/NotFound'}, "503": {description: Email not configured}}}
  /api/admin/users/{user_id}/change-email:
    parameters: [{name: user_id, in: path, required: true, schema: {type: integer}}]
    post:
      tags: [AdminApi]
      summary: "Secure change-email: verify new addr, notify both, force reset, step-up re-auth"
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [new_email, current_password], properties: {new_email: {type: string}, current_password: {type: string, description: the admin's OWN password (step-up)}}}}}}
      responses: {"200": {description: Changed, content: {application/json: {schema: {$ref: '#/components/schemas/AdminUser'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {description: Step-up re-auth failed / not admin}, "404": {$ref: '#/components/responses/NotFound'}, "503": {description: Email not configured}}
  /api/settings:
    get: {tags: [AdminApi], summary: Editable settings, grouped (branding/security/email/defaults), responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/Settings'}}}}, "403": {$ref: '#/components/responses/Forbidden'}}}
    put: {tags: [AdminApi], summary: Patch settings (coerced + validated; unknown keys ignored), requestBody: {content: {application/json: {schema: {type: object, additionalProperties: true}}}}, responses: {"200": {description: Updated, content: {application/json: {schema: {$ref: '#/components/schemas/Settings'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/admin/backups:
    get: {tags: [AdminApi], summary: Backup list + sizes, storage location, disk headroom, last/next run, schedule, responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/BackupOverview'}}}}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/admin/backups/run:
    post: {tags: [AdminApi], summary: Back up now (create + verify + off-site upload), responses: {"200": {description: Verification report}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/admin/backups/schedule:
    put: {tags: [AdminApi], summary: "Set the backup schedule (off|daily|weekly + hour)", requestBody: {content: {application/json: {schema: {type: object, properties: {schedule: {type: string, enum: [off, daily, weekly]}, hour: {type: integer, minimum: 0, maximum: 23}}}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}}}
  /api/admin/backups/restore:
    post:
      tags: [AdminApi]
      summary: "GUARDED restore: confirm + step-up; auto safety-backup taken first"
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [filename, current_password, confirm], properties: {filename: {type: string}, current_password: {type: string, description: step-up}, confirm: {type: boolean}}}}}}
      responses: {"200": {description: Restored (+ safety backup name)}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {description: Step-up failed}, "404": {$ref: '#/components/responses/NotFound'}}
  /api/permissions/matrix:
    get: {tags: [AdminApi], summary: Read-only role→permission map (permissions-as-data; §10), responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/PermissionMatrix'}}}}, "403": {$ref: '#/components/responses/Forbidden'}}}

  # --- Suggestions inbox + role-change requests (§5, §10) ---------------------
  /api/suggestions:
    post: {tags: [Inbox], summary: Submit a suggestion (any member), requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/Suggestion'}}}}, responses: {"201": {description: Created, content: {application/json: {schema: {$ref: '#/components/schemas/Suggestion'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "401": {$ref: '#/components/responses/Unauthorized'}}}
    get:
      tags: [Inbox]
      summary: The admin inbox — filter by status/topic, or the prioritized queue
      parameters: [{name: status, in: query, schema: {type: string, enum: [new, in_progress, done, declined]}}, {name: topic, in: query, schema: {type: string, enum: [idea, bug, photo_request, other]}}, {name: prioritized, in: query, schema: {type: boolean}, description: only items with a priority, ranked}]
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {suggestions: {type: array, items: {$ref: '#/components/schemas/Suggestion'}}}}}}}, "403": {$ref: '#/components/responses/Forbidden'}}
  /api/suggestions/{suggestion_id}:
    parameters: [{name: suggestion_id, in: path, required: true, schema: {type: integer}}]
    put: {tags: [Inbox], summary: "Admin triage: set status and/or priority (integer rank, or null)", requestBody: {content: {application/json: {schema: {$ref: '#/components/schemas/Suggestion'}}}}, responses: {"200": {description: Updated}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}, "404": {$ref: '#/components/responses/NotFound'}}}
  /api/role-requests:
    post: {tags: [Inbox], summary: "Request a role change (member); one pending request at a time", requestBody: {required: true, content: {application/json: {schema: {type: object, required: [requested_role], properties: {requested_role: {type: string, enum: [viewer, contributor, curator, admin]}}}}}}, responses: {"201": {description: Created, content: {application/json: {schema: {$ref: '#/components/schemas/RoleRequest'}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "409": {description: A pending request already exists}}}
    get:
      tags: [Inbox]
      summary: "Admin: list role requests (filter by status)"
      parameters: [{name: status, in: query, schema: {type: string, enum: [pending, approved, denied]}}]
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {role_requests: {type: array, items: {$ref: '#/components/schemas/RoleRequest'}}}}}}}, "403": {$ref: '#/components/responses/Forbidden'}}
  /api/role-requests/{request_id}/approve:
    parameters: [{name: request_id, in: path, required: true, schema: {type: integer}}]
    post: {tags: [Inbox], summary: "Admin: approve (applies the role change through the audit service)", responses: {"200": {description: Approved, content: {application/json: {schema: {$ref: '#/components/schemas/RoleRequest'}}}}, "403": {$ref: '#/components/responses/Forbidden'}, "404": {$ref: '#/components/responses/NotFound'}, "409": {description: Already decided}}}
  /api/role-requests/{request_id}/deny:
    parameters: [{name: request_id, in: path, required: true, schema: {type: integer}}]
    post: {tags: [Inbox], summary: "Admin: deny (no role change, decision recorded)", responses: {"200": {description: Denied, content: {application/json: {schema: {$ref: '#/components/schemas/RoleRequest'}}}}, "403": {$ref: '#/components/responses/Forbidden'}, "404": {$ref: '#/components/responses/NotFound'}, "409": {description: Already decided}}}

  # --- Write control: activity feed, restore, revert (ADR-0001) ---------------
  /api/activity:
    get:
      tags: [WriteControl]
      summary: The audit trail — paginated, filterable (Curator+; ADR-0001)
      parameters:
        - {name: action, in: query, schema: {type: string, enum: [create, update, delete, restore, revert]}}
        - {name: actor_id, in: query, schema: {type: integer}}
        - {name: subject_type, in: query, schema: {type: string}}
        - {name: date_from, in: query, schema: {type: string, format: date}}
        - {name: date_to, in: query, schema: {type: string, format: date}}
        - {name: page, in: query, schema: {type: integer, default: 1}}
        - {name: per_page, in: query, schema: {type: integer, default: 50, maximum: 200}}
      responses: {"200": {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/ActivityPage'}}}}, "401": {$ref: '#/components/responses/Unauthorized'}, "403": {$ref: '#/components/responses/Forbidden'}}
  /api/activity/feed:
    get:
      tags: [WriteControl]
      summary: "Friendly, ALL-MEMBERS recent-activity feed for Home — safe creates only, never deletes/reverts/account actions. Optional subject_type+subject_id (both or neither) scopes it to one subject, e.g. a Person Page"
      parameters: [{name: limit, in: query, schema: {type: integer, default: 20, maximum: 100}}, {name: subject_type, in: query, schema: {type: string, enum: [individual, name, family, event, source, citation, media, note]}}, {name: subject_id, in: query, schema: {type: integer}}]
      responses: {"200": {description: OK, content: {application/json: {schema: {type: object, properties: {activity: {type: array, items: {$ref: '#/components/schemas/MemberActivityEntry'}}}}}}}, "400": {$ref: '#/components/responses/BadRequest'}, "401": {$ref: '#/components/responses/Unauthorized'}}
  /api/restore:
    post:
      tags: [WriteControl]
      summary: Un-delete a soft-deleted record (permission: revert)
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [subject_type, subject_id], properties: {subject_type: {type: string, enum: [individual, name, family, event, source, citation, media, note]}, subject_id: {type: integer}}}}}}
      responses: {"200": {description: Restored (returns the row snapshot)}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}, "404": {$ref: '#/components/responses/NotFound'}}
  /api/audit/{audit_id}/revert:
    parameters: [{name: audit_id, in: path, required: true, schema: {type: integer}}]
    post:
      tags: [WriteControl]
      summary: Undo the change an audit entry describes (permission: revert)
      responses: {"200": {description: Reverted (result is the new snapshot, or null if now deleted)}, "400": {$ref: '#/components/responses/BadRequest'}, "403": {$ref: '#/components/responses/Forbidden'}, "404": {$ref: '#/components/responses/NotFound'}}

  # --- Views (WP4) — HTML pages; the data comes from the JSON API above ------
  /coming-soon:
    get:
      tags: [Views]
      summary: Shared "not built yet" placeholder for nav destinations this WP doesn't build
      parameters: [{name: feature, in: query, schema: {type: string}, description: display text only, never trusted for logic}]
      responses: {"200": {description: HTML page}}
  /people:
    get: {tags: [Views], summary: "Find/browse people (client-rendered against GET /api/search)", responses: {"200": {description: HTML page}}}
  /people/new:
    get: {tags: [Views], summary: "Register-a-person form (submits via JS to POST /api/individuals + /api/places + /api/events)", responses: {"200": {description: HTML page}}}
  /people/{individual_id}:
    parameters: [{name: individual_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Views], summary: "The Person Page (FE-2): 6 client-rendered tabs — Story/Relationships/Timeline/Photos/Details/Sources — over the JSON API above", responses: {"200": {description: HTML page}}}
  /tree:
    get:
      tags: [Views]
      summary: "The Pedigree view (FE-3): vertical ancestor tree, client-rendered against GET /api/tree/root + GET /api/individuals/{id}/pedigree"
      parameters: [{name: root, in: query, schema: {type: integer}, description: "recenter on this individual instead of the default tree root; shareable/back-navigable"}]
      responses: {"200": {description: HTML page}}
  /tree/family/{family_id}:
    parameters: [{name: family_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Views], summary: "The Family Group sheet (FE-3): both partners, marriage/divorce events, children — client-rendered against GET /api/families/{family_id}", responses: {"200": {description: HTML page}}}
  /tree/relationship:
    get:
      tags: [Views]
      summary: "The Relationship view (FE-3): two person pickers + the shortest blood path, client-rendered against GET /api/individuals/{a_id}/relationship/{b_id}"
      parameters:
        - {name: a, in: query, schema: {type: integer}, description: "pre-fill person A (defaults to GET /api/me/person when omitted)"}
        - {name: b, in: query, schema: {type: integer}, description: pre-fill person B}
      responses: {"200": {description: HTML page}}
  /memories:
    get:
      tags: [Views]
      summary: "Memories (FE-4): Chronological album — every photo by capture date (falls back to upload date), client-rendered against GET /api/media?order_by=capture. Also the section's photo-upload entry point."
      parameters: [{name: photo, in: query, schema: {type: integer}, description: "FE-5: deep-link straight to one photo's detail panel (GET /api/media/{id}) — used by My Contributions' photo rows"}]
      responses: {"200": {description: HTML page}}
  /memories/person:
    get:
      tags: [Views]
      summary: "By Person album (FE-4): pick a person, see every photo linked to them — GET /api/media?subject_type=individual&subject_id="
      parameters: [{name: person, in: query, schema: {type: integer}, description: "pre-fill the picker; shareable/bookmarkable"}]
      responses: {"200": {description: HTML page}}
  /memories/family:
    get:
      tags: [Views]
      summary: "By Family album (FE-4): pick a family, see photos linked to the family, its own events, and its members' events — a client-side aggregation over GET /api/media's subject filters"
      parameters: [{name: family, in: query, schema: {type: integer}, description: "pre-fill the picker; shareable/bookmarkable"}]
      responses: {"200": {description: HTML page}}
  /memories/event:
    get:
      tags: [Views]
      summary: "By Event album (FE-4): every event with at least one linked photo, grouped — a whole-archive view over GET /api/events + GET /api/media?subject_type=event"
      responses: {"200": {description: HTML page}}
  /memories/stories:
    get:
      tags: [Views]
      summary: "Stories (FE-4): the memory-blog lane — every note, newest first, client-rendered against GET /api/notes"
      responses: {"200": {description: HTML page}}
  /memories/stories/new:
    get:
      tags: [Views]
      summary: "Write a Story (FE-4, Contributor+): title/content/format/shared-note + an optional who-it's-about link picker, submits via JS to POST /api/notes"
      responses: {"200": {description: HTML page}}
  /memories/stories/{note_id}:
    parameters: [{name: note_id, in: path, required: true, schema: {type: integer}}]
    get: {tags: [Views], summary: "One story's read view (FE-4): rendered Markdown + navigable links, client-rendered against GET /api/notes/{note_id}", responses: {"200": {description: HTML page}}}
  /search:
    get:
      tags: [Views]
      summary: "Quick + Advanced search (FE-4, Master Plan §12): one page, hash-switched (#quick/#advanced), client-rendered against GET /api/search (+ GET /api/families for the quick search's family matches)"
      responses: {"200": {description: HTML page}}
  /account:
    get:
      tags: [Views]
      summary: "Account & Security (FE-5): Profile/Role/Email/Password/Delete, client-rendered against GET /api/me + the rest of the Account tag. Own account only — no id in the URL."
      responses: {"200": {description: HTML page}}
  /account/contributions:
    get:
      tags: [Views]
      summary: "My Contributions (FE-5): summary cards + a paginated, filterable list of the caller's own audit rows, client-rendered against GET /api/me/contributions. Own rows only — no id in the URL."
      responses: {"200": {description: HTML page}}

  # --- Admin Console (FE-6): the native-Chronicle rebuild of the admin
  # surface. Every page below is a thin shell, client-rendered against the
  # AdminApi/Inbox/WriteControl/Tree tags above (Admin-only except Activity,
  # which is Curator+ — see app/routes/admin.py). The legacy server-rendered
  # flows this rebuild kept as-is (create/edit account, the direct-password-
  # reset form, the site-text-and-hero form, the flash-redirect backup-run
  # form) stay documented under the Admin tag, above.
  # -------------------------------------------------------------------------
  /admin:
    get:
      tags: [Views]
      summary: "Admin Console dashboard (FE-6): aggregate counts + storage, backup health, and the pending suggestions/role-request queues, each with a jump to its own section — client-rendered against GET /api/stats + GET /api/admin/backups + GET /api/suggestions + GET /api/role-requests."
      responses: {"200": {description: HTML page}, "403": {description: Admins only}}
  /admin/users:
    get:
      tags: [Views]
      summary: "Users (FE-6): every account (role, linked person, active/verified state), plus email-a-reset-link / secure change-email / link-unlink-person actions and the read-only role→permission matrix — client-rendered against GET /api/admin/users + GET /api/permissions/matrix + the AdminApi/Account actions. Replaces the old static table at this same URL."
      responses: {"200": {description: HTML page}, "403": {description: Admins only}}
  /admin/suggestions:
    get:
      tags: [Views]
      summary: "Suggestions Inbox (FE-6): a filterable triage list (status/topic/prioritized), edits saved inline per row — client-rendered against GET/PUT /api/suggestions."
      responses: {"200": {description: HTML page}, "403": {description: Admins only}}
  /admin/role-requests:
    get:
      tags: [Views]
      summary: "Role Requests (FE-6): the pending queue (approve/deny) plus decided history — client-rendered against GET /api/role-requests + its approve/deny actions."
      responses: {"200": {description: HTML page}, "403": {description: Admins only}}
  /admin/config:
    get:
      tags: [Views]
      summary: "Settings (FE-6): the grouped config-as-data settings (branding/defaults/security/email) — client-rendered against GET/PUT /api/settings. A separate page from GET /admin/settings (tagline/About/banner) — two independent settings surfaces already existed in the backend; see docs/FRONTEND_DESIGN.md's FE-6 entry."
      responses: {"200": {description: HTML page}, "403": {description: Admins only}}
  /admin/backups:
    get:
      tags: [Views]
      summary: "Backups (FE-6): overview, back-up-now with its verification report, the schedule editor, and the guarded restore (the gravest action in the app: step-up + explicit confirm, safety backup taken first) — client-rendered against GET /api/admin/backups + POST /run + PUT /schedule + POST /restore. Replaces the old static list at this same URL."
      responses: {"200": {description: HTML page}, "403": {description: Admins only}}
  /admin/activity:
    get:
      tags: [Views]
      summary: "Activity (FE-6): the full audit trail, paginated and filterable, with per-entry revert/restore — client-rendered against GET /api/activity + POST /api/restore + POST /api/audit/{audit_id}/revert. CURATOR+, not Admin-only (§10 — Curator holds `revert`; BLOCKERS.md 2026-07-03 RESOLVED). Replaces the old static table at this same URL."
      responses: {"200": {description: HTML page}, "403": {description: Logged in below Curator}}

components:
  responses:
    Unauthorized: {description: Not logged in, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
    Forbidden: {description: Logged in but lacking the required role, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
    NotFound: {description: No such record, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
    BadRequest: {description: Validation failed, content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}}
  schemas:
    Error:
      type: object
      properties:
        error: {type: string}
        fields: {type: object, additionalProperties: {type: string}, description: per-field problems (present on validation errors)}
    AuditEntry:
      type: object
      description: One row of the write-control audit trail (ADR-0001).
      properties:
        id: {type: integer, readOnly: true}
        action: {type: string, description: create|update|delete|restore|revert (or a security/admin verb)}
        actor_id: {type: integer, nullable: true}
        actor: {type: string, nullable: true, description: the actor's display name}
        subject_type: {type: string, example: individual}
        subject_id: {type: integer, nullable: true}
        detail: {type: string}
        created_at: {type: string, format: date-time, readOnly: true}
    ActivityPage:
      type: object
      description: A page of audit entries plus pagination metadata.
      properties:
        activity: {type: array, items: {$ref: '#/components/schemas/AuditEntry'}}
        page: {type: integer}
        per_page: {type: integer}
        total: {type: integer}
        pages: {type: integer}
    MemberActivityEntry:
      type: object
      description: One row of the friendly, all-members Home activity feed — a safe CREATE only (never a delete/revert/account action).
      properties:
        id: {type: integer, readOnly: true}
        text: {type: string, example: "Jane added a photo: Family reunion 1962"}
        subject_type: {type: string, enum: [individual, media, note]}
        subject_id: {type: integer}
        created_at: {type: string, format: date-time, readOnly: true}
    MeAccount:
      type: object
      description: The current user's own account snapshot (FE-5 Account & Security page).
      properties:
        id: {type: integer, readOnly: true}
        display_name: {type: string}
        email: {type: string, readOnly: true, description: not writable via PUT /api/me — see /api/me/change-email}
        role: {type: string, readOnly: true, description: not writable via PUT /api/me — admin-only}
        email_verified_at: {type: string, format: date-time, nullable: true}
        timezone: {type: string, nullable: true, description: "IANA zone name, or null for the site default"}
        individual_id: {type: integer, nullable: true}
        pending_email: {type: string, nullable: true, readOnly: true, description: unverified address from a pending change-email request, or null — set via /api/me/change-email, cleared when verification completes}
    MyContributionsPage:
      type: object
      description: The My Contributions dashboard — one member's own audit rows, paginated, plus header-card summary counts.
      properties:
        activity: {type: array, items: {$ref: '#/components/schemas/AuditEntry'}}
        page: {type: integer}
        per_page: {type: integer}
        total: {type: integer}
        pages: {type: integer}
        summary:
          type: object
          properties:
            by_action: {type: object, additionalProperties: {type: integer}}
            by_subject_type: {type: object, additionalProperties: {type: integer}}
    AccountLink:
      type: object
      description: The Account↔Person link state for one user (ADR-0002).
      properties:
        user_id: {type: integer, readOnly: true}
        individual_id: {type: integer, nullable: true}
        individual: {$ref: '#/components/schemas/Individual', nullable: true}
    TreeRoot:
      type: object
      description: Where the family tree should open for the current user (ADR-0002).
      properties:
        individual_id: {type: integer, nullable: true}
        source: {type: string, enum: [linked, oldest_ancestor, empty], description: how the root was chosen}
        individual: {$ref: '#/components/schemas/Individual', nullable: true}
    PersonListItem:
      type: object
      description: The lightweight person row shared by the People list, search, and tree nodes.
      properties:
        id: {type: integer}
        primary_name: {type: string, nullable: true}
        sex: {type: string, nullable: true}
        living: {type: boolean}
        birth_year: {type: integer, nullable: true}
        death_year: {type: integer, nullable: true}
        birth_place: {type: string, nullable: true}
    PedigreeGraph:
      type: object
      description: A bounded graph slice — nodes + edges — for lazy-expandable tree rendering.
      properties:
        root_id: {type: integer}
        direction: {type: string, enum: [ancestors, descendants, both]}
        depth: {type: integer}
        nodes:
          type: array
          items:
            allOf:
              - {$ref: '#/components/schemas/PersonListItem'}
              - type: object
                properties:
                  has_ancestors: {type: boolean, description: more parents exist beyond the slice (lazy-fetch hint)}
                  has_descendants: {type: boolean}
        edges:
          type: array
          items:
            type: object
            properties:
              type: {type: string, enum: [parent-child, partner]}
              family_id: {type: integer}
              parent_id: {type: integer, nullable: true}
              child_id: {type: integer, nullable: true}
              partner1_id: {type: integer, nullable: true}
              partner2_id: {type: integer, nullable: true}
    RelationshipResult:
      type: object
      description: Shortest blood path between two people + a label describing B relative to A.
      properties:
        a: {type: integer}
        b: {type: integer}
        relationship: {type: string, example: 1st cousin once removed}
        nca_id: {type: integer, nullable: true, description: nearest common ancestor}
        distance_a: {type: integer, nullable: true}
        distance_b: {type: integer, nullable: true}
        path: {type: array, items: {type: integer}, description: individual ids from A through the NCA to B}
    Stats:
      type: object
      description: Aggregate counts + storage for the dashboards.
      properties:
        counts:
          type: object
          additionalProperties: {type: integer}
          description: people, families, events, sources, citations, photos, notes, places, repositories, users
        storage_bytes: {type: integer}
    OnThisDay:
      type: object
      description: Family births/marriages/deaths sharing a calendar day.
      properties:
        month: {type: integer}
        day: {type: integer}
        births: {type: array, items: {$ref: '#/components/schemas/Anniversary'}}
        marriages: {type: array, items: {$ref: '#/components/schemas/Anniversary'}}
        deaths: {type: array, items: {$ref: '#/components/schemas/Anniversary'}}
    Anniversary:
      type: object
      properties:
        event_id: {type: integer}
        subject_type: {type: string}
        subject_id: {type: integer}
        who: {type: string, nullable: true}
        year: {type: integer, nullable: true}
        date_original: {type: string, nullable: true}
        place: {type: string, nullable: true}
    AdminUser:
      type: object
      description: An account row for the admin Users tab.
      properties:
        id: {type: integer}
        email: {type: string}
        display_name: {type: string}
        role: {type: string, enum: [viewer, contributor, curator, admin]}
        is_active: {type: boolean}
        email_verified: {type: boolean}
        individual_id: {type: integer, nullable: true}
        linked: {type: boolean, description: whether the account is linked to a person}
        locked: {type: boolean, description: currently locked out}
        created_at: {type: string, format: date-time}
    Settings:
      type: object
      description: Editable settings grouped for the admin panel (secrets excluded).
      properties:
        branding: {type: object, additionalProperties: true}
        security: {type: object, additionalProperties: true}
        email: {type: object, additionalProperties: true}
        defaults: {type: object, additionalProperties: true}
    BackupOverview:
      type: object
      properties:
        backups:
          type: array
          items:
            type: object
            properties:
              filename: {type: string}
              bytes: {type: integer}
              created_at: {type: string, format: date-time}
        storage_location: {type: string}
        offsite_bucket: {type: string, nullable: true}
        disk_free_bytes: {type: integer, nullable: true}
        disk_total_bytes: {type: integer, nullable: true}
        last_run: {type: string, format: date-time, nullable: true}
        next_run: {type: string, format: date-time, nullable: true}
        schedule: {type: string, enum: [off, daily, weekly]}
        schedule_hour: {type: integer}
    PermissionMatrix:
      type: object
      description: The permissions-as-data map (§10) — role → {permission → bool}.
      properties:
        permissions: {type: array, items: {type: string}}
        matrix:
          type: object
          additionalProperties: {type: object, additionalProperties: {type: boolean}}
    Suggestion:
      type: object
      description: A member suggestion in the admin inbox (§5).
      properties:
        id: {type: integer, readOnly: true}
        author_user_id: {type: integer, nullable: true, readOnly: true}
        author: {type: string, nullable: true, readOnly: true}
        topic: {type: string, enum: [idea, bug, photo_request, other]}
        body: {type: string}
        status: {type: string, enum: [new, in_progress, done, declined]}
        priority: {type: integer, nullable: true, description: admin rank (lower = higher); null = untriaged}
        created_at: {type: string, format: date-time, readOnly: true}
        updated_at: {type: string, format: date-time, readOnly: true}
    RoleRequest:
      type: object
      description: A member's request for a role change (§10).
      properties:
        id: {type: integer, readOnly: true}
        user_id: {type: integer, readOnly: true}
        user: {type: string, nullable: true, readOnly: true}
        requested_role: {type: string, enum: [viewer, contributor, curator, admin]}
        status: {type: string, enum: [pending, approved, denied], readOnly: true}
        decided_by_user_id: {type: integer, nullable: true, readOnly: true}
        decided_by: {type: string, nullable: true, readOnly: true}
        created_at: {type: string, format: date-time, readOnly: true}
        decided_at: {type: string, format: date-time, nullable: true, readOnly: true}
    HistoricalEvent:
      type: object
      description: One world/US almanac entry (reference data) for timeline context.
      properties:
        id: {type: integer}
        year: {type: integer}
        date_sort: {type: string, nullable: true}
        title: {type: string}
        description: {type: string}
        scope: {type: string, enum: [US, world]}
    Name:
      type: object
      description: A name belonging to an individual (system fields are read-only).
      properties:
        id: {type: integer, readOnly: true}
        individual_id: {type: integer, readOnly: true}
        name_type: {type: string, example: birth, description: birth|married|aka|immigrant|maiden}
        name_prefix: {type: string, nullable: true}
        given: {type: string, nullable: true}
        nickname: {type: string, nullable: true}
        surname_prefix: {type: string, nullable: true}
        surname: {type: string, nullable: true}
        name_suffix: {type: string, nullable: true}
        is_primary: {type: boolean}
        sort_order: {type: integer}
        display: {type: string, readOnly: true, description: reassembled full name}
    Individual:
      type: object
      properties:
        id: {type: integer, readOnly: true}
        gedcom_xref: {type: string, nullable: true}
        sex: {type: string, nullable: true, enum: [M, F, X, U, null]}
        living: {type: boolean, default: true}
        restriction: {type: string, nullable: true, description: GEDCOM RESN}
        created_at: {type: string, format: date-time, readOnly: true}
        updated_at: {type: string, format: date-time, readOnly: true}
        primary_name: {type: string, nullable: true, readOnly: true}
        names_count: {type: integer, readOnly: true}
        names: {type: array, items: {$ref: '#/components/schemas/Name'}, description: present on detail GET}
        name: {$ref: '#/components/schemas/Name', description: write-only — an optional inline primary name on create}
    FamilyChild:
      type: object
      properties:
        family_id: {type: integer, readOnly: true}
        child_id: {type: integer}
        child_name: {type: string, readOnly: true}
        pedigree_type: {type: string, enum: [birth, adopted, foster, step], default: birth}
        child_order: {type: integer, default: 0}
    Family:
      type: object
      properties:
        id: {type: integer, readOnly: true}
        gedcom_xref: {type: string, nullable: true}
        partner1_id: {type: integer, nullable: true}
        partner2_id: {type: integer, nullable: true}
        partner1: {type: string, nullable: true, readOnly: true}
        partner2: {type: string, nullable: true, readOnly: true}
        created_at: {type: string, format: date-time, readOnly: true}
        updated_at: {type: string, format: date-time, readOnly: true}
        children_count: {type: integer, readOnly: true}
        children: {type: array, items: {$ref: '#/components/schemas/FamilyChild'}}
    Place:
      type: object
      properties:
        id: {type: integer, readOnly: true}
        full_name: {type: string}
        city: {type: string, nullable: true}
        county: {type: string, nullable: true}
        state: {type: string, nullable: true}
        country: {type: string, nullable: true}
        latitude: {type: number, nullable: true}
        longitude: {type: number, nullable: true}
    Event:
      type: object
      properties:
        id: {type: integer, readOnly: true}
        subject_type: {type: string, enum: [individual, family]}
        subject_id: {type: integer}
        subject_label: {type: string, nullable: true, readOnly: true}
        event_tag: {type: string, example: BIRT, description: GEDCOM tag}
        event_value: {type: string, nullable: true, description: attribute value, e.g. an occupation}
        date_original: {type: string, nullable: true, example: ABT 1850}
        date_sort: {type: string, nullable: true, example: "1850-00-00"}
        place_id: {type: integer, nullable: true}
        place: {type: string, nullable: true, readOnly: true}
        age: {type: string, nullable: true}
        cause: {type: string, nullable: true}
        created_at: {type: string, format: date-time, readOnly: true}
    Repository:
      type: object
      properties:
        id: {type: integer, readOnly: true}
        gedcom_xref: {type: string, nullable: true}
        name: {type: string}
        address: {type: string, nullable: true}
        website: {type: string, nullable: true}
        sources_count: {type: integer, readOnly: true}
    Source:
      type: object
      properties:
        id: {type: integer, readOnly: true}
        gedcom_xref: {type: string, nullable: true}
        title: {type: string}
        author: {type: string, nullable: true}
        publication: {type: string, nullable: true}
        repository_id: {type: integer, nullable: true}
        repository: {type: string, nullable: true, readOnly: true}
        citations_count: {type: integer, readOnly: true}
    Citation:
      type: object
      properties:
        id: {type: integer, readOnly: true}
        source_id: {type: integer}
        source_title: {type: string, nullable: true, readOnly: true}
        subject_type: {type: string, enum: [individual, family, event, name]}
        subject_id: {type: integer}
        subject_label: {type: string, nullable: true, readOnly: true}
        page: {type: string, nullable: true}
        quality: {type: integer, nullable: true, minimum: 0, maximum: 3, description: GEDCOM QUAY}
        notes: {type: string, nullable: true}
    Link:
      type: object
      description: A polymorphic attachment target.
      required: [subject_type, subject_id]
      properties:
        subject_type: {type: string, enum: [individual, family, event]}
        subject_id: {type: integer}
        subject_label: {type: string, nullable: true, readOnly: true}
    Media:
      type: object
      properties:
        id: {type: integer, readOnly: true}
        gedcom_xref: {type: string, nullable: true}
        file_path: {type: string, readOnly: true}
        media_type: {type: string, readOnly: true, example: image/jpeg}
        title: {type: string, nullable: true}
        description: {type: string, nullable: true}
        capture_date: {type: string, nullable: true, description: when the photo was taken (raw, e.g. "Summer 1952")}
        capture_date_sort: {type: string, nullable: true, description: normalized sortable capture date}
        uploaded_by: {type: integer, nullable: true, readOnly: true}
        uploader: {type: string, nullable: true, readOnly: true}
        created_at: {type: string, format: date-time, readOnly: true, description: when uploaded (distinct from capture_date)}
        file_url: {type: string, readOnly: true}
        thumb_url: {type: string, readOnly: true}
        links_count: {type: integer, readOnly: true}
        links: {type: array, items: {$ref: '#/components/schemas/Link'}}
    Note:
      type: object
      properties:
        id: {type: integer, readOnly: true}
        gedcom_xref: {type: string, nullable: true}
        title: {type: string, nullable: true}
        content: {type: string, description: raw Markdown}
        content_type: {type: string, enum: [markdown, plain], default: markdown}
        is_shared: {type: boolean, default: false}
        author_id: {type: integer, nullable: true, readOnly: true}
        author: {type: string, nullable: true, readOnly: true}
        created_at: {type: string, format: date-time, readOnly: true}
        updated_at: {type: string, format: date-time, readOnly: true}
        links_count: {type: integer, readOnly: true}
        links: {type: array, items: {$ref: '#/components/schemas/Link'}}
        subject_type: {type: string, writeOnly: true, description: optional inline attachment on create}
        subject_id: {type: integer, writeOnly: true}
    SearchResults:
      type: object
      properties:
        query: {type: string}
        counts: {type: object, properties: {people: {type: integer}, notes: {type: integer}}}
        people:
          type: array
          items: {$ref: '#/components/schemas/PersonListItem'}
        notes:
          type: array
          items:
            type: object
            properties:
              id: {type: integer}
              title: {type: string, nullable: true}
              snippet: {type: string}
              author: {type: string, nullable: true}