openapi.yaml

openapi: 3.1.0
info:
  title: Ledgerline API
  version: 1.743.0
  license:
    name: Proprietary
  description: >
    Plaintext-relational personal cloud API for the Ledgerline mobile client.

    **Architecture:** every module is a relational table exposed over per-record
    REST (soft-delete trash + optimistic-concurrency `version`). ALL user content is
    plaintext at rest since v1.516.0 — confidentiality at rest is an infrastructure
    concern (LUKS full-disk encryption + encrypted backups). Only OPERATIONAL SECRETS
    (SMTP / backup / Paperless credentials, backup passphrases) remain encrypted at
    rest via the Laravel `encrypted` cast (APP_KEY) and are never serialised into any
    response. The client sends and receives plaintext over TLS. Binary files (invoice
    PDFs, receipts) are stored as plaintext bytes and streamed by id. (The former
    zero-knowledge / vault / sealed-store model was fully removed in the v1.5xx pivot.)

    **Authentication:** obtain a Sanctum bearer token via the device pairing
    exchange (QR code scan + owner approval in the web UI), then include it as
    `Authorization: Bearer <token>` on every request. All routes except the two
    pairing endpoints require the `device` Sanctum ability. Sanctum's absolute
    token lifetime is shortened to 60 days for the internet-facing deployment
    (v1.562.0); re-pair / re-login to renew (idle + remote-wipe revocation apply
    on top). Login also requires a verified email address before a bearer is
    minted (403 `{status:"verify-email"}`), and a blocked account fails auth
    generically (no enumeration).

    **Rate limiting (enforced, v1.562.0):** since the app is served publicly via
    the NetBird proxy (`https://home.pinlo.me`), the former LAN-only no-op
    throttling was reversed — every throttled route now genuinely returns
    **429** with a `Retry-After` header. Named web limiters: login 5/min,
    two-factor challenge 5/min (TOTP is no longer online-brute-forceable),
    fortify 20/min, auth-pair 30/min, dav 120/min, share-unlock 10/min, invite
    10/min. The `/api/v1` endpoints carry inline per-minute throttles (e.g.
    `/auth/login` 10/min, the `/auth/{reset,forgot,register}` broker routes
    6/min, `/invite/*` 20/min, `/backup/jobs/{job}/run` 10/min,
    `/finance/transactions/bulk` 120/min); handle 429 by backing off for
    `Retry-After` seconds.

    **Web-only surfaces (intentionally no /api/v1 twin):** per-user Paperless
    CONFIGURATION (URL/token/enabled + connection test) and the workspace-admin
    settings — notification channels (mail/ntfy/webhook) edit/update/test, system
    settings + error resolution, the `max_connected_devices` security setting, and
    the self-registration toggle — are managed in the web UI only. (Backup, users,
    groups, security-log and the company profile ARE mirrored on the API.)

    **Forced 2FA (workspace policy):** when an admin enables `force_2fa`, EVERY
    authenticated `/api/v1` request from an account without a confirmed second
    factor returns **403** `{status:"two_factor_required"}` (see the
    `TwoFactorRequired` response), except the enrollment/escape endpoints
    (`/me`, `/auth/logout`, `/preferences`, `/locale`, `/theme`,
    `/user/two-factor*`). Clients should route the user to 2FA enrollment on
    that status. This is a workspace-wide gate applied by middleware, not a
    per-operation flag.

    **Response security headers (v1.562.0):** responses carry a tightened header
    set for the internet-facing deployment — `Content-Security-Policy` with
    `frame-ancestors 'self'` + `X-Frame-Options: SAMEORIGIN` (framing default
    reversed from `*`), a broadened `Permissions-Policy` denylist, and stripped
    `Server`/`X-Powered-By`. These are transport headers, not JSON — clients need
    no changes.

servers:
  - url: /api/v1
    description: Current stable API base path

security:
  - bearerAuth: []

tags:
  - name: Auth
    description: Device pairing exchange and session management
  - name: Passkeys
    description: >
      WebAuthn passkeys / hardware security keys (YubiKey, Nitrokey, platform
      authenticators) via web-auth/webauthn-lib. Public login pair mints a
      device bearer token; management endpoints require the authenticated user
      plus a current-password step-up to register. Public-key only at rest
      (none-attestation).
  - name: Me/Device
    description: Authenticated user info, avatar, and device heartbeat
  - name: Finance
  - name: Devices
    description: Connected device listing, revocation, and remote-wipe management
  - name: Notifications
    description: In-app notification bell — list recent items, mark read
  - name: Account
    description: GDPR data export, account deletion, and session revocation
  - name: Preferences
    description: User preferences — locale and colour-scheme
  - name: Groups
    description: >
      Admin group management (requires the admin role on top of the device token).
      A group is a reusable limit template (device cap + module allow-list) plus a
      shareable flag; membership is many-to-many. Limits and membership are non-secret
      metadata.
  - name: Company
    description: >
      Per-user company profile and invoice defaults (the Finance module's business
      identity + numbering/appearance settings). This is the user's OWN business
      identity that prints on every invoice — non-secret, served in the clear like the
      avatar (it is the business's own identity, never customer data).
      The invoice records, payment methods and imported bank transactions themselves
      live in the relational finance tables (see the Finance tag).
  - name: Status
    description: Application availability / health check (the site-root /up up-check).
  - name: TwoFactor
    description: >
      Self-service TOTP two-factor + app-password management for a paired device
      (Sanctum bearer). Mirrors the web Fortify flow, which is browser-only.
  - name: DevicePairings
    description: >
      Owner-side device pairing: an already-paired device generates a code, polls
      it, and approves/rejects the new device's claim. Owner-scoped.
  - name: Users
    description: >
      Admin user management (requires the admin role on top of the device token —
      `can:manage-global-settings`). No credentials (password hashes, 2FA secrets)
      are ever returned. Non-admins get 403.
  - name: Backup
    description: >
      Admin backup management (admin role + device token). Credential hygiene is
      enforced: destination `config` (cloud credentials) and job `passphrase` are
      NEVER present in any response. A database job with encrypt=false is refused
      (422) — a DB dump contains all data (plaintext) plus the encrypted operational
      secrets, and must never leave the box unencrypted.
  - name: SecurityLog
    description: >
      Admin, read-only, metadata-only audit trail (admin role + device token). Rows
      never contain tokens/keys/ciphertext.
  - name: SecurityPortal
    description: >
      Admin security portal (admin role + device token): verbose HTTP request log
      with CSV/JSON export, IP block-list CRUD, per-user block toggle, and a
      cross-user session/device overview.
  - name: Paperless
    description: >
      Per-user Paperless-ngx integration: cached term quick-picks, live term
      creation, cache sync, and document forwarding. `POST /paperless/documents` is
      a transient-cleartext boundary (like POST /invoices/ocr): the client posts the
      raw document bytes, the server forwards them to the user's own Paperless
      instance and stores/logs nothing. Per-user Paperless CONFIGURATION (URL / token
      / enabled flag) is managed via GET/PUT /paperless/config + POST
      /paperless/config/test; the API token is never returned (has_token bool).
  - name: Settings
    description: >
      Admin workspace settings (requires the admin role on top of the device token —
      `can:manage-global-settings`): outgoing notifications (SMTP/NTFY/webhook) with a
      test send, the paired-device cap, the Files upload/orphan-grace limits, and the
      read-only System/maintenance overview. Operative secrets (SMTP password, ntfy
      token, webhook secret) are NEVER returned — a GET reports has_* booleans and a
      blank submission preserves the stored secret. Non-admins get 403.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum
      description: >
        First-party Sanctum token with ability `device`. Obtained via the
        pairing exchange. Include as `Authorization: Bearer <token>`.

  responses:
    Unauthorized:
      description: Unauthenticated — missing, invalid, or expired bearer token.
    Forbidden:
      description: >
        Forbidden — the Sanctum token lacks the required `device` ability, the
        Finance module is disabled for this account (module:finance gate), or (on
        admin routes) the caller is not an admin (manage-global-settings).
    TwoFactorRequired:
      description: >
        Two-factor enrollment required. When the workspace has `force_2fa`
        enabled (admin security policy), EVERY authenticated `/api/v1` request
        from an account without a confirmed second factor returns this, EXCEPT
        the enrollment/escape endpoints (`/me`, `/auth/logout`, `/preferences`,
        `/locale`, `/theme`, `/user/two-factor*`). Enroll a second factor to
        clear it. Body `status` is `two_factor_required` (distinct from the
        generic Forbidden). Enforced by the EnsureTwoFactorEnrolled middleware.
      content:
        application/json:
          schema:
            type: object
            properties:
              status: { type: string, enum: [two_factor_required] }
              message: { type: string }
    NotFound:
      description: Not found, or not owned by the caller (owner-scoped; existence is not leaked).
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/ValidationError" }
    FinanceV2QuoteUnprocessable:
      description: Quote input validation or a stable quote-domain rejection.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/FinanceV2QuoteUnprocessable" }
    VersionConflict:
      description: >
        Optimistic-concurrency conflict — the stored `version` no longer matches the
        `version` sent. Re-fetch the row, merge, and retry.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/VersionConflict" }
    RateLimited:
      description: >
        Too many requests — the route's per-minute rate limit was exceeded.
        Rate limiting is genuinely enforced again on the internet-facing
        deployment (v1.562.0); it was inert under the former LAN-only build.
        Back off and retry after the `Retry-After` interval.
      headers:
        Retry-After:
          description: Seconds to wait before retrying (standard throttle header).
          schema: { type: integer }

  schemas:
    WebauthnCredential:
      type: object
      description: A registered passkey / hardware key (public-key only, owner-scoped).
      properties:
        id: { type: integer }
        name: { type: [string, "null"] }
        last_used_at: { type: [string, "null"], format: date-time }
        created_at: { type: [string, "null"], format: date-time }
    ValidationError:
      type: object
      description: >
        Laravel validation-failure body (HTTP 422). `errors` maps each failed field
        to its messages.
      required: [message, errors]
      properties:
        message: { type: string }
        errors:
          type: object
          additionalProperties: { type: array, items: { type: string } }
    VersionConflict:
      type: object
      description: >
        Optimistic-concurrency conflict body. `version` is the current stored
        version the client should rebase onto.
      required: [error, version]
      properties:
        error: { type: string, enum: [version_conflict] }
        version: { type: integer }
    FinanceError:
      type: object
      description: "Business-rule rejection body: a machine-readable `error` code (HTTP 422)."
      required: [error]
      properties:
        error: { type: string }
    TransactionReceipt:
      type: object
      description: >
        A receipt entry embedded in a bank transaction's `receipts[]`. File receipts
        are created only via POST /finance/transactions/{transaction}/receipts;
        `blob_path` is the SERVER-owned on-disk path (never accepted from the client).
        Fileless entries (invoice links / Eigenbeleg metadata) may be added via the
        transaction PUT.
      required: [id, name, kind, tags, locked, trashed]
      properties:
        id: { type: string, description: "UUID assigned server-side." }
        blob_path: { type: [string, "null"], description: "Server-owned storage path under invoices/ (read-only; response only)." }
        name: { type: string }
        mime: { type: [string, "null"] }
        kind: { type: string, example: receipt, description: "e.g. receipt | invoice | eigenbeleg." }
        category: { type: [string, "null"] }
        tags: { type: array, items: { type: string } }
        contactId: { type: [string, "null"] }
        partnerId: { type: [integer, "null"] }
        sig: { type: [string, "null"], description: "Content signature ({size}:{sha256 of head+tail}), the same one finance_receipts.sig carries. Lets the receipt inbox recognise a document that is already filed at a booking instead of uploading a second copy." }
        vat: { type: [string, "null"] }
        locked: { type: boolean, description: "A locked receipt (e.g. an auto-linked invoice) cannot be deleted." }
        trashed: { type: boolean }
        removed_from_server: { type: boolean, description: "The origin copy has been deleted; the archived copy is the only one left." }

    PaperlessConfig:
      type: object
      description: >
        Per-user Paperless connection config. The API token is never returned;
        `has_token` reports whether one is stored.
      required: [paperless_enabled, paperless_url, has_token, counts]
      properties:
        paperless_enabled: { type: boolean }
        paperless_url: { type: [string, "null"], format: uri }
        has_token: { type: boolean }
        counts:
          type: object
          required: [tag, document_type, correspondent]
          properties:
            tag: { type: integer }
            document_type: { type: integer }
            correspondent: { type: integer }

    NotificationConfig:
      type: object
      description: >
        Workspace notification config with secrets masked. Secret values
        (smtp_password / ntfy_token / webhook_secret) are represented only by
        has_* booleans and are never returned.
      required:
        [mail_enabled, has_smtp_password, ntfy_enabled, has_ntfy_token, webhook_enabled, has_webhook_secret]
      properties:
        mail_enabled: { type: boolean }
        smtp_host: { type: [string, "null"] }
        smtp_port: { type: [integer, "null"] }
        smtp_encryption: { type: [string, "null"], enum: [tls, ssl, null] }
        smtp_username: { type: [string, "null"] }
        smtp_from_address: { type: [string, "null"], format: email }
        smtp_from_name: { type: [string, "null"] }
        has_smtp_password: { type: boolean }
        ntfy_enabled: { type: boolean }
        ntfy_url: { type: [string, "null"], format: uri }
        ntfy_topic: { type: [string, "null"] }
        has_ntfy_token: { type: boolean }
        webhook_enabled: { type: boolean }
        webhook_url: { type: [string, "null"], format: uri }
        has_webhook_secret: { type: boolean }
    NotificationConfigWrite:
      type: object
      description: >
        Notification config update. Only submitted fields are persisted. Secret
        fields (smtp_password/ntfy_token/webhook_secret) preserve the stored value
        when omitted or blank.
      properties:
        mail_enabled: { type: boolean }
        smtp_host: { type: [string, "null"], maxLength: 255, description: "SSRF-guarded (v1.562.0): a host resolving to a link-local / cloud-metadata / internal range is rejected with 422 (parity with ntfy_url/webhook_url)." }
        smtp_port: { type: [integer, "null"], minimum: 1, maximum: 65535 }
        smtp_encryption: { type: [string, "null"], enum: [tls, ssl, null] }
        smtp_username: { type: [string, "null"], maxLength: 255 }
        smtp_password: { type: [string, "null"], maxLength: 255, description: "Blank/omitted keeps the stored secret." }
        smtp_from_address: { type: [string, "null"], format: email, maxLength: 255 }
        smtp_from_name: { type: [string, "null"], maxLength: 255 }
        ntfy_enabled: { type: boolean }
        ntfy_url: { type: [string, "null"], format: uri, maxLength: 255 }
        ntfy_topic: { type: [string, "null"], maxLength: 255 }
        ntfy_token: { type: [string, "null"], maxLength: 255, description: "Blank/omitted keeps the stored secret." }
        webhook_enabled: { type: boolean }
        webhook_url: { type: [string, "null"], format: uri, maxLength: 255 }
        webhook_secret: { type: [string, "null"], maxLength: 255, description: "Blank/omitted keeps the stored secret." }

    SecurityPolicy:
      type: object
      description: "Workspace security policy: device cap, password policy and force-2FA."
      properties:
        max_connected_devices: { type: integer }
        pw_min_length: { type: [integer, "null"] }
        pw_require_mixed_case: { type: boolean }
        pw_require_numbers: { type: boolean }
        pw_require_symbols: { type: boolean }
        pw_check_breaches: { type: boolean }
        force_2fa: { type: boolean }

    SystemOverview:
      type: object
      description: "Read-only operational overview (metadata only — no secrets)."
      required: [tasks, status, trend, errors, audit]
      properties:
        tasks:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              expression: { type: string }
              lastAt: { type: [string, "null"] }
              lastOk: { type: [boolean, "null"] }
        status:
          type: object
          description: "SystemStatus snapshot (version/queue/storage/errors/backup/scheduler/disk)."
          additionalProperties: true
        trend:
          type: object
          description: "Storage trend over ~30 days ({points, deltaBytes, deltaDays})."
          additionalProperties: true
        errors:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              level: { type: [string, "null"] }
              exception: { type: [string, "null"] }
              message: { type: [string, "null"] }
              file: { type: [string, "null"] }
              line: { type: [integer, "null"] }
              count: { type: integer }
              first_seen_at: { type: [string, "null"] }
              last_seen_at: { type: [string, "null"] }
              resolved_at: { type: [string, "null"] }
        audit:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              action: { type: string }
              actor: { type: [string, "null"] }
              ip: { type: [string, "null"] }
              meta: { type: [object, "null"], additionalProperties: true }
              created_at: { type: [string, "null"] }

    CompanyProfile:
      type: object
      description: >
        Per-user company profile + invoice defaults (the business identity that prints
        on invoices). Non-secret. All fields are optional; on PUT, only the fields sent
        are updated. `has_logo` is read-only (response only).
      properties:
        company_name: { type: [string, "null"], maxLength: 200 }
        company_address: { type: [string, "null"], maxLength: 1000 }
        company_email: { type: [string, "null"], format: email, maxLength: 200 }
        company_phone: { type: [string, "null"], maxLength: 100 }
        company_tax_id: { type: [string, "null"], maxLength: 100 }
        company_vat_id: { type: [string, "null"], maxLength: 100 }
        company_iban: { type: [string, "null"], maxLength: 60 }
        company_bic: { type: [string, "null"], maxLength: 20 }
        company_bank_name: { type: [string, "null"], maxLength: 200 }
        invoice_number_format: { type: [string, "null"], maxLength: 40, description: "e.g. YYYY-NNNN. Locked client-side once the current year has invoices (GoBD)." }
        invoice_next_number: { type: [integer, "null"], minimum: 1, maximum: 100000000, description: "Numbering floor; the actual next number is derived per year from the invoices." }
        invoice_default_vat_rate: { type: [number, "null"], minimum: 0, maximum: 100 }
        small_business: { type: boolean, description: "§19 Kleinunternehmer — when true, invoices show no VAT and the VAT return reports zero output VAT." }
        invoice_payment_terms_days: { type: [integer, "null"], minimum: 0, maximum: 365 }
        invoice_footer_text: { type: [string, "null"], maxLength: 2000 }
        invoice_accent_color: { type: [string, "null"], pattern: "^#[0-9a-fA-F]{6}$" }
        invoice_heading_color: { type: [string, "null"], pattern: "^#[0-9a-fA-F]{6}$" }
        invoice_template: { type: [string, "null"], enum: [editorial, modern, elegant, klassisch, schlicht] }
        invoice_payment_methods: { type: [string, "null"], maxLength: 500 }
        invoice_payment_terms_text: { type: [string, "null"], maxLength: 1000 }
        company_website: { type: [string, "null"], maxLength: 255 }
        company_contacts: { type: array, maxItems: 20, items: { type: object, properties: { name: { type: [string, "null"] }, role: { type: [string, "null"] }, email: { type: [string, "null"] }, phone: { type: [string, "null"] } } } }
        invoice_font: { type: [string, "null"], maxLength: 80 }
        invoice_vat_ist: { type: boolean, description: "Ist-Versteuerung (cash-basis VAT) toggle." }
        has_logo: { type: boolean, readOnly: true, description: "Whether a company logo is stored (GET /company/logo)." }

    Group:
      type: object
      description: >
        A user group: a reusable limit template plus a shareable flag. Limits are
        nullable (null = the group sets no cap for that dimension). Non-secret
        metadata.
      properties:
        id: { type: integer }
        name: { type: string, maxLength: 100 }
        max_connected_devices: { type: [integer, "null"], description: "Device cap (null = no group cap)." }
        shareable: { type: boolean, description: "Members may offer this group as a share target." }
        modules:
          type: [array, "null"]
          description: >
            Allow-list of enabled module keys for members of this group (null = all
            modules). A member's effective modules are the union across their groups
            (a group with null grants all); a per-user allow-list overrides. Enforced
            server-side and surfaced at /me as user.modules.
          items: { type: string, enum: [finance] }
        members:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              name: { type: string }
              email: { type: string }

    DisplayPreferences:
      type: object
      description: >
        Global, non-secret DISPLAY preferences — 12/24h clock, date format and a
        timezone override. Presentation only. Returned in GET /me and set via
        POST /preferences; the client applies them to its own rendering.
      properties:
        time_format: { type: string, enum: [24h, 12h] }
        timezone: { type: [string, "null"], description: "Hard IANA timezone override (e.g. Europe/Berlin); null follows the browser/system zone." }
        date_format: { type: string, enum: [system, dmy, dmy_dot, mdy, ymd], description: "Date-format preset; 'system' uses the locale's regional format." }
        notifications:
          type: object
          description: "Per-category push prefs, keyed by notification category (e.g. server/finance_bank_csv/reminder). Absent category = push enabled."
          additionalProperties:
            type: object
            properties:
              push: { type: boolean, description: "false suppresses push for this category (the centre row is still created)." }

    MeUser:
      type: object
      description: >
        The authenticated user's profile. Returned as the `user` object by GET /me
        and by POST /auth/pair/collect (when `status: approved`). All fields are
        non-secret metadata — no credentials (password hash, 2FA secret) are included.
      required: [id, name, email, locale, groups, modules, has_avatar, two_factor, preferences, theme]
      properties:
        id: { type: integer }
        name: { type: string }
        email: { type: string, format: email }
        locale:
          type: string
          description: "The user's UI locale (one of the configured languages, e.g. en, de, ru)."
        groups:
          type: array
          description: >
            Derived from the first-party role: `["admin"]` for admins, `[]` otherwise.
            The historical claim shape is kept so existing mobile clients need no
            change — there is no separate `role` field.
          items: { type: string }
        modules:
          type: array
          description: >
            The application module keys this account may use (per-user / per-group
            toggles). A native client should hide the tabs for modules NOT listed
            here; the API also enforces it — a disabled module's store endpoints
            return 403.
          items: { type: string, enum: [finance] }
        has_avatar:
          type: boolean
          description: "Whether a non-secret avatar is stored. True → fetch it via GET /api/v1/avatar (Bearer)."
        two_factor:
          type: boolean
          description: "Whether TOTP two-factor authentication is confirmed for the account."
        preferences:
          allOf:
            - $ref: "#/components/schemas/DisplayPreferences"
          description: "Non-secret display preferences (units + 12/24h clock); set via POST /api/v1/preferences."
        theme:
          type: string
          enum: [light, dark, system]
          description: "Current UI theme (set via POST /api/v1/theme)."

    OkResponse:
      type: object
      description: Acknowledgement response.
      required: [ok]
      properties:
        ok:
          type: boolean
          example: true

    Invoice:
      type: object
      description: >
        Invoice (relational table invoices). All columns are plaintext at rest since
        v1.516.0 (confidentiality is an infra concern: LUKS + encrypted backups).
        customer/lines/versions are JSON columns; money + number/date drive stats +
        GoBD numbering. number/seq/year/type=credit_note/cancels_invoice_id/pdf_path/
        version/version_seq are server-managed and never mass-assigned via CRUD.
      properties:
        id: { type: integer }
        user_id: { type: integer, description: "Owner (stamped server-side; read-only)." }
        number: { type: [string, "null"] }
        seq: { type: [integer, "null"] }
        year: { type: [integer, "null"] }
        status: { type: string, enum: [draft, final, sent, paid] }
        type: { type: string, enum: [invoice, credit_note], description: "Document kind. A credit note (Storno/Gutschrift) reverses a finalized invoice and carries its own GoBD number." }
        cancels_invoice_id: { type: [integer, "null"], description: "For a credit note, the id of the invoice it cancels (server-set, never mass-assigned)." }
        issue_date: { type: [string, "null"] }
        due_date: { type: [string, "null"] }
        currency: { type: string }
        vat_rate: { type: [string, "null"] }
        gross: { type: [string, "null"] }
        net: { type: [string, "null"] }
        vat: { type: [string, "null"] }
        discount_type: { type: [string, "null"], enum: [percent, amount, null], description: "Global invoice-level discount kind (Rabatt) on the net taxable base." }
        discount_value: { type: [string, "null"], description: "Discount value: a percentage when discount_type=percent, else an absolute amount." }
        skonto_percent: { type: [string, "null"], description: "Early-payment Skonto percentage printed on the invoice." }
        skonto_days: { type: [integer, "null"], description: "Early-payment Skonto window in days from the issue date." }
        imported: { type: boolean }
        paid_at: { type: [string, "null"], format: date-time }
        sent_at: { type: [string, "null"], format: date-time, description: "When the invoice PDF was emailed to the customer." }
        reminded_at: { type: [string, "null"], format: date-time, description: "When a payment reminder (dunning) was last sent." }
        reminder_count: { type: integer, description: "Dunning level (Mahnstufe) — how many customer reminders have gone out." }
        payment_account: { type: [string, "null"] }
        partner_id: { type: [integer, "null"] }
        pdf_path: { type: [string, "null"] }
        customer: { type: [object, "null"], additionalProperties: true, description: "Denormalised customer snapshot (nullable). May carry `invoiceEmail` (dedicated Rechnungs-E-Mail, preferred over `email` when emailing/dunning) alongside name/attn/address/email/vatId/partnerId." }
        lines: { type: [array, "null"], items: { type: object, additionalProperties: true } }
        note: { type: [string, "null"] }
        versions:
          type: [array, "null"]
          description: "GoBD correction trail. Pass a version's `seq` as `version_seq` to the PDF ops to read/attach that version's own PDF."
          items:
            type: object
            properties:
              seq: { type: integer, description: "Version sequence — pass as version_seq to the PDF ops." }
              label: { type: [string, "null"] }
              pdf: { type: [string, "null"], description: "Stored blob path of this version's own PDF (read-only)." }
            additionalProperties: true
        version_seq: { type: integer }
        version: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        deleted_at: { type: [string, "null"], format: date-time }

    FinancePartner:
      type: object
      description: "Geschäftspartner (relational finance_partners). All columns plaintext at rest since v1.516.0."
      properties:
        id: { type: integer }
        user_id: { type: integer, description: "Owner (stamped server-side; read-only)." }
        name: { type: string }
        category: { type: [string, "null"] }
        url: { type: [string, "null"] }
        logo: { type: [string, "null"] }
        note: { type: [string, "null"] }
        address: { type: [string, "null"] }
        email: { type: [string, "null"] }
        invoice_email: { type: [string, "null"], description: "Dedicated invoice email (Rechnungs-E-Mail); invoices are sent here when set, else the general email." }
        phone: { type: [string, "null"] }
        vat_id: { type: [string, "null"] }
        hourly_rate: { type: [string, "null"], description: "Default hourly rate as a decimal string (decimal:2 cast); prefills invoice line items for this partner." }
        customer_number: { type: [string, "null"], description: "Assigned by the server on create from the `customer_number_format` template, unless the caller supplies one (migrating from another system). Only for a party we sell to — a supplier has no use for ours. Binned partners keep their number out of circulation." }
        kind: { type: [string, "null"], enum: [customer, supplier, both, lead, null], description: "What the partner is to us. The column existed unused since the pivot and carries this meaning from v1.782.0." }
        payment_terms_days: { type: [integer, "null"], description: "Prefills a new document's due date." }
        discount_percent: { type: [string, "null"], description: "Standing discount; prefills a new document." }
        delivery_address: { type: [string, "null"], description: "Where goods go, when that is not where the invoice goes." }
        archived_at: { type: [string, "null"], format: date-time, description: "Hidden from the pickers but not gone; its documents still point at it." }
        currency: { type: [string, "null"], description: "ISO 4217 code used when invoicing this partner." }
        contacts: { type: array, items: { type: object, additionalProperties: true } }
        version: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        deleted_at: { type: [string, "null"], format: date-time }

    PaymentMethod:
      type: object
      description: "Payment method (relational payment_methods; all columns plaintext since v1.516.0)."
      properties:
        id: { type: integer }
        user_id: { type: integer, description: "Owner (stamped server-side; read-only)." }
        type: { type: string, enum: [bank, card, paypal, cash, other] }
        name: { type: string }
        scope: { type: string, enum: [business, private], description: "Business or private. An account always states its scope; its bookings inherit it. Existing accounts read as business." }
        holder: { type: [string, "null"] }
        note: { type: [string, "null"] }
        business: { type: boolean }
        url: { type: [string, "null"] }
        icon: { type: [string, "null"] }
        iban: { type: [string, "null"] }
        bic: { type: [string, "null"] }
        bank: { type: [string, "null"] }
        account_no: { type: [string, "null"] }
        card_number: { type: [string, "null"] }
        card_network: { type: [string, "null"] }
        card_expiry: { type: [string, "null"] }
        paypal_email: { type: [string, "null"] }
        version: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        deleted_at: { type: [string, "null"], format: date-time }

    FinanceProject:
      type: object
      description: "Cost project (relational finance_projects, nestable via parent_id) and the unit of planning: tasks and logged hours hang off it."
      properties:
        id: { type: integer }
        user_id: { type: integer, description: "Owner (stamped server-side; read-only)." }
        parent_id: { type: [integer, "null"] }
        name: { type: string }
        kind: { type: string, enum: [business, private] }
        note: { type: [string, "null"] }
        expenses: { type: [array, "null"], items: { $ref: "#/components/schemas/ProjectExpense" }, description: "Hand-typed ledger rows (nullable). Stored verbatim as JSON — the server validates only that it is an array of at most 5000 items." }
        status: { type: string, enum: [planned, active, on_hold, done, cancelled], description: "on_hold and cancelled are the two states that are neither progress nor completion." }
        starts_on: { type: [string, "null"], format: date }
        due_on: { type: [string, "null"], format: date }
        budget_net: { type: [string, "null"], description: "What it may cost, net. Compared against the ledger; nothing is enforced — a project over budget is information, not an error." }
        partner_id: { type: [integer, "null"], description: "Whose project it is. Also supplies the hourly rate frozen onto new time entries." }
        quote_id: { type: [integer, "null"], description: "The quote it came from, when it came from one. Server-owned." }
        version: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        deleted_at: { type: [string, "null"], format: date-time }

    ProjectExpense:
      type: object
      description: |
        One hand-typed row of a project's ledger, stored inside
        `finance_projects.expenses`. The column is free-form JSON: the server
        persists it as sent and only reads `date`, `amount`, `direction` and
        `category` for the EÜR, so a client MUST round-trip unknown keys rather
        than dropping them.

        `direction: 'in'` is a Zubuchung (a refund/credit booked on the project)
        and REDUCES the expense total in `GET /finance/reports/euer`;
        `direction: 'out'` (and a legacy row that carries no `direction` at all)
        is a Abbuchung and adds to it. `amount` is unsigned — the sign lives in
        `direction`.
      properties:
        id: { type: string, description: "Client-generated row id (stable across edits; used to update/delete a single row)." }
        direction: { type: string, enum: [out, in], default: out, description: "out = spend (Abbuchung), in = credit (Zubuchung)." }
        amount: { type: number, description: "Unsigned amount, gross." }
        date: { type: [string, "null"], format: date, description: "Booking date (YYYY-MM-DD); the EÜR buckets by its year." }
        title: { type: [string, "null"], description: "Short label shown in the ledger (Bezeichnung), e.g. \"Excavator rental\"." }
        note: { type: [string, "null"], description: "Longer free-text description (Beschreibung)." }
        category: { type: [string, "null"], description: "Free-text expense category — matched by name against the managed finance categories (for the Sachkonto) and used as the EÜR grouping label." }
        payment_method_id: { type: [integer, "null"], description: "Which account the money moved through (informational; not validated server-side)." }

    FinancePartnerNote:
      type: object
      description: "One entry in a partner's contact log. `occurred_at` is when it happened; `created_at` is when it was typed, which can be days later."
      properties:
        id: { type: integer }
        user_id: { type: integer }
        finance_partner_id: { type: integer }
        kind: { type: string, enum: [call, meeting, mail, note] }
        body: { type: string }
        occurred_at: { type: string, format: date-time }
        created_at: { type: [string, "null"], format: date-time }
        updated_at: { type: [string, "null"], format: date-time }
    FinanceProduct:
      type: object
      description: "A sellable article. `stock_qty` is a denormalised read of the movement ledger, written only alongside a movement; treat it as reporting, not as an input."
      properties:
        id: { type: integer }
        user_id: { type: integer }
        kind: { type: string, enum: [service, hardware] }
        sku: { type: [string, "null"], description: "Article number. Unique among an owner's live articles; a binned one frees it." }
        name: { type: string }
        description: { type: [string, "null"] }
        unit: { type: [string, "null"], description: "Free text — hour, piece, day, flat rate. Every trade names its units differently." }
        price_net: { type: string, description: "Decimal as string (decimal:2 cast)." }
        purchase_price: { type: [string, "null"], description: "What it cost us. Used to show a margin; never printed on a document that leaves the house." }
        vat_rate: { type: [string, "null"], description: "null = fall back to the company default rate." }
        supplier_id: { type: [integer, "null"] }
        category: { type: [string, "null"] }
        active: { type: boolean }
        track_stock: { type: boolean }
        stock_qty: { type: string, description: "Decimal as string (decimal:3). Fractional on purpose: 2.5 hours, 0.5 metres." }
        stock_min: { type: [string, "null"], description: "Reorder level. null = never warn." }
        note: { type: [string, "null"] }
        version: { type: integer }
        created_at: { type: [string, "null"], format: date-time }
        updated_at: { type: [string, "null"], format: date-time }
        deleted_at: { type: [string, "null"], format: date-time }
    FinanceProductInput:
      type: object
      description: "Create/update body. Stock fields are absent on purpose — see the stock endpoint."
      properties:
        kind: { type: string, enum: [service, hardware] }
        sku: { type: [string, "null"], maxLength: 64 }
        name: { type: string, maxLength: 300 }
        description: { type: [string, "null"], maxLength: 5000 }
        unit: { type: [string, "null"], maxLength: 32 }
        price_net: { type: [number, "null"] }
        purchase_price: { type: [number, "null"] }
        vat_rate: { type: [number, "null"], minimum: 0, maximum: 100 }
        supplier_id: { type: [integer, "null"], description: "Must be one of the caller's own partners." }
        category: { type: [string, "null"], maxLength: 160 }
        active: { type: [boolean, "null"] }
        track_stock: { type: [boolean, "null"] }
        note: { type: [string, "null"], maxLength: 5000 }
        version: { type: [integer, "null"], description: "Send it to get a 409 instead of a blind overwrite." }
    FinanceStockMovement:
      type: object
      description: "One movement of goods. Append-only: no update, no delete, no soft delete — a stock figure is only trustworthy if the steps behind it cannot be rewritten."
      properties:
        id: { type: integer }
        user_id: { type: integer }
        finance_product_id: { type: integer }
        qty: { type: string, description: "Signed decimal as string. In positive, out negative." }
        reason: { type: string, enum: [purchase, sale, correction, return, initial] }
        ref_type: { type: [string, "null"], enum: [invoice, quote, manual, null], description: "What caused it. A loose reference, not a foreign key, so deleting a document cannot erase the fact that goods moved." }
        ref_id: { type: [string, "null"] }
        note: { type: [string, "null"] }
        occurred_at: { type: string, format: date-time }
        created_at: { type: [string, "null"], format: date-time }
    FinanceDocumentLine:
      type: object
      description: "One line of a quote or invoice. The SAME shape on both, which is what makes converting a quote a copy rather than a translation, and lets the cent-exact totals mathematics stay one implementation."
      properties:
        desc: { type: string }
        qty: { type: number }
        unit: { type: [string, "null"] }
        unitPrice: { type: number }
        vatRate: { type: [number, "null"] }
        kind: { type: [string, "null"], enum: [service, hardware, null] }
        productId: { type: [integer, "null"], description: "The catalogue article this line came from. What lets a finalised invoice move stock." }
    FinanceProjectTask:
      type: object
      description: "A piece of work under a project. A milestone is the same row with `is_milestone` set — a date that matters with no work in it."
      properties:
        id: { type: integer }
        user_id: { type: integer }
        finance_project_id: { type: integer }
        title: { type: string }
        description: { type: [string, "null"] }
        status: { type: string, enum: [open, in_progress, done] }
        starts_on: { type: [string, "null"], format: date }
        due_on: { type: [string, "null"], format: date }
        estimate_hours: { type: [string, "null"], description: "Hours quoted for this piece of work, decimal as string." }
        is_milestone: { type: boolean }
        sort: { type: integer, description: "Hand-ordered: task order is a judgement, not a date." }
        finance_product_id: { type: [integer, "null"], description: "The catalogue article the quote line came from, when it came from one." }
        version: { type: integer }
        created_at: { type: [string, "null"], format: date-time }
        updated_at: { type: [string, "null"], format: date-time }
        deleted_at: { type: [string, "null"], format: date-time }
    FinanceProjectTaskInput:
      type: object
      properties:
        title: { type: string, maxLength: 300 }
        description: { type: [string, "null"], maxLength: 20000 }
        status: { type: [string, "null"], enum: [open, in_progress, done, null] }
        starts_on: { type: [string, "null"], format: date }
        due_on: { type: [string, "null"], format: date }
        estimate_hours: { type: [number, "null"] }
        is_milestone: { type: [boolean, "null"] }
        sort: { type: [integer, "null"] }
        version: { type: [integer, "null"] }
    FinanceTimeEntry:
      type: object
      description: "Hours worked. `hourly_rate` is frozen here rather than read from the partner at invoicing time, so a later rate change cannot rewrite what past work was worth. `invoiced_invoice_id` is set once and never cleared — that is the protection against billing the same hour twice."
      properties:
        id: { type: integer }
        user_id: { type: integer }
        finance_project_id: { type: integer }
        finance_project_task_id: { type: [integer, "null"], description: "Optional: not everything worth logging was planned." }
        date: { type: string, format: date }
        hours: { type: string }
        description: { type: [string, "null"] }
        billable: { type: boolean }
        hourly_rate: { type: [string, "null"] }
        invoiced_invoice_id: { type: [integer, "null"] }
        version: { type: integer }
        created_at: { type: [string, "null"], format: date-time }
        updated_at: { type: [string, "null"], format: date-time }
        deleted_at: { type: [string, "null"], format: date-time }
    FinanceTimeEntryInput:
      type: object
      properties:
        finance_project_task_id: { type: [integer, "null"], description: "Must belong to the same project." }
        date: { type: [string, "null"], format: date, description: "Defaults to today." }
        hours: { type: number, minimum: -24, maximum: 24, description: "Zero is refused: it states nothing." }
        description: { type: [string, "null"], maxLength: 20000 }
        billable: { type: [boolean, "null"], default: true }
        hourly_rate: { type: [number, "null"], description: "Defaults to the customer's rate at the time of logging." }
        version: { type: [integer, "null"] }
    FinanceQuote:
      type: object
      description: "A quote (Angebot). Editable only while `status` is draft. `expired` is derived from `valid_until`, never stored — a date does not need a nightly job to become true."
      properties:
        id: { type: integer }
        user_id: { type: integer }
        number: { type: [string, "null"], description: "Assigned by the server on send. Never settable by a client." }
        seq: { type: [integer, "null"] }
        year: { type: [integer, "null"] }
        status: { type: string, enum: [draft, sent, accepted, declined] }
        partner_id: { type: [integer, "null"] }
        customer: { type: [object, "null"], additionalProperties: true, description: "Snapshot of the addressee, kept alongside partner_id so editing the partner cannot rewrite a quote already sent." }
        title: { type: [string, "null"] }
        issue_date: { type: [string, "null"], format: date }
        valid_until: { type: [string, "null"], format: date }
        currency: { type: string }
        lines: { type: [array, "null"], items: { $ref: "#/components/schemas/FinanceDocumentLine" } }
        discount_type: { type: [string, "null"], enum: [percent, amount, null] }
        discount_value: { type: [string, "null"] }
        net: { type: [string, "null"] }
        vat: { type: [string, "null"] }
        gross: { type: [string, "null"] }
        intro_text: { type: [string, "null"] }
        outro_text: { type: [string, "null"] }
        note: { type: [string, "null"] }
        sent_at: { type: [string, "null"], format: date-time }
        accepted_at: { type: [string, "null"], format: date-time }
        declined_at: { type: [string, "null"], format: date-time }
        converted_invoice_id: { type: [integer, "null"] }
        converted_project_id: { type: [integer, "null"] }
        pdf_path: { type: [string, "null"] }
        version: { type: integer }
        created_at: { type: [string, "null"], format: date-time }
        updated_at: { type: [string, "null"], format: date-time }
        deleted_at: { type: [string, "null"], format: date-time }
    FinanceQuoteInput:
      type: object
      description: "Create/update body. `number`/`seq`/`year`/`status` are absent on purpose: the server owns them, so a client cannot mint or reuse a number."
      properties:
        title: { type: [string, "null"], maxLength: 300 }
        partner_id: { type: [integer, "null"], description: "Must be one of the caller's own partners." }
        customer: { type: [object, "null"], additionalProperties: true }
        issue_date: { type: [string, "null"], format: date }
        valid_until: { type: [string, "null"], format: date }
        currency: { type: [string, "null"], maxLength: 8 }
        lines: { type: [array, "null"], maxItems: 200, items: { $ref: "#/components/schemas/FinanceDocumentLine" } }
        discount_type: { type: [string, "null"], enum: [percent, amount, null] }
        discount_value: { type: [number, "null"] }
        net: { type: [number, "null"] }
        vat: { type: [number, "null"] }
        gross: { type: [number, "null"] }
        intro_text: { type: [string, "null"], maxLength: 5000 }
        outro_text: { type: [string, "null"], maxLength: 5000 }
        note: { type: [string, "null"], maxLength: 5000 }
        version: { type: [integer, "null"] }
    FinanceCategory:
      type: object
      description: "Receipt category (relational finance_categories, unique per user; no soft deletes)."
      properties:
        id: { type: integer }
        user_id: { type: integer, description: "Owner (stamped server-side; read-only)." }
        name: { type: string }
        color: { type: [string, "null"], description: "Hex colour #RRGGBB, or null.", example: "#7066f5" }
        icon: { type: [string, "null"], description: "Monochrome icon name (heroicons-outline), or null.", example: "hashtag" }
        account_no: { type: [string, "null"], description: "Owner-entered Sachkonto/chart-of-accounts code (e.g. SKR03/04) for this category, or null. Free text — the server never assigns or validates a specific number.", example: "4930" }
        created_at: { type: [string, "null"], format: date-time }
        updated_at: { type: [string, "null"], format: date-time }

    VatReturn:
      type: object
      description: "VAT advance return (Umsatzsteuer-Voranmeldung) figures for a year."
      required: [year, net, vat, gross, count, byRate, quarters]
      properties:
        year: { type: integer }
        net: { type: number }
        vat: { type: number }
        gross: { type: number }
        count: { type: integer }
        byRate:
          type: array
          items:
            type: object
            properties: { rate: { type: number }, net: { type: number }, vat: { type: number } }
        quarters:
          type: array
          items:
            type: object
            properties: { q: { type: integer }, net: { type: number }, vat: { type: number } }

    FinanceKpis:
      type: object
      description: "Headline revenue KPIs for a year incl. year-over-year net growth."
      required: [year, net, count, avg, customers, prevNet]
      properties:
        year: { type: integer }
        net: { type: number }
        count: { type: integer }
        avg: { type: number }
        customers: { type: integer }
        prevNet: { type: number }
        growthPct: { type: [number, "null"] }

    RevenueByCustomer:
      type: object
      description: "Net/gross revenue for one customer in a year."
      properties:
        name: { type: string }
        net: { type: number }
        gross: { type: number }
        count: { type: integer }

    InvoiceAging:
      type: object
      description: >
        Aging of OPEN invoices (status='sent', not trashed) bucketed by days past
        the due date vs today: current (not yet due / no due date), 1-30, 31-60,
        60+. Read-only; each bucket carries count + gross sum + the invoice list.
      required: [buckets, openCount, openGross]
      properties:
        openCount: { type: integer }
        openGross: { type: number }
        buckets:
          type: object
          properties:
            current: { $ref: "#/components/schemas/AgingBucket" }
            "1_30": { $ref: "#/components/schemas/AgingBucket" }
            "31_60": { $ref: "#/components/schemas/AgingBucket" }
            "60_plus": { $ref: "#/components/schemas/AgingBucket" }

    AgingBucket:
      type: object
      required: [count, gross, invoices]
      properties:
        count: { type: integer }
        gross: { type: number }
        invoices:
          type: array
          items:
            type: object
            properties:
              id: { type: integer }
              number: { type: [string, "null"] }
              customer: { type: string }
              gross: { type: number }
              due_date: { type: [string, "null"] }
              days_overdue: { type: integer }

    AccountVatSummary:
      type: object
      description: "VAT summary of one account's transactions: output/input VAT + payable, by rate."
      required: [income, expense, outputVat, inputVat, payable, privateSum, undecided]
      properties:
        income: { type: array, items: { type: object, properties: { rate: { type: string }, net: { type: number }, vat: { type: number } } } }
        expense: { type: array, items: { type: object, properties: { rate: { type: string }, net: { type: number }, vat: { type: number } } } }
        outputVat: { type: number }
        inputVat: { type: number }
        payable: { type: number }
        privateSum: { type: number }
        undecided: { type: integer }

    VatAdvanceReturn:
      type: object
      description: >
        Unified USt-Voranmeldung: output VAT (from realized invoices) minus input
        VAT / Vorsteuer (from ALL of the user's bank transactions) = payable
        (Zahllast), for a year and optional quarter. For a §19 Kleinunternehmer
        outputVat is 0 (turnover reported as net = gross) and payable = −inputVat.
      required: [year, quarter, net, outputVat, inputVat, payable, byRate, small_business]
      properties:
        year: { type: integer }
        quarter: { type: [integer, "null"], minimum: 1, maximum: 4, description: "1–4, or null for the full year." }
        net: { type: number, description: "Net turnover for the period (output side)." }
        outputVat: { type: number, description: "VAT collected on sales." }
        inputVat: { type: number, description: "Vorsteuer paid on expenses." }
        payable: { type: number, description: "outputVat − inputVat (Zahllast)." }
        byRate:
          type: array
          items:
            type: object
            properties:
              rate: { type: number }
              outputNet: { type: number }
              outputVat: { type: number }
              inputNet: { type: number }
              inputVat: { type: number }
        small_business: { type: boolean }

    EuerReport:
      type: object
      description: >
        Simplified EÜR (Einnahmenüberschussrechnung): income − expenses = profit
        for a year. Income = realized invoices by issue_date (net, or gross for a
        §19 KU) grouped by customer; expenses = that year's expense bank
        transactions (excluding private movements) + FinanceProject manual
        expenses, grouped by VAT/expense category. Not the full Anlage-EÜR form.
      required: [year, income, expenses, profit, small_business]
      properties:
        year: { type: integer }
        income:
          type: object
          required: [total, byCategory]
          properties:
            total: { type: number }
            byCategory:
              type: array
              items:
                type: object
                properties: { name: { type: string }, amount: { type: number } }
        expenses:
          type: object
          required: [total, byCategory]
          properties:
            total: { type: number }
            byCategory:
              type: array
              items:
                type: object
                properties: { name: { type: string }, amount: { type: number } }
        profit: { type: number }
        small_business: { type: boolean }

    RecurringCharge:
      type: object
      description: >
        One detected recurring charge (subscription, standing order), from
        GET /finance/recurring. Read-only: the detector reports, it never writes a
        row. Conservative by design — at least three charges and a stable interval,
        because a false "you have a subscription" is worse than a miss.
      properties:
        merchant: { type: string, description: "Counterparty as booked (grouping normalises legal forms, so 'NETCUP GmbH' and 'netcup Deutschland' are one)." }
        scope: { type: string, enum: [business, private] }
        cadence: { type: string, enum: [weekly, monthly, quarterly, semiannual, annual] }
        interval_days: { type: integer, description: "Median days between charges." }
        charges: { type: integer }
        amount: { type: number, format: double, description: "Most recent charge." }
        yearly: { type: number, format: double, description: "Annualised from the cadence (not the measured gap), so a leap year does not move it and a monthly line compares with an annual one." }
        first_at: { type: string, format: date }
        last_at: { type: string, format: date }
        next_at: { type: string, format: date, description: "Expected next charge (last + interval)." }
        stale: { type: boolean, description: "The next charge is well overdue — cancelled, or silently stopped." }
        price_change:
          type: [object, "null"]
          description: "Set when the most recent charge differs from the one before it."
          properties:
            from: { type: number, format: double }
            to: { type: number, format: double }
            at: { type: string, format: date }
        transaction_ids: { type: array, items: { type: integer } }

    DuplicateGroup:
      type: object
      description: "A suspected-duplicate group (read-only). `ids` are the row ids sharing `key` for `reason`."
      required: [reason, key, ids]
      properties:
        reason: { type: string }
        key: { type: string }
        ids: { type: array, items: { type: integer } }

    NumberGapGroup:
      type: object
      description: "A run of missing invoice numbers within one numbering regime (read-only, never mutates a row). `group` is `year:YYYY` for YYYY-NNNN numbers (reset per calendar year) or the literal `sequence` for every other format (bare integers, R-NNNNN, …), which is treated as one continuous ordinal sequence across all years."
      required: [group, missing, min, max, count]
      properties:
        group: { type: string, example: "year:2025" }
        missing: { type: array, items: { type: string }, description: "The missing numbers, formatted like the group's highest-numbered sample." }
        min: { type: string, description: "Lowest number observed in this group." }
        max: { type: string, description: "Highest number observed in this group." }
        count: { type: integer }

    FinanceReceipt:
      type: object
      description: "Standalone receipt (relational finance_receipts) — a receipt document WITHOUT a bank transaction (\"Fremdbeleg\"). Bytes plaintext on the files disk; blob_path/size/sig server-owned. Optional bank_transaction_id links it to a booking, or — for a split payment (one receipt settled by several separate charges) — linked_transaction_ids links it to all of them instead; the two are mutually exclusive."
      properties:
        id: { type: integer }
        user_id: { type: integer, description: "Owner (stamped server-side; read-only)." }
        bank_transaction_id: { type: integer, nullable: true, description: "Optional link to a bank booking (the common single-charge case)." }
        linked_transaction_ids: { type: array, items: { type: integer }, nullable: true, description: "Split-payment link: this receipt's total was debited as several separate bank transactions, e.g. one INWX invoice settled by two charges a week apart. Mutually exclusive with bank_transaction_id — setting one server-side clears the other." }
        finance_project_id: { type: integer, nullable: true }
        blob_path: { type: string, description: "Server-owned storage path (files disk)." }
        name: { type: string }
        mime: { type: string, nullable: true }
        size: { type: integer }
        sig: { type: string, nullable: true, description: "Content dedup signature." }
        kind: { type: string }
        scope: { type: [string, "null"], enum: [business, private, null], description: "null = follow the linked booking (which follows its account); a loose receipt is business." }
        effective_scope: { type: string, enum: [business, private], description: "Resolved server-side. Read-only." }
        category: { type: string, nullable: true }
        tags: { type: array, items: { type: string } }
        vat: { type: string, nullable: true }
        amount: { type: [string, "null"], description: "Gross total as a decimal string (decimal:2 cast — Laravel serialises it as a string), editable, prefilled by OCR recognition." }
        currency: { type: string, nullable: true, description: "ISO 4217 code (EUR/USD/GBP/CHF), uppercased server-side; editable, prefilled by OCR recognition. Display/reference only — amount is never converted." }
        date: { type: [string, "null"], description: "Document date (editable, prefilled by OCR recognition). Carries a time part: a `date` cast serialises exactly like `datetime`, so this is `2026-07-31T00:00:00.000000Z`, not a plain date." }
        order_ref: { type: string, nullable: true, description: "Merchant-printed payment/order reference (e.g. Amazon's \"Zahlungsreferenznummer\") — the strongest signal for grouping several receipts that settle as one charge." }
        doc_number: { type: string, nullable: true, description: "Recognised invoice/receipt number — display + de-dup signal for accidental re-uploads." }
        note: { type: string, nullable: true }
        partner_id: { type: integer, nullable: true }
        ocr: { type: string, nullable: true }
        version: { type: integer }
        created_at: { type: string, format: date-time, nullable: true }
        updated_at: { type: string, format: date-time, nullable: true }
        deleted_at: { type: string, format: date-time, nullable: true }

    ReceiptMatchGroup:
      type: object
      description: "A suggested link between one or more unlinked standalone receipts and one unlinked bank transaction (read-only, never mutates a row) — covers the case a single charge is settled by several receipts (e.g. Amazon splitting an order into multiple shipment invoices). The client applies an accepted group by PUTing bank_transaction_id on each listed receipt."
      required: [transaction_id, receipt_ids, reason, total]
      properties:
        transaction_id: { type: integer }
        receipt_ids: { type: array, items: { type: integer }, description: "One or more receipts summing to `total`." }
        reason: { type: string, enum: [order_ref, exact, sum], description: "order_ref = receipts share a merchant-printed payment reference; exact = one receipt matches the amount to the cent; sum = a bounded subset-sum of nearby receipts matches the amount." }
        total: { type: number, format: double }
    ReceiptDuplicate:
      type: object
      description: "An accidental re-upload of the same receipt document (same order_ref/doc_number + amount as an earlier upload), excluded from ReceiptMatchGroup sums so it is never double-counted."
      required: [receipt_id, duplicate_of]
      properties:
        receipt_id: { type: integer }
        duplicate_of: { type: integer, description: "The earlier-uploaded receipt this one duplicates." }
    SplitPaymentGroup:
      type: object
      description: "The inverse of ReceiptMatchGroup: one unlinked standalone receipt whose amount matches no SINGLE unlinked transaction, but a bounded subset-sum of several does (e.g. one INWX invoice billed as one document but debited as two separate charges a week apart). Read-only, never mutates a row. The client applies an accepted group by PUTing linked_transaction_ids on the receipt."
      required: [receipt_id, transaction_ids, reason, total]
      properties:
        receipt_id: { type: integer }
        transaction_ids: { type: array, items: { type: integer }, description: "Two or more transactions summing to `total`." }
        reason: { type: string, enum: [sum], description: "Always sum — a single matching transaction is already handled elsewhere (the client's own auto-pick on upload), so this only ever fires for a combination." }
        total: { type: number, format: double }

    BankTransaction:
      type: object
      description: "Bank-statement line (relational bank_transactions). All columns plaintext at rest since v1.516.0. Amount/date/vat_cat drive stats + VAT."
      properties:
        id: { type: integer }
        user_id: { type: integer, description: "Owner (stamped server-side; read-only)." }
        payment_method_id: { type: integer }
        date: { type: string }
        amount: { type: string }
        vat_cat: { type: [string, "null"] }
        scope: { type: [string, "null"], enum: [business, private, null], description: "null = follow the account; an explicit value overrides it. Distinct from vat_cat='private' (an owner withdrawal that stays in the books)." }
        effective_scope: { type: string, enum: [business, private], description: "Resolved server-side (booking -> account) so no client re-derives the rule. Read-only." }
        sig: { type: [string, "null"] }
        invoice_id: { type: [integer, "null"] }
        invoice_number: { type: [string, "null"] }
        finance_project_id: { type: [integer, "null"] }
        counterparty: { type: [string, "null"] }
        counterparty_iban: { type: [string, "null"] }
        bic: { type: [string, "null"] }
        purpose: { type: [string, "null"] }
        booking_text: { type: [string, "null"] }
        eref: { type: [string, "null"] }
        receipts: { type: [array, "null"], items: { $ref: "#/components/schemas/TransactionReceipt" } }
        version: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        deleted_at: { type: [string, "null"], format: date-time }

    InvoiceInput:
      type: object
      description: >
        Invoice create/update body. On create `name` defaults apply
        (status=draft, type=invoice, currency=EUR); `number` is optional (self-issued
        invoices are numbered server-side via /finalize). On update every field is
        optional (send only what changes) and `version` drives optimistic concurrency.
        Server-managed fields (seq/year/cancels_invoice_id/pdf_path/version) are never
        accepted here.
      properties:
        number: { type: [string, "null"], maxLength: 64 }
        status: { type: string, enum: [draft, final, sent, paid] }
        type: { type: string, enum: [invoice, credit_note] }
        issue_date: { type: [string, "null"], format: date }
        due_date: { type: [string, "null"], format: date }
        currency: { type: string, maxLength: 8 }
        vat_rate: { type: [number, "null"] }
        gross: { type: [number, "null"] }
        net: { type: [number, "null"] }
        vat: { type: [number, "null"] }
        discount_type: { type: [string, "null"], enum: [percent, amount, null] }
        discount_value: { type: [number, "null"], minimum: 0 }
        skonto_percent: { type: [number, "null"], minimum: 0, maximum: 100 }
        skonto_days: { type: [integer, "null"], minimum: 0, maximum: 3650 }
        imported: { type: boolean }
        paid_at: { type: [string, "null"], format: date }
        payment_account: { type: [string, "null"], maxLength: 200 }
        partner_id: { type: [integer, "null"], description: "Must be an existing, owned, non-deleted partner." }
        customer: { type: [object, "null"], additionalProperties: true }
        lines: { type: [array, "null"], maxItems: 1000, items: { type: object, additionalProperties: true } }
        note: { type: [string, "null"], maxLength: 100000 }
        versions: { type: [array, "null"], maxItems: 1000, items: { type: object, additionalProperties: true } }
        version: { type: integer, minimum: 0, description: "Update only: expected row version for optimistic concurrency (409 on mismatch)." }

    PartnerInput:
      type: object
      description: "Business-partner create/update body. `name` is required on create. `version` (update only) drives optimistic concurrency."
      properties:
        name: { type: string, maxLength: 300 }
        category: { type: [string, "null"], maxLength: 120 }
        kind: { type: [string, "null"], maxLength: 16 }
        url: { type: [string, "null"], maxLength: 2000 }
        logo: { type: [string, "null"], maxLength: 2000 }
        note: { type: [string, "null"], maxLength: 100000 }
        address: { type: [string, "null"], maxLength: 2000 }
        email: { type: [string, "null"], maxLength: 320 }
        invoice_email: { type: [string, "null"], format: email, maxLength: 320 }
        phone: { type: [string, "null"], maxLength: 100 }
        vat_id: { type: [string, "null"], maxLength: 64 }
        contacts: { type: [array, "null"], maxItems: 200, items: { type: object, additionalProperties: true } }
        version: { type: integer, minimum: 0, description: "Update only: optimistic concurrency (409 on mismatch)." }

    PaymentMethodInput:
      type: object
      description: "Payment-method create/update body. `type` + `name` are required on create. `version` (update only) drives optimistic concurrency."
      properties:
        type: { type: string, enum: [bank, card, paypal, cash, other] }
        name: { type: string, maxLength: 200 }
        holder: { type: [string, "null"], maxLength: 200 }
        note: { type: [string, "null"], maxLength: 20000 }
        business: { type: boolean }
        scope: { type: string, enum: [business, private], description: "Defaults to business; its bookings inherit it." }
        url: { type: [string, "null"], maxLength: 2000 }
        icon: { type: [string, "null"], maxLength: 200000, description: "Data-URI or URL of a small bank/brand icon." }
        iban: { type: [string, "null"], maxLength: 64 }
        bic: { type: [string, "null"], maxLength: 32 }
        bank: { type: [string, "null"], maxLength: 200 }
        account_no: { type: [string, "null"], maxLength: 64 }
        card_number: { type: [string, "null"], maxLength: 40 }
        card_network: { type: [string, "null"], maxLength: 40 }
        card_expiry: { type: [string, "null"], maxLength: 16 }
        paypal_email: { type: [string, "null"], maxLength: 320 }
        version: { type: integer, minimum: 0, description: "Update only: optimistic concurrency (409 on mismatch)." }

    ProjectInput:
      type: object
      description: "Cost-project create/update body. `name` is required on create. `version` (update only) drives optimistic concurrency."
      properties:
        name: { type: string, maxLength: 300 }
        parent_id: { type: [integer, "null"], description: "Must be an existing, owned, non-deleted project." }
        kind: { type: string, enum: [business, private] }
        note: { type: [string, "null"], maxLength: 100000 }
        expenses: { type: [array, "null"], maxItems: 5000, items: { $ref: "#/components/schemas/ProjectExpense" }, description: "Replaces the whole ledger — there is no per-row endpoint. Send the full array." }
        version: { type: integer, minimum: 0, description: "Update only: optimistic concurrency (409 on mismatch)." }

    CategoryInput:
      type: object
      required: [name]
      description: "Receipt-category create/update body (name/colour/icon/account_no — a full replace, not just a rename)."
      properties:
        name: { type: string, maxLength: 160, description: "Unique per user (the current category id is ignored on update)." }
        color: { type: [string, "null"], pattern: "^#[0-9a-fA-F]{6}$", example: "#7066f5" }
        icon: { type: [string, "null"], maxLength: 40, description: "Monochrome heroicons-outline name from the fixed allowlist (FinanceController::CATEGORY_ICONS), e.g. hashtag/tag/banknotes." }
        account_no: { type: [string, "null"], maxLength: 40, description: "Owner-entered Sachkonto/chart-of-accounts code, free text.", example: "4930" }

    TransactionInput:
      type: object
      description: "Bank-transaction create/update body. `payment_method_id` + `date` + `amount` are required on create. `version` (update only) drives optimistic concurrency."
      properties:
        payment_method_id: { type: integer, description: "Must be an existing, owned, non-deleted payment method." }
        date: { type: string, format: date }
        amount: { type: number }
        vat_cat: { type: [string, "null"], maxLength: 16 }
        scope: { type: [string, "null"], enum: [business, private, null], description: "null/absent = follow the account." }
        sig: { type: [string, "null"], maxLength: 80, description: "Dedup signature." }
        invoice_id: { type: [integer, "null"], description: "Must be an existing, owned, non-deleted invoice." }
        invoice_number: { type: [string, "null"], maxLength: 64 }
        finance_project_id: { type: [integer, "null"], description: "Must be an existing, owned, non-deleted project." }
        counterparty: { type: [string, "null"], maxLength: 2000 }
        counterparty_iban: { type: [string, "null"], maxLength: 64 }
        bic: { type: [string, "null"], maxLength: 32 }
        purpose: { type: [string, "null"], maxLength: 4000 }
        booking_text: { type: [string, "null"], maxLength: 2000 }
        eref: { type: [string, "null"], maxLength: 200 }
        receipts:
          type: [array, "null"]
          maxItems: 200
          description: "Metadata + fileless (invoice-link/Eigenbeleg) entries only; a client-supplied blob_path is always dropped — real file receipts are created via the receipts endpoint."
          items: { type: object, additionalProperties: true }
        version: { type: integer, minimum: 0, description: "Update only: optimistic concurrency (409 on mismatch)." }

    TransactionBulkRow:
      type: object
      required: [date, amount]
      description: "One parsed bank-statement line for POST /finance/transactions/bulk. Deduplicated by `sig`."
      properties:
        date: { type: string, format: date }
        amount: { type: number }
        sig: { type: [string, "null"], maxLength: 80 }
        vat_cat: { type: [string, "null"], maxLength: 16 }
        counterparty: { type: [string, "null"], maxLength: 2000 }
        counterparty_iban: { type: [string, "null"], maxLength: 64 }
        bic: { type: [string, "null"], maxLength: 32 }
        purpose: { type: [string, "null"], maxLength: 4000 }
        booking_text: { type: [string, "null"], maxLength: 2000 }
        eref: { type: [string, "null"], maxLength: 200 }

    UserSettings:
      type: object
      description: "Per-user non-display settings (file version cap)."
      properties:
        file_max_versions: { type: integer, minimum: 1, maximum: 200 }

    AdminUser:
      type: object
      description: "Admin view of a user. Never includes password hashes or 2FA secrets."
      required: [id, name, email, role, verified, two_factor]
      properties:
        id: { type: integer }
        name: { type: string }
        email: { type: string, format: email }
        role: { type: string, enum: [admin, user] }
        max_connected_devices: { type: [integer, "null"] }
        modules: { type: [array, "null"], items: { type: string } }
        groups: { type: array, items: { type: object, properties: { id: { type: integer }, name: { type: string } } } }
        verified: { type: boolean }
        two_factor: { type: boolean }
        last_login_at: { type: [string, "null"], format: date-time }
        blocked_at: { type: [string, "null"], format: date-time, description: "Set while the account is blocked (see POST /admin/users/{user}/block); null when active." }

    AdminUserWrite:
      type: object
      description: "User create/update body. role/quotas/modules are privilege fields (never mass-assigned server-side)."
      properties:
        name: { type: string, maxLength: 255 }
        email: { type: string, format: email, maxLength: 255 }
        role: { type: string, enum: [admin, user] }
        password: { type: string, minLength: 12, description: "Create only (prohibited on update); omit to trigger a reset mail." }
        max_connected_devices: { type: [integer, "null"], minimum: 1, maximum: 50 }
        modules: { type: [array, "null"], items: { type: string, enum: [finance] } }
        modules_marker: { type: string, enum: ['set'], description: "Send with an (empty) modules[] to set an explicit list rather than 'no change'." }
        groups: { type: [array, "null"], items: { type: integer } }

    PaperlessTerm:
      type: object
      required: [id, name]
      properties:
        id: { type: integer, description: "Paperless numeric id." }
        name: { type: string }
        color: { type: [string, "null"] }

    SecurityLogEntry:
      type: object
      description: "One append-only audit entry. Metadata only — never tokens/keys/ciphertext."
      properties:
        at: { type: [string, "null"], format: date-time }
        user_id: { type: [integer, "null"] }
        actor: { type: [string, "null"], description: "Display name at query time." }
        action: { type: string, example: device.evicted, description: "Dot-namespaced event id." }
        ip: { type: [string, "null"] }
        user_agent: { type: [string, "null"] }
        meta: { type: [object, "null"], additionalProperties: true }

    RequestLogEntry:
      type: object
      description: "One HTTP request-trail row (admin, metadata only)."
      required: [id, method, path, status]
      properties:
        id: { type: integer }
        time: { type: [string, "null"], format: date-time }
        ip: { type: [string, "null"] }
        method: { type: string, example: GET }
        path: { type: string, example: /api/v1/files }
        status: { type: integer, example: 200 }
        user:
          type: [object, "null"]
          properties: { id: { type: integer }, name: { type: string } }
        user_agent: { type: [string, "null"] }
        duration_ms: { type: [integer, "null"] }

    BlockedIp:
      type: object
      description: "One entry in the IP/CIDR block-list."
      required: [id, cidr]
      properties:
        id: { type: integer }
        cidr: { type: string, example: 203.0.113.0/24 }
        reason: { type: [string, "null"] }
        created_at: { type: [string, "null"], format: date-time }

    SessionsOverview:
      type: object
      description: "Cross-user active web sessions + device tokens (admin)."
      properties:
        web:
          type: array
          items:
            type: object
            properties:
              kind: { type: string, enum: [web] }
              user_id: { type: integer }
              ip: { type: [string, "null"] }
              user_agent: { type: [string, "null"] }
              last_activity: { type: [string, "null"], format: date-time }
        devices:
          type: array
          items:
            type: object
            properties:
              kind: { type: string, enum: [device] }
              user_id: { type: integer }
              name: { type: [string, "null"] }
              ip: { type: [string, "null"] }
              last_used_at: { type: [string, "null"], description: "Raw DB timestamp string (Y-m-d H:i:s), not strict ISO-8601." }

    BackupDestinationSummary:
      type: object
      description: "Safe public shape — credentials (`config`) intentionally omitted."
      properties:
        id: { type: integer }
        name: { type: string }
        driver: { type: string, enum: [s3, b2, sftp, webdav] }

    BackupDestinationWrite:
      type: object
      required: [name, driver]
      description: >
        Create/update body for a backup destination. Only the keys relevant to the
        chosen `driver` are stored: s3/b2 → bucket/region/key/secret/endpoint/
        use_path_style/path; sftp → host/port/username/password/host_fingerprint/path;
        webdav → base_uri/username/password/path. On update, a blank `secret` or
        `password` keeps the stored value. Credentials are stored encrypted (config
        cast) and are NEVER returned in any response.
      properties:
        name: { type: string, maxLength: 120 }
        driver: { type: string, enum: [s3, b2, sftp, webdav] }
        bucket: { type: string, maxLength: 255, description: "s3/b2." }
        region: { type: string, maxLength: 64, description: "s3/b2." }
        key: { type: string, maxLength: 255, description: "s3/b2 access key id." }
        secret: { type: string, maxLength: 255, description: "s3/b2 secret (blank on update keeps stored)." }
        endpoint: { type: string, maxLength: 255, format: uri, description: "s3/b2 custom endpoint. SSRF-guarded (SafeUrl)." }
        use_path_style: { type: boolean, description: "s3/b2 path-style addressing." }
        host: { type: string, maxLength: 255, description: "sftp host. SSRF-guarded (SafeHost); link-local/metadata rejected (422)." }
        port: { type: integer, minimum: 1, maximum: 65535, description: "sftp port." }
        username: { type: string, maxLength: 255, description: "sftp/webdav." }
        password: { type: string, maxLength: 255, description: "sftp/webdav (blank on update keeps stored)." }
        host_fingerprint: { type: string, maxLength: 255, description: "sftp host key fingerprint." }
        base_uri: { type: string, maxLength: 255, format: uri, description: "webdav base URL. SSRF-guarded (SafeUrl); link-local/metadata rejected (422)." }
        path: { type: string, maxLength: 255, description: "Optional sub-path prefix at the destination." }

    BackupJobSummary:
      type: object
      description: "Safe public shape — `passphrase` intentionally omitted."
      properties:
        id: { type: integer }
        name: { type: string }
        source: { type: string, enum: [database, invoices, avatars], description: "Legacy single-source column (= sources[0])." }
        sources: { type: array, items: { type: string, enum: [database, invoices, avatars] }, description: "All sources this job backs up." }
        mode: { type: string, enum: [full, incremental] }
        destination_id: { type: integer }
        cron: { type: string }
        retention: { type: integer }
        keep_daily: { type: integer }
        keep_weekly: { type: integer }
        keep_monthly: { type: integer }
        encrypt: { type: boolean }
        notify_channels: { type: array, items: { type: string } }
        enabled: { type: boolean }
        last_run_at: { type: [string, "null"], format: date-time }
        last_status: { type: [string, "null"] }
        statistics: { type: object, additionalProperties: true }

    BackupJobWrite:
      type: object
      required: [name, sources, backup_destination_id, cron, keep_daily]
      description: "A job backs up one or more sources at once into a timestamped batch, in full or incremental mode, rotated with grandfather-father-son retention. Encryption is recommended (a DB dump is cleartext PII) but optional; 422 only if encrypt=true without an available passphrase. Blank passphrase keeps the stored value on update."
      properties:
        name: { type: string, maxLength: 120 }
        sources: { type: array, minItems: 1, items: { type: string, enum: [database, invoices, avatars] }, description: "What to back up. database = full DB dump; invoices = invoice PDFs + receipts; avatars = user avatar images." }
        source: { type: [string, "null"], enum: [database, invoices, avatars], description: "Legacy single-source column, kept in sync with sources[0]. Optional." }
        mode: { type: string, enum: [full, incremental], description: "incremental only re-uploads blob sources (invoices/avatars) changed since the last run; the DB dump is always full." }
        backup_destination_id: { type: integer, description: "Must reference an existing backup destination." }
        cron: { type: string, maxLength: 64, description: "A valid cron expression." }
        retention: { type: [integer, "null"], minimum: 1, maximum: 9999, description: "Legacy flat retention; superseded by keep_daily. Kept in sync." }
        keep_daily: { type: integer, minimum: 0, maximum: 9999, description: "GFS son tier: keep the newest N batches." }
        keep_weekly: { type: [integer, "null"], minimum: 0, maximum: 9999, description: "GFS father tier: keep one batch per week for N weeks." }
        keep_monthly: { type: [integer, "null"], minimum: 0, maximum: 9999, description: "GFS grandfather tier: keep one batch per month for N months." }
        encrypt: { type: boolean }
        passphrase: { type: [string, "null"], minLength: 12, maxLength: 255, description: "Encryption passphrase. Required when encrypt=true and no env passphrase is set. Blank on update keeps stored. Never returned." }
        notify_channels: { type: array, items: { type: string, enum: [desktop, mail, ntfy, webhook] } }
        enabled: { type: boolean }

    BackupRunSummary:
      type: object
      description: "A recent backup run (the exact shape returned by GET /backup/runs)."
      properties:
        id: { type: integer }
        job: { type: [string, "null"], description: "Job name, or null if the job was deleted." }
        status: { type: string, description: "e.g. running | success | failed | cancelled." }
        message: { type: [string, "null"] }
        log: { type: [string, "null"] }
        startedIso: { type: [string, "null"], format: date-time }
        startedHuman: { type: [string, "null"], description: "Relative start time (e.g. '3 hours ago')." }
        size: { type: [string, "null"], description: "Human-readable total batch size (e.g. '4.2 MB'), or null." }
        archives:
          type: array
          description: "One entry per source backed up in this run. The database is a point-in-time dump (downloadable/verifiable/decryptable/restorable via `?source=database`); blob sources are a living MIRROR (delta-synced, no single archive) — restorable in-place but not downloadable/verifiable individually."
          items:
            type: object
            properties:
              source: { type: string, enum: [database, invoices, avatars] }
              encrypted: { type: boolean, description: "Bytes are encrypted (.enc / per-file) — verify/decrypt/restore need the passphrase." }
              mirror: { type: boolean, description: "Blob source stored as a living mirror (true) vs. a DB point-in-time dump (false)." }
              downloadable: { type: boolean, description: "Only the DB dump is a downloadable/verifiable archive; mirror sources are not." }
              restorable: { type: boolean, description: "Blob sources restore in-place from the mirror; the database cannot (use artisan backup:restore-db)." }
        cancellable: { type: boolean }
        cancelling: { type: boolean, description: "A graceful cancel has been requested and is pending." }
        verifyStatus: { type: [string, "null"] }
        verifyMessage: { type: [string, "null"] }
        verifiedHuman: { type: [string, "null"], description: "Relative time of the last verification." }

    FinanceV2Money:
      type: object
      additionalProperties: false
      required: [net_minor, vat_minor, gross_minor, currency]
      properties:
        net_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "9007199254740993", description: "Exact signed minor-unit integer string; JSON numbers are rejected." }
        vat_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "1711367858400789", description: "Exact signed minor-unit integer string; JSON numbers are rejected." }
        gross_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "10718567113141782", description: "Exact signed minor-unit integer string; JSON numbers are rejected." }
        currency: { type: string, pattern: "^[A-Z]{3}$" }

    FinanceV2QuoteLineInput:
      type: object
      additionalProperties: false
      required: [description, quantity, unit, unit_price, tax_rate, kind]
      properties:
        description: { type: string, maxLength: 1000 }
        quantity: { type: string, pattern: "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,4})?$", description: "Exact scale-4 decimal string; JSON numbers are rejected." }
        unit: { type: string, maxLength: 50 }
        unit_price: { type: string, pattern: "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", description: "Exact currency decimal string; JSON numbers are rejected." }
        tax_rate: { type: string, pattern: "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", description: "Exact percentage decimal string; JSON numbers are rejected." }
        kind: { type: string, enum: [service, hardware] }
        product_id: { type: [integer, "null"], minimum: 1 }

    FinanceV2QuoteDraftInput:
      type: object
      additionalProperties: false
      required: [title, customer, currency, lines, discount_type]
      properties:
        title: { type: string, maxLength: 255 }
        partner_id: { type: [integer, "null"], minimum: 1 }
        customer:
          type: object
          required: [name]
          properties:
            name: { type: string, maxLength: 255 }
            email: { type: [string, "null"], format: email }
          additionalProperties: true
        issue_date: { type: [string, "null"], format: date }
        valid_until: { type: [string, "null"], format: date }
        currency: { type: string, pattern: "^[A-Z]{3}$" }
        lines: { type: array, minItems: 1, maxItems: 200, items: { $ref: '#/components/schemas/FinanceV2QuoteLineInput' } }
        discount_type: { type: string, enum: [none, percent, fixed] }
        discount_value: { type: [string, "null"], pattern: "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$" }
        intro_text: { type: [string, "null"] }
        outro_text: { type: [string, "null"] }
        internal_note: { type: [string, "null"] }
        version: { type: integer, minimum: 0, description: "Required only for draft update." }
        control_net_minor: { type: [string, "null"], pattern: '^(?:0|-?[1-9][0-9]*)$', example: "9007199254740993", description: "Optional exact signed minor-unit assertion within the server integer range; JSON numbers are rejected and the value is never authoritative." }
        control_vat_minor: { type: [string, "null"], pattern: '^(?:0|-?[1-9][0-9]*)$', example: "1711367858400789", description: "Optional exact signed minor-unit assertion within the server integer range; JSON numbers are rejected and the value is never authoritative." }
        control_gross_minor: { type: [string, "null"], pattern: '^(?:0|-?[1-9][0-9]*)$', example: "10718567113141782", description: "Optional exact signed minor-unit assertion within the server integer range; JSON numbers are rejected and the value is never authoritative." }

    FinanceV2QuotePreview:
      type: object
      additionalProperties: false
      required: [net_minor, vat_minor, gross_minor, discount_minor, currency, tax_breakdowns, issue_date, valid_until]
      properties:
        net_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "9007199254740993" }
        vat_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "1711367858400789" }
        gross_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "10718567113141782" }
        discount_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "1000000000000000" }
        currency: { type: string, pattern: "^[A-Z]{3}$" }
        tax_breakdowns:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [tax_rate_basis_points, net_minor, vat_minor, gross_minor]
            properties:
              tax_rate_basis_points: { type: string, pattern: '^(?:0|[1-9][0-9]*)$', example: "1900" }
              net_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "9007199254740993" }
              vat_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "1711367858400789" }
              gross_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "10718567113141782" }
        issue_date: { type: string, format: date }
        valid_until: { type: string, format: date }

    FinanceV2QuoteLine:
      type: object
      additionalProperties: false
      required: [description, quantity, quantity_scaled, unit, unit_price, unit_price_minor, currency, tax_rate, tax_rate_basis_points, kind, product_id]
      properties:
        description: { type: string }
        quantity: { type: string }
        quantity_scaled: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "9007199254740993" }
        unit: { type: string }
        unit_price: { type: string }
        unit_price_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "9007199254740993" }
        currency: { type: string, pattern: "^[A-Z]{3}$" }
        tax_rate: { type: string }
        tax_rate_basis_points: { type: string, pattern: '^(?:0|[1-9][0-9]*)$', example: "1900", description: "Exact non-negative basis-point integer string; domain maximum is 10000." }
        kind: { type: string, enum: [service, hardware] }
        product_id: { type: [integer, "null"], minimum: 1 }

    FinanceV2QuoteCalculatedTotals:
      type: object
      additionalProperties: false
      required: [net_minor, vat_minor, gross_minor, discount_minor, currency, tax_breakdowns]
      properties:
        net_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "9007199254740993" }
        vat_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "1711367858400789" }
        gross_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "10718567113141782" }
        discount_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "1000000000000000" }
        currency: { type: string, pattern: "^[A-Z]{3}$" }
        tax_breakdowns:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [tax_rate_basis_points, net_minor, vat_minor, gross_minor]
            properties:
              tax_rate_basis_points: { type: string, pattern: '^(?:0|[1-9][0-9]*)$', example: "1900" }
              net_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "9007199254740993" }
              vat_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "1711367858400789" }
              gross_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', example: "10718567113141782" }

    FinanceV2QuoteDiscount:
      type: object
      additionalProperties: false
      required: [type, value, currency]
      properties:
        type: { type: string, enum: [none, percent, fixed] }
        value: { type: [string, "null"] }
        basis_points: { type: string, pattern: '^(?:0|[1-9][0-9]*)$', example: "1900" }
        minor: { type: string, pattern: '^(?:0|[1-9][0-9]*)$', example: "1000000000000000" }
        currency: { type: string, pattern: "^[A-Z]{3}$" }

    FinanceV2QuoteDraft:
      type: object
      additionalProperties: false
      required: [title, customer, partner_id, issue_date, valid_until, currency, lines, discount, totals, intro_text, outro_text, internal_note]
      properties:
        title: { type: string }
        customer: { type: object, additionalProperties: true }
        partner_id: { type: [integer, "null"] }
        issue_date: { type: string, format: date }
        valid_until: { type: string, format: date }
        currency: { type: string, pattern: "^[A-Z]{3}$" }
        lines: { type: array, items: { $ref: '#/components/schemas/FinanceV2QuoteLine' } }
        discount: { $ref: '#/components/schemas/FinanceV2QuoteDiscount' }
        totals: { $ref: '#/components/schemas/FinanceV2QuoteCalculatedTotals' }
        intro_text: { type: [string, "null"] }
        outro_text: { type: [string, "null"] }
        internal_note: { type: [string, "null"] }

    FinanceV2QuoteSnapshot:
      type: object
      additionalProperties: false
      required: [schema_version, document_type, series_uuid, document_number, revision_number, revision_label, title, customer, partner_id, issue_date, valid_until, currency, lines, discount, totals, intro_text, outro_text, customer_note]
      properties:
        schema_version: { type: integer, enum: [1] }
        document_type: { type: string, enum: [quote] }
        series_uuid: { type: string, format: uuid }
        document_number: { type: string }
        revision_number: { type: integer, minimum: 1 }
        revision_label: { type: string }
        title: { type: string }
        customer: { type: object, additionalProperties: true }
        partner_id: { type: [integer, "null"] }
        issue_date: { type: string, format: date }
        valid_until: { type: string, format: date }
        currency: { type: string, pattern: "^[A-Z]{3}$" }
        lines: { type: array, items: { $ref: '#/components/schemas/FinanceV2QuoteLine' } }
        discount: { $ref: '#/components/schemas/FinanceV2QuoteDiscount' }
        totals: { $ref: '#/components/schemas/FinanceV2QuoteCalculatedTotals' }
        intro_text: { type: [string, "null"] }
        outro_text: { type: [string, "null"] }
        customer_note: { type: [string, "null"] }

    FinanceV2QuoteRevision:
      type: object
      additionalProperties: false
      required: [id, revision_number, previous_revision_id, status, snapshot, totals, pdf_sha256, pdf_url, pdf_download_url, published_at, created_at]
      properties:
        id: { type: integer, format: int64 }
        revision_number: { type: integer, minimum: 1 }
        previous_revision_id: { type: [integer, "null"], format: int64 }
        status: { type: string, enum: [draft, published] }
        snapshot: { $ref: '#/components/schemas/FinanceV2QuoteSnapshot' }
        totals: { $ref: '#/components/schemas/FinanceV2Money' }
        pdf_sha256: { type: [string, "null"], pattern: "^[a-f0-9]{64}$" }
        pdf_url: { type: [string, "null"], format: uri }
        pdf_download_url: { type: [string, "null"], format: uri }
        published_at: { type: [string, "null"], format: date-time }
        created_at: { type: string, format: date-time }

    FinanceV2QuoteDelivery:
      type: object
      additionalProperties: false
      required: [uuid, revision_id, state, attempts, last_error_code, queued_at, sent_at, failed_at]
      properties:
        uuid: { type: string, format: uuid }
        revision_id: { type: integer, format: int64 }
        state: { type: string, enum: [queued, sending, sent, failed] }
        attempts: { type: integer, minimum: 0 }
        last_error_code: { type: [string, "null"] }
        queued_at: { type: string, format: date-time }
        sent_at: { type: [string, "null"], format: date-time }
        failed_at: { type: [string, "null"], format: date-time }

    FinanceV2Quote:
      type: object
      additionalProperties: false
      required: [id, status, effective_status, partner_id, number, version, has_pending_draft, current_revision, draft, totals, conversions, delivery, published_at, accepted_at, declined_at, converted_at, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        status: { type: string, enum: [draft, sent, accepted, declined, converted] }
        effective_status: { type: string, enum: [draft, sent, accepted, declined, converted, expired] }
        partner_id: { type: [integer, "null"] }
        number: { type: [string, "null"] }
        version: { type: integer, minimum: 0 }
        has_pending_draft: { type: boolean }
        current_revision: { anyOf: [{ $ref: '#/components/schemas/FinanceV2QuoteRevision' }, { type: "null" }] }
        draft: { anyOf: [{ $ref: '#/components/schemas/FinanceV2QuoteDraft' }, { type: "null" }] }
        totals: { $ref: '#/components/schemas/FinanceV2Money' }
        conversions: { type: array, items: { type: object, additionalProperties: false, properties: { source_revision_id: { type: integer }, target_type: { type: string, enum: [invoice] }, target_reference: { type: string }, target_id: { type: [integer, "null"] }, created_at: { type: string, format: date-time } }, required: [source_revision_id, target_type, target_reference, target_id, created_at] } }
        delivery: { anyOf: [{ $ref: '#/components/schemas/FinanceV2QuoteDelivery' }, { type: "null" }] }
        published_at: { type: [string, "null"], format: date-time }
        accepted_at: { type: [string, "null"], format: date-time }
        declined_at: { type: [string, "null"], format: date-time }
        converted_at: { type: [string, "null"], format: date-time }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    FinanceV2QuotePage:
      type: object
      additionalProperties: false
      required: [data, links, meta]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/FinanceV2Quote' } }
        links: { type: object, additionalProperties: false, properties: { first: { type: string, format: uri }, last: { type: string, format: uri }, prev: { type: [string, "null"], format: uri }, next: { type: [string, "null"], format: uri } }, required: [first, last, prev, next] }
        meta: { type: object, additionalProperties: false, properties: { current_page: { type: integer }, per_page: { type: integer }, total: { type: integer }, last_page: { type: integer } }, required: [current_page, per_page, total, last_page] }

    FinanceV2QuoteConflict:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error: { type: string, enum: [version_conflict, idempotency_key_reused, operation_in_progress, quote_locked, quote_revision_stale, quote_revision_replaced, quote_draft_pending, quote_publication_in_progress, quote_delivery_in_progress] }
        current: { $ref: '#/components/schemas/FinanceV2Quote' }

    FinanceV2QuoteDomainError:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error:
          type: string
          enum: [control_totals_mismatch, initial_draft_cannot_be_discarded, invalid_customer, invalid_discount, invalid_money, invalid_partner, invalid_product, invalid_quantity, invalid_quote_input, invalid_tax_rate, invalid_transition, invalid_validity_period, no_pdf, no_recipient, no_smtp, quote_draft_base_mismatch, quote_draft_missing, quote_expired, quote_not_accepted, quote_not_published, quote_publish_not_allowed, quote_revision_base_mismatch, quote_revision_not_published, quote_version_not_allowed]

    FinanceV2QuoteUnprocessable:
      oneOf:
        - { $ref: '#/components/schemas/ValidationError' }
        - { $ref: '#/components/schemas/FinanceV2QuoteDomainError' }

    FinanceV2InvoiceLineInput:
      type: object
      additionalProperties: false
      required: [description, quantity, unit, unit_price, tax_rate, kind]
      properties:
        description: { type: string, maxLength: 1000 }
        quantity: { type: string, pattern: "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,4})?$", description: "Exact scale-4 decimal string; JSON numbers are rejected." }
        unit: { type: string, maxLength: 50 }
        unit_price: { type: string, pattern: "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", description: "Exact currency decimal string; JSON numbers are rejected." }
        tax_rate: { type: string, pattern: "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", description: "Exact percentage decimal string; JSON numbers are rejected." }
        kind: { type: string, enum: [service, hardware] }
        product_id: { type: [integer, "null"], minimum: 1 }

    FinanceV2InvoiceDraftInput:
      type: object
      additionalProperties: false
      required: [issue_date, due_date, currency, customer, lines, discount_type]
      properties:
        issue_date: { type: string, format: date }
        due_date: { type: string, format: date }
        currency: { type: string, pattern: "^[A-Z]{3}$" }
        customer:
          type: object
          required: [name]
          properties:
            name: { type: string, maxLength: 255 }
            email: { type: [string, "null"], format: email }
          additionalProperties: true
        partner_id: { type: [integer, "null"], minimum: 1 }
        project_id: { type: [integer, "null"], minimum: 1 }
        lines: { type: array, minItems: 1, maxItems: 200, items: { $ref: '#/components/schemas/FinanceV2InvoiceLineInput' } }
        discount_type: { type: string, enum: [none, percent, fixed] }
        discount_value: { type: [string, "null"], pattern: "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$" }
        version: { type: integer, minimum: 0, description: "Required only for PATCH update." }
        control_net_minor: { type: [string, "null"], pattern: '^(?:0|-?[1-9][0-9]*)$', description: "Optional exact signed minor-unit assertion; never authoritative." }
        control_vat_minor: { type: [string, "null"], pattern: '^(?:0|-?[1-9][0-9]*)$', description: "Optional exact signed minor-unit assertion; never authoritative." }
        control_gross_minor: { type: [string, "null"], pattern: '^(?:0|-?[1-9][0-9]*)$', description: "Optional exact signed minor-unit assertion; never authoritative." }

    FinanceV2InvoiceSourceRef:
      type: object
      additionalProperties: false
      required: [type, key]
      properties:
        type: { type: string, enum: [quote_revision, legacy_quote_snapshot, project_time_batch, recurring_run, cancellation, legacy_invoice] }
        key: { type: string }

    FinanceV2Invoice:
      type: object
      additionalProperties: false
      required: [id, kind, number, status, issue_date, due_date, partner_id, project_id, totals, allocated_minor, paid_minor, open_minor, source, snapshot, version, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        kind: { type: string, enum: [invoice, credit_note] }
        number: { type: [string, "null"] }
        status: { type: string, enum: [draft, finalized, sent, partially_paid, paid, cancelled] }
        issue_date: { type: string, format: date }
        due_date: { type: string, format: date }
        partner_id: { type: [integer, "null"] }
        project_id: { type: [integer, "null"] }
        totals: { $ref: '#/components/schemas/FinanceV2Money' }
        allocated_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', description: "Signed sum of active allocation entries." }
        paid_minor: { type: string, pattern: '^(?:0|[1-9][0-9]*)$', description: "Non-negative magnitude applied to a normal invoice." }
        open_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$' }
        source: { anyOf: [{ $ref: '#/components/schemas/FinanceV2InvoiceSourceRef' }, { type: "null" }] }
        snapshot: { type: object, additionalProperties: true, description: "Canonical calculated draft/revision snapshot; never includes storage paths." }
        version: { type: integer, minimum: 0 }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    FinanceV2InvoicePage:
      type: object
      additionalProperties: false
      required: [data, links, meta]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/FinanceV2Invoice' } }
        links: { type: object, additionalProperties: false, properties: { first: { type: string, format: uri }, last: { type: string, format: uri }, prev: { type: [string, "null"], format: uri }, next: { type: [string, "null"], format: uri } }, required: [first, last, prev, next] }
        meta: { type: object, additionalProperties: false, properties: { current_page: { type: integer }, per_page: { type: integer }, total: { type: integer }, last_page: { type: integer } }, required: [current_page, per_page, total, last_page] }

    FinanceV2InvoiceFinalizeResult:
      allOf:
        - { $ref: '#/components/schemas/FinanceV2Invoice' }
        - type: object
          additionalProperties: false
          required: [revision]
          properties:
            revision:
              type: object
              additionalProperties: false
              required: [id, pdf_sha256, finalized_at]
              properties:
                id: { type: integer, format: int64 }
                pdf_sha256: { type: string, pattern: "^[a-f0-9]{64}$" }
                finalized_at: { type: string, format: date-time }

    FinanceV2InvoiceRevision:
      type: object
      additionalProperties: false
      required: [id, revision_number, status, snapshot, net_minor, vat_minor, gross_minor, currency, pdf_sha256, pdf_url, published_at]
      properties:
        id: { type: integer, format: int64 }
        revision_number: { type: integer, minimum: 1 }
        status: { type: string, enum: [draft, published] }
        snapshot: { type: object, additionalProperties: true }
        net_minor: { type: integer }
        vat_minor: { type: integer }
        gross_minor: { type: integer }
        currency: { type: string, pattern: "^[A-Z]{3}$" }
        pdf_sha256: { type: [string, "null"], pattern: "^[a-f0-9]{64}$" }
        pdf_url: { type: string, format: uri }
        published_at: { type: [string, "null"], format: date-time }

    FinanceV2InvoiceDelivery:
      type: object
      additionalProperties: false
      required: [id, kind, recipient, status, attempts, last_attempt_at, sent_at, next_retry_at, last_error_code, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        kind: { type: string, enum: [invoice, reminder] }
        recipient: { type: string, format: email }
        status: { type: string, enum: [pending, sending, sent, failed, unknown] }
        attempts: { type: integer, minimum: 0 }
        last_attempt_at: { type: [string, "null"], format: date-time }
        sent_at: { type: [string, "null"], format: date-time }
        next_retry_at: { type: [string, "null"], format: date-time }
        last_error_code: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    FinanceV2InvoiceConflict:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error: { type: string, enum: [version_conflict, invoice_version_conflict, invoice_delete_conflict, invoice_finalization_conflict, idempotency_key_reused, idempotency_conflict, operation_in_progress, source_snapshot_conflict, delivery_idempotency_conflict, delivery_state_conflict, delivery_invoice_state_conflict, delivery_revision_stale] }
        current: { $ref: '#/components/schemas/FinanceV2Invoice' }

    FinanceV2InvoiceDomainError:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error:
          type: string
          enum: [document_totals_mismatch, invalid_customer, invalid_discount, invalid_invoice_dates, invalid_invoice_input, invalid_money, invalid_partner, invalid_product, invalid_quantity, invalid_tax_rate, invoice_not_cancellable, invoice_not_deletable, invoice_not_editable, invoice_not_finalizable, invoice_not_overdue, credit_note_cannot_be_cancelled, delivery_invoice_not_eligible, delivery_kind_invalid, delivery_pdf_unavailable, delivery_recipient_missing, delivery_retry_not_allowed, delivery_smtp_unavailable]

    FinanceV2InvoiceUnprocessable:
      oneOf:
        - { $ref: '#/components/schemas/ValidationError' }
        - { $ref: '#/components/schemas/FinanceV2InvoiceDomainError' }

    FinanceV2Payment:
      type: object
      additionalProperties: false
      required: [id, amount_minor, allocated_minor, unapplied_minor, currency, received_at, reference, counterparty, payment_method_id, source, version]
      properties:
        id: { type: string, format: uuid }
        amount_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$', description: "Signed minor-unit integer string; positive is incoming money, negative is a refund." }
        allocated_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$' }
        unapplied_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$' }
        currency: { type: string, pattern: "^[A-Z]{3}$" }
        received_at: { type: string, format: date-time }
        reference: { type: [string, "null"] }
        counterparty: { type: [string, "null"] }
        payment_method_id: { type: [integer, "null"] }
        source: { anyOf: [{ $ref: '#/components/schemas/FinanceV2InvoiceSourceRef' }, { type: "null" }] }
        version: { type: integer, minimum: 0 }

    FinanceV2PaymentPage:
      type: object
      additionalProperties: false
      required: [data, links, meta]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/FinanceV2Payment' } }
        links: { type: object, additionalProperties: false, properties: { first: { type: string, format: uri }, last: { type: string, format: uri }, prev: { type: [string, "null"], format: uri }, next: { type: [string, "null"], format: uri } }, required: [first, last, prev, next] }
        meta: { type: object, additionalProperties: false, properties: { current_page: { type: integer }, per_page: { type: integer }, total: { type: integer }, last_page: { type: integer } }, required: [current_page, per_page, total, last_page] }

    FinanceV2RecordPaymentInput:
      type: object
      additionalProperties: false
      required: [amount, currency, received_at]
      properties:
        amount: { type: string, pattern: "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", description: "Exact signed decimal string; positive is incoming money, negative is a refund." }
        currency: { type: string, pattern: "^[A-Z]{3}$" }
        received_at: { type: string, format: date-time }
        reference: { type: [string, "null"], maxLength: 255 }
        counterparty: { type: [string, "null"], maxLength: 255 }
        payment_method_id: { type: [integer, "null"], minimum: 1 }
        source_type: { type: [string, "null"], maxLength: 64 }
        source_key: { type: [string, "null"], maxLength: 255 }

    FinanceV2AllocationLineInput:
      type: object
      additionalProperties: false
      required: [invoice_id, amount]
      properties:
        invoice_id: { type: string, format: uuid }
        amount: { type: string, pattern: "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,2})?$", description: "Exact signed decimal string; sign must match the payment's sign." }

    FinanceV2AllocationResult:
      type: object
      additionalProperties: false
      required: [payment, invoices]
      properties:
        payment: { $ref: '#/components/schemas/FinanceV2Payment' }
        invoices: { type: array, items: { $ref: '#/components/schemas/FinanceV2Invoice' } }

    FinanceV2PaymentSuggestions:
      type: object
      additionalProperties: false
      required: [status, requires_confirmation, candidates]
      properties:
        status: { type: string, enum: [none, suggested, ambiguous] }
        requires_confirmation: { type: boolean }
        candidates:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [invoice_id, number, open_minor, currency, score, reason]
            properties:
              invoice_id: { type: string, format: uuid }
              number: { type: string }
              open_minor: { type: string, pattern: '^(?:0|-?[1-9][0-9]*)$' }
              currency: { type: string, pattern: "^[A-Z]{3}$" }
              score: { type: integer }
              reason: { type: string }

    FinanceV2PaymentConflict:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error: { type: string, enum: [idempotency_key_reused, idempotency_conflict, invoice_version_conflict, payment_version_conflict, allocation_reversal_conflict] }

    FinanceV2PaymentDomainError:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error:
          type: string
          enum: [invalid_payment_input, invalid_money, invalid_currency, invalid_reference, invalid_counterparty, invalid_source, allocation_currency_mismatch, allocation_over_limit, allocation_sign_mismatch, allocation_target_not_finalized, allocation_target_cancelled, allocation_zero_amount, allocation_already_reversed]

    FinanceV2PaymentUnprocessable:
      oneOf:
        - { $ref: '#/components/schemas/ValidationError' }
        - { $ref: '#/components/schemas/FinanceV2PaymentDomainError' }

    FinanceV2RecurringInvoiceTemplateInput:
      type: object
      additionalProperties: false
      required: [mode, interval, timezone, start_date, run_time, draft]
      properties:
        mode: { type: string, enum: [draft, auto_send] }
        interval: { type: string, enum: [monthly, quarterly, semiannual, annual] }
        timezone: { type: string, description: "IANA timezone identifier." }
        start_date: { type: string, format: date }
        end_date: { type: [string, "null"], format: date }
        run_time: { type: string, pattern: '^([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$' }
        draft: { $ref: '#/components/schemas/FinanceV2InvoiceDraftInput' }

    FinanceV2RecurringInvoiceTemplateVersionInput:
      type: object
      additionalProperties: false
      required: [effective_from, expected_version, draft]
      properties:
        effective_from: { type: string, format: date }
        expected_version: { type: integer, minimum: 0 }
        draft: { $ref: '#/components/schemas/FinanceV2InvoiceDraftInput' }

    FinanceV2RecurringInvoiceTemplate:
      type: object
      additionalProperties: false
      required: [id, mode, interval, timezone, start_date, end_date, run_time, anchor_day, month_end_anchor, next_run_at, status, paused_at, current_version, version]
      properties:
        id: { type: string, format: uuid }
        mode: { type: string, enum: [draft, auto_send] }
        interval: { type: string, enum: [monthly, quarterly, semiannual, annual] }
        timezone: { type: string }
        start_date: { type: string, format: date }
        end_date: { type: [string, "null"], format: date }
        run_time: { type: string }
        anchor_day: { type: integer, minimum: 1, maximum: 31 }
        month_end_anchor: { type: boolean }
        next_run_at: { type: string, format: date-time }
        status: { type: string, enum: [active, paused, completed] }
        paused_at: { type: [string, "null"], format: date-time }
        current_version:
          type: object
          additionalProperties: false
          required: [number, effective_from, snapshot_sha256]
          properties:
            number: { type: integer, minimum: 1 }
            effective_from: { type: string, format: date }
            snapshot_sha256: { type: string, pattern: "^[a-f0-9]{64}$" }
        version: { type: integer, minimum: 0 }

    FinanceV2RecurringInvoiceTemplatePage:
      type: object
      additionalProperties: false
      required: [data, links, meta]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceTemplate' } }
        links: { type: object, additionalProperties: false, properties: { first: { type: string, format: uri }, last: { type: string, format: uri }, prev: { type: [string, "null"], format: uri }, next: { type: [string, "null"], format: uri } }, required: [first, last, prev, next] }
        meta: { type: object, additionalProperties: false, properties: { current_page: { type: integer }, per_page: { type: integer }, total: { type: integer }, last_page: { type: integer } }, required: [current_page, per_page, total, last_page] }

    FinanceV2RecurringInvoiceRun:
      type: object
      additionalProperties: false
      required: [id, scheduled_for, scheduled_local_date, status, last_completed_step, attempts, claimed_at, claim_expires_at, next_retry_at, last_error_code, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        scheduled_for: { type: string, format: date-time }
        scheduled_local_date: { type: string, format: date }
        status: { type: string, enum: [pending, creating_draft, draft_created, finalizing, finalized, sending, sent, failed] }
        last_completed_step: { type: [string, "null"] }
        attempts: { type: integer, minimum: 0 }
        claimed_at: { type: [string, "null"], format: date-time }
        claim_expires_at: { type: [string, "null"], format: date-time }
        next_retry_at: { type: [string, "null"], format: date-time }
        last_error_code: { type: [string, "null"] }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    FinanceV2RecurringInvoiceRunPage:
      type: object
      additionalProperties: false
      required: [data, links, meta]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceRun' } }
        links: { type: object, additionalProperties: false, properties: { first: { type: string, format: uri }, last: { type: string, format: uri }, prev: { type: [string, "null"], format: uri }, next: { type: [string, "null"], format: uri } }, required: [first, last, prev, next] }
        meta: { type: object, additionalProperties: false, properties: { current_page: { type: integer }, per_page: { type: integer }, total: { type: integer }, last_page: { type: integer } }, required: [current_page, per_page, total, last_page] }

    FinanceV2RecurringConflict:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error: { type: string, enum: [version_conflict, recurring_template_version_conflict, idempotency_key_reused, idempotency_conflict, operation_in_progress] }
        current: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceTemplate' }

    FinanceV2RecurringDomainError:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error:
          type: string
          enum: [invalid_recurring_template_input, invalid_timezone, invalid_interval, invalid_effective_date, invalid_recurring_mode, invalid_money, invalid_quantity, recurring_template_completed, recurring_template_effective_date_before_start, recurring_template_effective_date_conflict]

    FinanceV2RecurringUnprocessable:
      oneOf:
        - { $ref: '#/components/schemas/ValidationError' }
        - { $ref: '#/components/schemas/FinanceV2RecurringDomainError' }

    FinanceV2ProjectInput:
      type: object
      additionalProperties: false
      required: [name, kind, currency]
      properties:
        name: { type: string, maxLength: 255 }
        kind: { type: string, enum: [business, private] }
        budget_minor: { type: string, nullable: true, pattern: '^-?\d+$' }
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        partner_reference: { type: [string, "null"], maxLength: 255 }
        parent_id: { type: [string, "null"], format: uuid, description: "Create only."}
        starts_on: { type: [string, "null"], format: date }
        due_on: { type: [string, "null"], format: date }
        version: { type: integer, minimum: 0, description: "Required for update."}

    FinanceV2ProjectActionInput:
      type: object
      additionalProperties: false
      required: [version]
      properties:
        version: { type: integer, minimum: 0 }
        status: { type: string, enum: [planned, active, on_hold, done, cancelled] }
        parent_id: { type: [string, "null"], format: uuid }

    FinanceV2WorkItemInput:
      type: object
      additionalProperties: false
      required: [title, status, is_milestone]
      properties:
        title: { type: string, maxLength: 255 }
        description: { type: [string, "null"], maxLength: 10000 }
        status: { type: string, enum: [open, in_progress, done] }
        starts_on: { type: [string, "null"], format: date }
        due_on: { type: [string, "null"], format: date }
        estimate_hours: { type: [string, "null"], pattern: '^-?(0|[1-9][0-9]*)(\.[0-9]{1,4})?$' }
        is_milestone: { type: boolean }
        product_reference: { type: [string, "null"] }
        version: { type: integer, minimum: 0, description: "Required for update."}

    FinanceV2TimeEntryInput:
      type: object
      additionalProperties: false
      required: [worked_on, hours, billable, currency]
      properties:
        work_item_id: { type: [string, "null"], format: uuid }
        worked_on: { type: string, format: date }
        hours: { type: string, pattern: '^-?(0|[1-9][0-9]*)(\.[0-9]{1,4})?$' }
        description: { type: [string, "null"], maxLength: 10000 }
        billable: { type: boolean }
        hourly_rate_minor: { type: string, nullable: true, pattern: '^-?\d+$' }
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        version: { type: integer, minimum: 0, description: "Required for update."}

    FinanceV2LedgerEntryInput:
      type: object
      additionalProperties: false
      required: [direction, amount_minor, currency]
      properties:
        direction: { type: string, enum: [in, out] }
        amount_minor: { type: string, pattern: '^-?\d+$' }
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        occurred_on: { type: [string, "null"], format: date }
        title: { type: [string, "null"], maxLength: 255 }
        note: { type: [string, "null"], maxLength: 10000 }
        category_reference: { type: [string, "null"] }
        payment_method_reference: { type: [string, "null"] }
        version: { type: integer, minimum: 0, description: "Required for update."}

    FinanceV2ProjectDocumentInput:
      type: object
      additionalProperties: false
      required: [source_type, source_reference, role]
      properties:
        source_type: { type: string, enum: [finance_series, legacy_invoice, finance_receipt, bank_transaction, bank_transaction_receipt] }
        source_reference: { type: string, maxLength: 255, description: "Opaque owner-scoped reference."}
        pinned_revision_id: { type: [integer, "null"], minimum: 1 }
        role: { type: string, enum: [source_quote, quote, invoice, payment, receipt, file, photo, other] }

    FinanceV2ProjectNoteInput:
      type: object
      additionalProperties: false
      required: [type, visibility, body]
      properties:
        revision_id: { type: [integer, "null"], minimum: 1, description: "Document-series notes only."}
        type: { type: string, enum: [note, decision, call, email, meeting, correction] }
        visibility: { type: string, enum: [internal, customer] }
        body: { type: string, minLength: 1, maxLength: 100000 }
        supersedes_note_id: { type: [integer, "null"], minimum: 1 }

    FinanceV2Project:
      type: object
      additionalProperties: false
      required: [id, parent_id, parent_available, name, kind, status, partner_reference, starts_on, due_on, budget_minor, currency, version, archived, created_at, updated_at]
      properties:
        id: { type: string, format: uuid }
        parent_id: { type: [string, "null"], format: uuid }
        parent_available: { type: boolean }
        name: { type: string }
        kind: { type: string, enum: [business, private] }
        status: { type: string, enum: [planned, active, on_hold, done, cancelled] }
        partner_reference: { type: [string, "null"] }
        starts_on: { type: [string, "null"], format: date }
        due_on: { type: [string, "null"], format: date }
        budget_minor: { type: string, nullable: true, pattern: '^-?\d+$' }
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        version: { type: integer, minimum: 0 }
        archived: { type: boolean }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }

    FinanceV2ProjectPage:
      type: object
      additionalProperties: false
      required: [data, meta, links]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/FinanceV2Project' } }
        meta: { type: object, required: [current_page, per_page, total, last_page], properties: { current_page: { type: integer }, per_page: { type: integer }, total: { type: integer }, last_page: { type: integer } } }
        links: { type: object, required: [first, last, prev, next], properties: { first: { type: string, format: uri }, last: { type: string, format: uri }, prev: { type: [string, "null"], format: uri }, next: { type: [string, "null"], format: uri } } }

    FinanceV2WorkItem:
      type: object
      additionalProperties: false
      required: [resource_type, id, title, status, estimate_quantity_scaled, is_milestone, sort, version]
      properties:
        resource_type: { type: string, enum: [work_item] }
        id: { type: string, format: uuid }
        title: { type: string }
        description: { type: [string, "null"] }
        status: { type: string, enum: [open, in_progress, done] }
        starts_on: { type: [string, "null"], format: date }
        due_on: { type: [string, "null"], format: date }
        estimate_quantity_scaled: { type: string, nullable: true, pattern: '^-?\d+$' }
        is_milestone: { type: boolean }
        sort: { type: integer }
        product_reference: { type: [string, "null"] }
        version: { type: integer, minimum: 0 }

    FinanceV2TimeEntry:
      type: object
      additionalProperties: false
      required: [resource_type, id, work_item_id, worked_on, quantity_scaled, billable, hourly_rate_minor, currency, version]
      properties:
        resource_type: { type: string, enum: [time_entry] }
        id: { type: string, format: uuid }
        work_item_id: { type: [string, "null"], format: uuid }
        worked_on: { type: string, format: date }
        quantity_scaled: { type: string, pattern: '^-?\d+$' }
        description: { type: [string, "null"] }
        billable: { type: boolean }
        hourly_rate_minor: { type: string, nullable: true, pattern: '^-?\d+$' }
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        invoice_target_reference: { type: [string, "null"] }
        invoiced_at: { type: [string, "null"], format: date-time }
        version: { type: integer, minimum: 0 }

    FinanceV2LedgerEntry:
      type: object
      additionalProperties: false
      required: [resource_type, id, direction, amount_minor, currency, version]
      properties:
        resource_type: { type: string, enum: [ledger_entry] }
        id: { type: string, format: uuid }
        direction: { type: string, enum: [in, out] }
        amount_minor: { type: string, pattern: '^-?\d+$' }
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        occurred_on: { type: [string, "null"], format: date }
        title: { type: [string, "null"] }
        note: { type: [string, "null"] }
        category_reference: { type: [string, "null"] }
        payment_method_reference: { type: [string, "null"] }
        version: { type: integer, minimum: 0 }

    FinanceV2ProjectTotals:
      type: object
      additionalProperties: false
      required: [project_id, currencies]
      properties:
        project_id: { type: string, format: uuid }
        currencies:
          type: object
          additionalProperties:
            type: object
            additionalProperties: false
            required: [hours_scaled, time_value_minor, ledger_minor, financial_minor]
            properties:
              hours_scaled: { type: string, pattern: '^-?\d+$' }
              time_value_minor: { type: string, pattern: '^-?\d+$' }
              ledger_minor: { type: string, pattern: '^-?\d+$' }
              financial_minor: { type: string, pattern: '^-?\d+$' }

    FinanceV2ProjectDocument:
      type: object
      additionalProperties: false
      required: [link_id, project_id, source, role, snapshot, current, availability, attached_at, detached, detached_at]
      properties:
        link_id: { type: integer, minimum: 1 }
        project_id: { type: string, format: uuid }
        source: { type: object, required: [source_type, source_reference, pinned_revision_id], properties: { source_type: { type: string }, source_reference: { type: string }, pinned_revision_id: { type: [integer, "null"] } } }
        role: { type: string }
        snapshot: { type: object, description: "Strict allowlist; storage paths and OCR payloads are never returned."}
        current: { type: [object, "null"] }
        availability: { type: string, enum: [available, deleted, missing] }
        attached_at: { type: string, format: date-time }
        detached: { type: boolean }
        detached_at: { type: [string, "null"], format: date-time }

    FinanceV2HistoryItem:
      type: object
      additionalProperties: false
      required: [id, source_kind, type, visibility, body, supersedes_note_id, payload, author_id, occurred_at, series_id, revision_id]
      properties:
        id: { type: integer, minimum: 1 }
        source_kind: { type: string, enum: [project_note, document_note, project_activity, document_activity] }
        type: { type: string }
        visibility: { type: [string, "null"], enum: [internal, customer, null] }
        body: { type: [string, "null"] }
        supersedes_note_id: { type: [integer, "null"], minimum: 1 }
        subject_type: { type: [string, "null"] }
        subject_reference: { type: [string, "null"] }
        payload: { type: object, description: "Allowlisted audit payload; secrets and raw errors are scrubbed."}
        author_id: { type: [integer, "null"], minimum: 1 }
        occurred_at: { type: string, format: date-time }
        series_id: { type: [string, "null"], format: uuid }
        revision_id: { type: [integer, "null"], minimum: 1 }

    FinanceV2ProjectConflict:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error: { type: string, enum: [project_archived, time_invoiced, document_already_attached, document_not_attached, idempotency_key_reused, version_conflict, operation_in_progress] }
        current: { $ref: '#/components/schemas/FinanceV2Project' }

    FinanceV2ProjectDomainError:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error: { type: string, enum: [invalid_transition, invalid_project_input] }

paths:

  /auth/login:
    post:
      tags: [Auth]
      operationId: spaLogin
      summary: Browser login (email+password+optional 2FA) to a bearer token
      security: []
      description: >
        Backend-agnostic login: validates credentials (and TOTP/recovery code
        when 2FA is confirmed) and returns a device-scoped Sanctum bearer token.
        On a 2FA-required account with no/invalid code, returns 422 with
        {two_factor: true}. Native clients that send `install_id` (+ device_name/
        app_version/os_version) are registered as a real device — same as QR
        pairing — so they appear under "Connected devices" (revoke/wipe/heartbeat)
        and re-login on the same install_id replaces the previous device row.
        The account must have a verified email before a bearer is minted — an
        unverified account returns 403 {status:"verify-email"} (v1.562.0). A
        blocked account fails with the same generic 422 as bad credentials (no
        enumeration). Throttled at 10 req/min → 429.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, format: email }
                password: { type: string }
                code: { type: [string, "null"] }
                recovery_code: { type: [string, "null"] }
                device_name: { type: [string, "null"], description: "Device label (native) or 'web' default." }
                install_id: { type: [string, "null"], description: "Stable app install id — presence marks a native device; enables device registration + dedup." }
                app_version: { type: [string, "null"] }
                os_version: { type: [string, "null"] }
      responses:
        "200":
          description: Token + user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
                  user: { $ref: '#/components/schemas/MeUser' }
        "403":
          description: >
            Email not verified — no bearer is minted until the address is verified.
          content:
            application/json:
              schema: { type: object, properties: { status: { type: string, example: verify-email } } }
        "422":
          description: >
            Invalid credentials (also returned generically for a blocked account,
            no enumeration), or {two_factor:true} when a 2FA code is required.
        "429": { $ref: '#/components/responses/RateLimited' }
  /auth/logout:
    post:
      tags: [Auth]
      operationId: spaLogout
      summary: Revoke the current bearer token
      responses:
        "200": { description: "OK."}
        "401": { $ref: '#/components/responses/Unauthorized' }

  /auth/passkey/options:
    post:
      tags: [Passkeys]
      operationId: passkeyLoginOptions
      summary: Passwordless sign-in — WebAuthn assertion options
      security: []
      description: >
        Public. Returns a one-time challenge (`options`, standard WebAuthn
        PublicKeyCredentialRequestOptionsJSON) plus an opaque `handle` that binds
        the challenge for /auth/passkey/verify. Feed `options` to
        navigator.credentials.get(). Throttled 30/min.
      responses:
        "200":
          description: Request options + handle.
          content:
            application/json:
              schema:
                type: object
                properties:
                  handle: { type: string }
                  options: { type: object, additionalProperties: true }
        "429": { $ref: '#/components/responses/RateLimited' }
  /auth/passkey/verify:
    post:
      tags: [Passkeys]
      operationId: passkeyLoginVerify
      summary: Passwordless sign-in — verify assertion, mint a bearer token
      security: []
      description: >
        Public. Verifies the authenticator assertion against the cached
        challenge and mints a device-scoped Sanctum bearer token. 422
        {message:"passkey_failed"} on any invalid/expired assertion; 403
        {status:"verify-email"} for an unverified account; 403
        {message:"blocked"} for a blocked account. Throttled 30/min.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [handle, credential]
              properties:
                handle: { type: string }
                credential: { type: object, additionalProperties: true, description: "Serialized PublicKeyCredential (assertion) as returned by the webauthn browser helper." }
      responses:
        "200":
          description: Token + user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
                  user: { $ref: '#/components/schemas/MeUser' }
        "403": { description: "Email not verified or account blocked." }
        "422": { description: "Assertion invalid/expired." }
        "429": { $ref: '#/components/responses/RateLimited' }

  # --------------------------------------------------------------------------
  # Contacts module (module:contacts + device auth). Mirrors the web routes.
  # --------------------------------------------------------------------------
  /up:
    servers:
      - url: /
        description: Site root (this endpoint lives above the /api/v1 base path).
    get:
      tags: [Status]
      operationId: healthUp
      summary: Application health check (up-check)
      description: >
        Laravel's framework health endpoint at the site ROOT (`/up`, not
        `/api/v1/up`). Unauthenticated, unthrottled. Returns HTTP 200 while the
        application booted cleanly (runs the framework health checks) and a 500
        otherwise. Apps poll it to confirm the server is reachable and healthy
        before/independently of API calls. The body is a small HTML page — clients
        should treat the STATUS CODE as the signal, not the body.
      security: []
      responses:
        "200":
          description: Application is up and healthy.
          content:
            text/html:
              schema:
                type: string
        "429":
          description: Too Many Requests — a fronting reverse proxy may throttle excessive polling.
        "500":
          description: Application is unhealthy (a health check threw).

  # --------------------------------------------------------------------------
  # Auth
  # --------------------------------------------------------------------------

  /auth/pair:
    post:
      tags: [Auth]
      operationId: authPair
      summary: Claim a pairing code (public)
      description: >
        The mobile app scans a QR code from the user's web profile and claims the
        one-time code here. Moves the pairing to pending-approval status. No bearer
        token required. Throttle: 30 req/min per IP.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code, device_name]
              properties:
                code:
                  type: string
                  description: One-time pairing code from the QR.
                device_name:
                  type: string
                  maxLength: 60
                  description: Human-readable device name shown in the web UI.
      responses:
        "200":
          description: Code claimed; waiting for owner approval.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [pending]
        "410":
          description: Code not found, expired, or in the wrong state (Gone).
        "422":
          description: Validation error (missing/invalid fields).
        "429":
          description: Rate limit exceeded.

  /auth/pair/collect:
    post:
      tags: [Auth]
      operationId: authCollect
      summary: Poll for pairing approval (public)
      description: >
        Poll with the same code. Returns `status: pending` until the owner approves
        the device in the web UI, then returns the Sanctum bearer token exactly once.
        No bearer token required. Throttle: 30 req/min per IP.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code:
                  type: string
                  description: The same one-time pairing code.
                install_id:
                  type: string
                  maxLength: 64
                  description: >
                    Optional device-local random id (NOT a secret) that lets the
                    server audit trail be correlated with the client's own
                    diagnostic log. Stored on the token; echoed in device audit meta.
                app_version:
                  type: string
                  maxLength: 32
                  description: Optional client app version reported at pairing (non-secret).
                os_version:
                  type: string
                  maxLength: 32
                  description: Optional client OS version reported at pairing (non-secret).
      responses:
        "200":
          description: Pending or approved.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      status:
                        type: string
                        enum: [pending]
                  - type: object
                    properties:
                      status:
                        type: string
                        enum: [approved]
                      token:
                        type: string
                        description: Sanctum bearer token for subsequent API calls.
                      user:
                        $ref: "#/components/schemas/MeUser"
        "410":
          description: Code not found, expired, rejected, or already consumed (Gone).
        "429":
          description: Rate limit exceeded.

  /auth/session:
    delete:
      tags: [Auth]
      operationId: authDestroy
      summary: Revoke the current bearer token
      description: >
        Deletes the Sanctum token authenticating this request (logout / remote wipe
        acknowledgement). Throttle: none (uses general API throttle).
      responses:
        "200":
          description: Token revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "401":
          description: Unauthenticated.

  # --------------------------------------------------------------------------
  # Me / Device
  # --------------------------------------------------------------------------

  /me:
    get:
      tags: [Me/Device]
      operationId: meShow
      summary: Authenticated user info
      description: >
        Returns the authenticated user's profile and a `wipe` flag that signals
        the owner has requested a remote wipe of this token. No throttle beyond
        the default API rate.
      responses:
        "200":
          description: User payload.
          content:
            application/json:
              schema:
                type: object
                required: [user, wipe]
                properties:
                  user:
                    $ref: "#/components/schemas/MeUser"
                  wipe:
                    type: boolean
                    description: >
                      Kill switch. If true, the owner has requested a remote wipe of
                      this token — the client should erase its local data and log out.
        "401":
          description: Unauthenticated.

  /avatar:
    get:
      tags: [Me/Device]
      operationId: avatarShow
      summary: Stream the authenticated user's avatar
      description: >
        Streams the user's stored avatar image (a non-secret profile image).
        Returns 404 if no avatar is stored. Throttle: 120 req/min.
      responses:
        "200":
          description: Avatar image bytes.
          content:
            image/*:
              schema:
                type: string
                format: binary
        "401":
          description: Unauthenticated.
        "404":
          description: No avatar stored.
        "429":
          description: Rate limit exceeded.
    post:
      tags: [Me/Device]
      operationId: avatarStore
      summary: Upload / replace the authenticated user's avatar
      description: >
        Uploads an avatar image (multipart, field `avatar`; jpeg/png/webp/gif,
        max 10 MiB). Re-encoded server-side to a square 512×512 JPEG (metadata
        stripped); the previous avatar is deleted. Non-secret profile image.
        Throttle 60/min.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [avatar]
              properties:
                avatar: { type: string, format: binary }
      responses:
        "200":
          description: Stored.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  has_avatar: { type: boolean }
        "422": { description: "Not a valid image / too large."}
        "429": { description: "Rate limit exceeded."}
    delete:
      tags: [Me/Device]
      operationId: avatarDestroy
      summary: Remove the authenticated user's avatar
      description: Deletes the stored avatar. Throttle 60/min.
      responses:
        "200":
          description: Removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  has_avatar: { type: boolean }
        "429": { description: "Rate limit exceeded."}

  /device/push-endpoint:
    post:
      tags: [Me/Device]
      operationId: devicePushEndpointStore
      summary: Register the per-device UnifiedPush endpoint
      description: >
        Stores an HTTPS push endpoint (a UnifiedPush/ntfy topic URL) on the calling
        device token; SendPushJob POSTs notification payloads there. Stored encrypted.
        Validated as https + a resolvable, non-link-local/metadata host (SSRF guard).
        Throttle 60/min.
      security: [ { bearerAuth: [] } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [endpoint]
              properties:
                endpoint: { type: string, format: uri, maxLength: 2048, description: "https URL of the push endpoint." }
      responses:
        "200": { description: "Registered.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean } } } } } }
        "401": { $ref: '#/components/responses/Unauthorized' }
        "422": { description: "Invalid or disallowed endpoint (not https / blocked host)." }
        "429": { description: "Rate limit exceeded."}
    delete:
      tags: [Me/Device]
      operationId: devicePushEndpointDestroy
      summary: Clear the per-device push endpoint
      description: Removes the push endpoint from the calling device token (push disabled). Throttle 60/min.
      security: [ { bearerAuth: [] } ]
      responses:
        "200": { description: "Cleared.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean } } } } } }
        "401": { $ref: '#/components/responses/Unauthorized' }
        "429": { description: "Rate limit exceeded."}

  /device/heartbeat:
    post:
      tags: [Me/Device]
      operationId: deviceHeartbeat
      summary: Record device sync activity
      description: >
        CLI/background clients call this to record whether they are currently syncing.
        Returns the remote-wipe flag so any heartbeat also delivers the kill switch.
        Throttle: 120 req/min.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [state]
              properties:
                state:
                  type: string
                  enum: [idle, syncing]
                  description: Current sync state of the client.
                detail:
                  type: [string, "null"]
                  maxLength: 160
                  description: Optional human-readable detail string shown in the devices list.
      responses:
        "200":
          description: Heartbeat recorded.
          content:
            application/json:
              schema:
                type: object
                required: [wipe]
                properties:
                  wipe:
                    type: boolean
                    description: >
                      If true the owner has requested a remote wipe of this token.
                      The client should erase its local data and log out.
        "422":
          description: Validation error (state not in allowed enum).
        "429":
          description: Rate limit exceeded.

  # --------------------------------------------------------------------------
  # Site-icon proxy (bank logos / partner favicons for the Finance module)
  # --------------------------------------------------------------------------

  /passwords/icon:
    get:
      tags: [Company]
      operationId: passwordsIcon
      summary: Fetch favicon/BIMI for a domain
      description: >
        Returns a data URI (base64-encoded image) for the best available icon for
        the given domain (favicon → BIMI). The fetch goes through the server's SSRF
        guard; the result is returned as a data URI. The domain is not persisted.
        Throttle: 1200 req/min.
      parameters:
        - name: domain
          in: query
          required: true
          schema:
            type: string
          description: Domain to look up (e.g. "github.com").
      responses:
        "200":
          description: Icon data URI or null.
          content:
            application/json:
              schema:
                type: object
                properties:
                  icon:
                    type: [string, "null"]
                    description: Data URI (e.g. "data:image/png;base64,...") or null if none found.
        "429":
          description: Rate limit exceeded.
  # --------------------------------------------------------------------------
  # Devices
  # --------------------------------------------------------------------------

  /devices:
    get:
      tags: [Devices]
      operationId: devicesIndex
      summary: List the caller's connected devices
      description: >
        Returns all Sanctum tokens (connected devices) for the authenticated user,
        most-recently-used first. Includes live sync state, last-used time, the app/OS
        build + a short install id (non-secret client correlation), and whether a
        remote wipe has been requested. No per-route throttle beyond default.
      responses:
        "200":
          description: List of connected devices.
          content:
            application/json:
              schema:
                type: object
                required: [devices]
                properties:
                  devices:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Sanctum token ID.
                        current:
                          type: boolean
                          description: >
                            True for the token making this request, so a client can
                            refuse to revoke or wipe itself. Always false for
                            session-auth (web) callers.
                        name:
                          type: string
                          description: Human-readable device name.
                        meta:
                          type: string
                          description: >
                            Formatted string combining IP address and last-used time
                            (e.g. "192.168.1.1 · last used 3 hours ago").
                        ip:
                          type: [string, "null"]
                          description: Last-seen IP address of the device (non-secret; owner-only).
                        last_used_at:
                          type: [string, "null"]
                          format: date-time
                          description: ISO-8601 timestamp of the device's last API request.
                        created_at:
                          type: [string, "null"]
                          format: date-time
                          description: ISO-8601 timestamp when this device token was minted (connected).
                        expires_at:
                          type: [string, "null"]
                          format: date-time
                          description: ISO-8601 absolute expiry of the token (Sanctum lifetime), or null.
                        os_version:
                          type: [string, "null"]
                          description: Reported OS version (structured; also folded into `version`).
                        app_version:
                          type: [string, "null"]
                          description: Reported app build (structured; also folded into `version`).
                        abilities:
                          type: array
                          items: { type: string }
                          description: Sanctum abilities granted to this token (e.g. ["device"]).
                        version:
                          type: [string, "null"]
                          description: Non-secret app/OS build (e.g. "iOS 18.2 · 1.5.0"), when reported.
                        installId:
                          type: [string, "null"]
                          description: >
                            Last 6 chars of the device's non-secret install id — helps the
                            owner distinguish devices. Re-pairing the same install id
                            supersedes the previous token (device.superseded) rather than
                            stacking a duplicate row.
                        syncing:
                          type: boolean
                          description: >
                            True when the device reported syncing state within the last
                            3 minutes.
                        syncDetail:
                          type: [string, "null"]
                          description: Short detail string from the last heartbeat (syncing only).
                        syncSeen:
                          type: [string, "null"]
                          description: Human-readable time since the last heartbeat was received.
                        wipeRequested:
                          type: boolean
                          description: True when the owner has flagged this device for remote wipe.
                        pushHost:
                          type: [string, "null"]
                          description: >
                            Scheme+host of this device's registered push endpoint
                            (e.g. https://ntfy.sh), or null if none. The topic path is
                            never emitted (it is the push capability).
        "401":
          description: Unauthenticated.

  /devices/{token}/push:
    delete:
      tags: [Devices]
      operationId: devicesRevokePush
      summary: Clear a device's push endpoint
      description: >
        Removes the stored push endpoint from the given device token so the server
        stops POSTing notifications there. Owner-scoped. Throttle: 20 req/min.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Sanctum token ID of the device whose push endpoint to clear.
      responses:
        "200":
          description: Push endpoint cleared.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "401":
          description: Unauthenticated.
        "429":
          description: Rate limit exceeded.

  /devices/{token}:
    delete:
      tags: [Devices]
      operationId: devicesRevoke
      summary: Revoke a paired device
      description: >
        Deletes the Sanctum token for the given device, immediately revoking its
        access. Owner-scoped (can only revoke own tokens). Throttle: 20 req/min.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Sanctum token ID of the device to revoke.
      responses:
        "200":
          description: Device revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "401":
          description: Unauthenticated.
        "429":
          description: Rate limit exceeded.

  /devices/{token}/wipe:
    post:
      tags: [Devices]
      operationId: devicesWipe
      summary: Request a remote wipe for a device
      description: >
        Flags the device's Sanctum token with a wipe request. The token remains
        valid so the device can fetch the flag on its next heartbeat and self-erase.
        Owner-scoped. Throttle: 20 req/min.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Sanctum token ID of the device to wipe.
      responses:
        "200":
          description: Wipe flag set.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "401":
          description: Unauthenticated.
        "429":
          description: Rate limit exceeded.

  # --------------------------------------------------------------------------
  # Notifications
  # --------------------------------------------------------------------------

  /notifications:
    get:
      tags: [Notifications]
      operationId: notificationsIndex
      summary: List recent notifications
      description: >
        Returns up to 30 recent in-app notifications for the authenticated user,
        with an unread count. Supports ETag-based conditional requests — if the
        client sends If-None-Match matching the current ETag the server returns
        304 Not Modified with no body, skipping the row fetch entirely.
        No per-route throttle beyond default.
      parameters:
        - name: If-None-Match
          in: header
          required: false
          schema:
            type: string
          description: ETag value from a previous response. Returns 304 if unchanged.
      responses:
        "200":
          description: Notification list with unread count.
          headers:
            ETag:
              description: >
                Opaque change-signature derived from the newest id, total count,
                latest update time, and unread count. Send back as If-None-Match.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required: [unread, items]
                properties:
                  unread:
                    type: integer
                    description: Count of unread notifications.
                  items:
                    type: array
                    items:
                      type: object
                      required: [id, level, category, title, read, at]
                      properties:
                        id:
                          type: integer
                        level:
                          type: string
                          description: Severity level (e.g. info, warning, error).
                        category:
                          type: string
                          description: Category (non-null; defaults to "general").
                        title:
                          type: string
                        body:
                          type: [string, "null"]
                        read:
                          type: boolean
                        at:
                          type: [string, "null"]
                          format: date-time
        "304":
          description: Not Modified — ETag matched, no payload.
        "401":
          description: Unauthenticated.

  /notifications/{notification}/read:
    post:
      tags: [Notifications]
      operationId: notificationsMarkRead
      summary: Mark a single notification as read
      description: >
        Sets read_at to now for the given notification. Owner-scoped (403 if the
        notification belongs to another user). No per-route throttle.
      parameters:
        - name: notification
          in: path
          required: true
          schema:
            type: integer
          description: Notification ID.
      responses:
        "200":
          description: Marked as read.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "403":
          description: Notification does not belong to the caller.
        "404":
          description: Notification not found.

  /notifications/read-all:
    post:
      tags: [Notifications]
      operationId: notificationsMarkAllRead
      summary: Mark all notifications as read
      description: >
        Sets read_at to now on all unread notifications for the authenticated
        user. Idempotent. No per-route throttle.
      responses:
        "200":
          description: All notifications marked as read.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "401":
          description: Unauthenticated.

  # --------------------------------------------------------------------------
  # Account (GDPR export, deletion, web-session revocation)
  # --------------------------------------------------------------------------

  /account/export:
    get:
      tags: [Account]
      operationId: accountExport
      summary: GDPR data export (streamed zip)
      description: >
        Streams a zip file containing the user's data as JSON, one file per data
        module: finance (invoices, bank transactions, receipts, payment methods,
        partners, projects), the Paperless-ngx integration settings, and the
        account/display settings. Data only — no blob bytes. The zip is generated
        on the fly and not stored server-side. Throttle: 6 req/min.
      responses:
        "200":
          description: Zip archive streamed to the client.
          content:
            application/zip:
              schema:
                type: string
                format: binary
                description: >
                  ledgerline-export-{timestamp}.zip containing one JSON file per
                  data module.
        "401":
          description: Unauthenticated.
        "429":
          description: Rate limit exceeded.

  /account:
    delete:
      tags: [Account]
      operationId: accountDestroy
      summary: Permanently delete the account (GDPR erasure)
      description: >
        Permanently purges the account and all owned data (all rows deleted, all
        stored files removed). The presented bearer token is revoked after deletion.
        Requires the user's email as a confirmation
        string to prevent accidental deletion. No per-route throttle.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [confirmation]
              properties:
                confirmation:
                  type: string
                  description: >
                    Must equal the authenticated user's email address exactly.
                    Returns 422 on mismatch.
      responses:
        "200":
          description: Account deleted.
          content:
            application/json:
              schema:
                type: object
                required: [deleted]
                properties:
                  deleted:
                    type: boolean
                    example: true
        "422":
          description: Confirmation string does not match the user's email.
        "401":
          description: Unauthenticated.

  /account/sessions/{id}:
    delete:
      tags: [Account]
      operationId: accountSessionsRevoke
      summary: Revoke another active web session
      description: >
        Deletes the given web session row for the authenticated user. Cannot revoke
        the caller's own current session. Idempotent (missing or already-deleted
        session is a no-op). No per-route throttle.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Session ID to revoke.
      responses:
        "200":
          description: Session revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "401":
          description: Unauthenticated.

  /account/sessions:
    get:
      tags: [Account]
      operationId: accountSessionsIndex
      summary: List active web sessions
      description: >
        The caller's active web (browser) sessions, newest first. Only populated when
        the server uses the database session driver (empty array otherwise). `current`
        flags the caller's own session and is never true on a token request. No secret
        values.
      responses:
        "200":
          description: Session list.
          content:
            application/json:
              schema:
                type: object
                required: [sessions]
                properties:
                  sessions:
                    type: array
                    items:
                      type: object
                      required: [id, ip, user_agent, last_active, current]
                      properties:
                        id: { type: string }
                        ip: { type: [string, "null"] }
                        user_agent: { type: [string, "null"] }
                        last_active: { type: integer, description: "Unix timestamp of last activity." }
                        current: { type: boolean }
        "401": { $ref: "#/components/responses/Unauthorized" }

  /locale:
    post:
      tags: [Preferences]
      operationId: localeUpdate
      summary: Update the UI language
      description: >
        Persists the chosen locale on the user's profile and (for web requests) in
        the session. The locale must be one of the values configured in
        config/locales.php. No per-route throttle beyond default.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [locale]
              properties:
                locale:
                  type: string
                  description: BCP 47 locale code (e.g. "en", "de"). Must be in the supported list.
      responses:
        "200":
          description: Locale updated.
          content:
            application/json:
              schema:
                type: object
                required: [ok, locale]
                properties:
                  ok:
                    type: boolean
                    example: true
                  locale:
                    type: string
                    description: The locale that was set.
        "422":
          description: Unsupported locale value.
        "401":
          description: Unauthenticated.

  /theme:
    post:
      tags: [Preferences]
      operationId: themeUpdate
      summary: Update the colour scheme preference
      description: >
        Persists the user's chosen colour scheme. No per-route throttle beyond default.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [theme]
              properties:
                theme:
                  type: string
                  enum: [light, dark, system]
                  description: Colour scheme preference.
      responses:
        "200":
          description: Theme updated.
          content:
            application/json:
              schema:
                type: object
                required: [ok, theme]
                properties:
                  ok:
                    type: boolean
                    example: true
                  theme:
                    type: string
                    enum: [light, dark, system]
        "422":
          description: Invalid theme value.
        "401":
          description: Unauthenticated.

  /preferences:
    post:
      tags: [Preferences]
      operationId: preferencesUpdate
      summary: Update global display preferences (units + clock format)
      description: >
        Persists the user's non-secret DISPLAY preferences — measurement units and
        12/24h clock. These are presentation choices only (the underlying data stays
        stored data is unchanged); the client applies them to its own rendering. Every field is
        optional; only the sent fields change. Mirrored in GET /me.preferences. No
        per-route throttle beyond default.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                distance:
                  type: string
                  enum: [km, mi]
                elevation:
                  type: string
                  enum: [m, ft]
                weight:
                  type: string
                  enum: [kg, lb]
                temp:
                  type: string
                  enum: [c, f]
                glucose:
                  type: string
                  enum: [mgdl, mmoll]
                time_format:
                  type: string
                  enum: [24h, 12h]
                timezone:
                  type: [string, "null"]
                  description: "IANA timezone override; empty string clears it (follow the browser)."
                date_format:
                  type: string
                  enum: [system, dmy, dmy_dot, mdy, ymd]
                mail_load_remote:
                  type: boolean
                  deprecated: true
                  description: "Deprecated and ignored: remote mail content is controlled per message."
                mail_signature:
                  type: [string, "null"]
                  maxLength: 5000
                notifications:
                  type: object
                  description: "Per-category push prefs (merged): { \"<category>\": { \"push\": bool } }."
                  additionalProperties:
                    type: object
                    properties:
                      push: { type: boolean }
      responses:
        "200":
          description: Preferences updated; returns the full preference set.
          content:
            application/json:
              schema:
                type: object
                required: [ok, preferences]
                properties:
                  ok:
                    type: boolean
                    example: true
                  preferences:
                    $ref: "#/components/schemas/DisplayPreferences"
        "422":
          description: Invalid preference value.
        "401":
          description: Unauthenticated.

  /groups:
    get:
      tags: [Groups]
      operationId: groupsIndex
      summary: List all groups (admin)
      description: >
        Returns every group with its limits, shareable flag and members. Requires the
        admin role (manage-global-settings) on top of the device token.
      responses:
        "200":
          description: The groups.
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items: { $ref: "#/components/schemas/Group" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    post:
      tags: [Groups]
      operationId: groupsStore
      summary: Create a group (admin)
      description: "Throttle: 60 req/min."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, maxLength: 100 }
                max_connected_devices: { type: [integer, "null"], minimum: 1, maximum: 50 }
                shareable: { type: boolean }
                modules: { type: [array, "null"], items: { type: string, enum: [finance] }, description: "Enabled module keys (null = all)." }
                members:
                  type: array
                  items: { type: integer }
                  description: User ids to set as members.
      responses:
        "201":
          description: Created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  group: { $ref: "#/components/schemas/Group" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /groups/{group}:
    put:
      tags: [Groups]
      operationId: groupsUpdate
      summary: Update a group and sync its members (admin)
      description: "Members is the full set — an omitted/empty array clears membership. Throttle: 60 req/min."
      parameters:
        - name: group
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, maxLength: 100 }
                max_connected_devices: { type: [integer, "null"], minimum: 1, maximum: 50 }
                shareable: { type: boolean }
                modules: { type: [array, "null"], items: { type: string, enum: [finance] }, description: "Enabled module keys (null = all)." }
                members:
                  type: array
                  items: { type: integer }
      responses:
        "200":
          description: Updated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  group: { $ref: "#/components/schemas/Group" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Groups]
      operationId: groupsDestroy
      summary: Delete a group (admin)
      description: "Members keep their accounts; the group's limits stop applying. Throttle: 60 req/min."
      parameters:
        - name: group
          in: path
          required: true
          schema: { type: integer }
      responses:
        "204":
          description: Deleted.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/health:
    get:
      tags: [Finance]
      operationId: financeV2Health
      summary: Finance v2 module contract and schema version
      description: >
        Authenticated readiness contract for the isolated finance-v2 module.
        Requires a Sanctum bearer with the `device` ability, completed mandatory
        2FA enrollment, and the Finance module enabled for the account. Throttle:
        120 requests/minute.
      security: [ { bearerAuth: [] } ]
      responses:
        "200":
          description: Finance v2 is enabled and reports its schema contract.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [module, schemaVersion]
                properties:
                  module: { type: string, enum: [finance] }
                  schemaVersion: { type: integer, enum: [1] }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/projects:
    get:
      tags: [Finance]
      operationId: financeV2ProjectsIndex
      summary: List owner-scoped projects
      parameters:
        - { name: q, in: query, schema: { type: string, maxLength: 255 } }
        - { name: status, in: query, schema: { type: string, enum: [planned, active, on_hold, done, cancelled] } }
        - { name: kind, in: query, schema: { type: string, enum: [business, private] } }
        - { name: partner_reference, in: query, schema: { type: string } }
        - { name: parent_id, in: query, schema: { type: string, format: uuid } }
        - { name: archived, in: query, schema: { type: boolean, default: false } }
        - { name: starts_from, in: query, schema: { type: string, format: date } }
        - { name: starts_to, in: query, schema: { type: string, format: date } }
        - { name: due_from, in: query, schema: { type: string, format: date } }
        - { name: due_to, in: query, schema: { type: string, format: date } }
        - { name: sort, in: query, schema: { type: string, enum: [updated_at, name, starts_on, due_on, status] } }
        - { name: direction, in: query, schema: { type: string, enum: [asc, desc] } }
        - { name: page, in: query, schema: { type: integer, minimum: 1 } }
        - { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }
      responses:
        "200": { description: "Project page.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectPage' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Finance]
      operationId: financeV2ProjectsCreate
      summary: Create a project
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectInput' } } } }
      responses:
        "201": { description: "Project created.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Project' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/projects/{project}:
    get:
      tags: [Finance]
      operationId: financeV2ProjectsShow
      summary: Read an owned project
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      responses:
        "200": { description: "Project.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Project' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    put:
      tags: [Finance]
      operationId: financeV2ProjectsUpdate
      summary: Update an owned project with optimistic versioning
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectInput' } } } }
      responses:
        "200": { description: "Updated project.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Project' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectConflict' } } } }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeV2ProjectsArchive
      summary: Archive an owned project
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectActionInput' } } } }
      responses:
        "200": { description: "Archived project.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Project' } } } }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectConflict' } } } }
        "422": { $ref: "#/components/responses/ValidationError" }

  /finance-v2/projects/{project}/status:
    post:
      tags: [Finance]
      operationId: financeV2ProjectsStatus
      summary: Change project status
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectActionInput' } } } }
      responses:
        "200": { description: "Updated project.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Project' } } } }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectConflict' } } } }
        "422": { description: "Invalid transition.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectDomainError' } } } }

  /finance-v2/projects/{project}/move:
    post:
      tags: [Finance]
      operationId: financeV2ProjectsMove
      summary: Move project in the owned hierarchy
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectActionInput' } } } }
      responses:
        "200": { description: "Moved project.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Project' } } } }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectConflict' } } } }
        "422": { $ref: "#/components/responses/ValidationError" }

  /finance-v2/projects/{project}/restore:
    post:
      tags: [Finance]
      operationId: financeV2ProjectsRestore
      summary: Restore an archived project
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectActionInput' } } } }
      responses:
        "200": { description: "Restored project.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Project' } } } }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectConflict' } } } }
        "422": { $ref: "#/components/responses/ValidationError" }

  /finance-v2/projects/{project}/work-items:
    get:
      tags: [Finance]
      operationId: financeV2ProjectWorkItemsIndex
      summary: List project work items
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: page, in: query, schema: { type: integer, minimum: 1 } }, { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }]
      responses:
        "200": { description: "Work item page.", content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: '#/components/schemas/FinanceV2WorkItem' } }, meta: { type: object } } } } } }
        "404": { $ref: "#/components/responses/NotFound" }
    post:
      tags: [Finance]
      operationId: financeV2ProjectWorkItemsCreate
      summary: Create a work item
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2WorkItemInput' } } } }
      responses:
        "201": { description: "Work item created.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2WorkItem' } } } }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Project archived.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectConflict' } } } }
        "422": { $ref: "#/components/responses/ValidationError" }

  /finance-v2/projects/{project}/work-items/{workItem}:
    put:
      tags: [Finance]
      operationId: financeV2ProjectWorkItemsUpdate
      summary: Update a project work item
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: workItem, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2WorkItemInput' } } } }
      responses:
        "200": { description: "Work item updated.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2WorkItem' } } } }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectConflict' } } } }
        "422": { $ref: "#/components/responses/ValidationError" }
    delete:
      tags: [Finance]
      operationId: financeV2ProjectWorkItemsDelete
      summary: Delete a project work item
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: workItem, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version], properties: { version: { type: integer, minimum: 0 } } } } } }
      responses: { "204": { description: "Deleted."}, "404": { $ref: "#/components/responses/NotFound" }, "409": { description: "Version conflict."}, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/work-items/reorder:
    post:
      tags: [Finance]
      operationId: financeV2ProjectWorkItemsReorder
      summary: Reorder all project work items
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [ids], properties: { ids: { type: array, items: { type: string, format: uuid } } } } } } }
      responses: { "200": { description: "Reordered work items."}, "404": { $ref: "#/components/responses/NotFound" }, "409": { description: "Project archived."}, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/time-entries:
    get:
      tags: [Finance]
      operationId: financeV2ProjectTimeEntriesIndex
      summary: List project time entries
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: page, in: query, schema: { type: integer, minimum: 1 } }, { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }]
      responses: { "200": { description: "Time entry page."}, "404": { $ref: "#/components/responses/NotFound" }, "422": { $ref: "#/components/responses/ValidationError" } }
    post:
      tags: [Finance]
      operationId: financeV2ProjectTimeEntriesCreate
      summary: Log project time
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2TimeEntryInput' } } } }
      responses: { "201": { description: "Time entry created.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2TimeEntry' } } } }, "404": { $ref: "#/components/responses/NotFound" }, "409": { description: "Project archived."}, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/time-entries/{entry}:
    put:
      tags: [Finance]
      operationId: financeV2ProjectTimeEntriesUpdate
      summary: Update uninvoiced project time
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: entry, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2TimeEntryInput' } } } }
      responses: { "200": { description: "Time entry updated.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2TimeEntry' } } } }, "404": { $ref: "#/components/responses/NotFound" }, "409": { description: "Version, archive, or invoiced conflict."}, "422": { $ref: "#/components/responses/ValidationError" } }
    delete:
      tags: [Finance]
      operationId: financeV2ProjectTimeEntriesDelete
      summary: Delete uninvoiced project time
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: entry, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version], properties: { version: { type: integer, minimum: 0 } } } } } }
      responses: { "204": { description: "Deleted."}, "404": { $ref: "#/components/responses/NotFound" }, "409": { description: "Version, archive, or invoiced conflict."}, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/invoice-drafts:
    post:
      tags: [Finance]
      operationId: financeV2ProjectInvoiceDraftsCreate
      summary: Create an idempotent invoice draft from project time
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }]
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [time_entry_ids], properties: { time_entry_ids: { type: array, minItems: 1, items: { type: string, format: uuid } } } } } } }
      responses: { "201": { description: "Invoice draft target."}, "404": { $ref: "#/components/responses/NotFound" }, "409": { description: "Idempotency, archive, or invoiced conflict."}, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/totals:
    get:
      tags: [Finance]
      operationId: financeV2ProjectTotalsShow
      summary: Read server-calculated project totals
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      responses: { "200": { description: "Exact totals.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectTotals' } } } }, "404": { $ref: "#/components/responses/NotFound" } }

  /finance-v2/projects/{project}/ledger:
    get:
      tags: [Finance]
      operationId: financeV2ProjectLedgerIndex
      summary: List project ledger entries
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: direction, in: query, schema: { type: string, enum: [in, out] } }, { name: from, in: query, schema: { type: string, format: date } }, { name: to, in: query, schema: { type: string, format: date } }, { name: category_reference, in: query, schema: { type: string } }, { name: page, in: query, schema: { type: integer, minimum: 1 } }, { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }]
      responses: { "200": { description: "Ledger page."}, "404": { $ref: "#/components/responses/NotFound" }, "422": { $ref: "#/components/responses/ValidationError" } }
    post:
      tags: [Finance]
      operationId: financeV2ProjectLedgerCreate
      summary: Create a project ledger entry
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2LedgerEntryInput' } } } }
      responses: { "201": { description: "Ledger entry created.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2LedgerEntry' } } } }, "404": { $ref: "#/components/responses/NotFound" }, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/ledger/{entry}:
    put:
      tags: [Finance]
      operationId: financeV2ProjectLedgerUpdate
      summary: Correct a project ledger entry
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: entry, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2LedgerEntryInput' } } } }
      responses: { "200": { description: "Corrected ledger entry.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2LedgerEntry' } } } }, "404": { $ref: "#/components/responses/NotFound" }, "409": { description: "Version conflict."}, "422": { $ref: "#/components/responses/ValidationError" } }
    delete:
      tags: [Finance]
      operationId: financeV2ProjectLedgerDelete
      summary: Delete a project ledger entry
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: entry, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version], properties: { version: { type: integer, minimum: 0 } } } } } }
      responses: { "204": { description: "Deleted."}, "404": { $ref: "#/components/responses/NotFound" }, "409": { description: "Version conflict."}, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/documents:
    get:
      tags: [Finance]
      operationId: financeV2ProjectDocumentsIndex
      summary: List active or historical project document links
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: state, in: query, schema: { type: string, enum: [active, detached, all] } }, { name: page, in: query, schema: { type: integer, minimum: 1 } }, { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }]
      responses: { "200": { description: "Document link page."}, "404": { $ref: "#/components/responses/NotFound" }, "422": { $ref: "#/components/responses/ValidationError" } }
    post:
      tags: [Finance]
      operationId: financeV2ProjectDocumentsAttach
      summary: Attach an owner-validated document source
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectDocumentInput' } } } }
      responses: { "201": { description: "Link attached.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectDocument' } } } }, "404": { $ref: "#/components/responses/NotFound" }, "409": { description: "Idempotency or duplicate conflict."}, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/documents/{link}:
    delete:
      tags: [Finance]
      operationId: financeV2ProjectDocumentsDetach
      summary: Detach a project document while preserving history
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: link, in: path, required: true, schema: { type: integer, minimum: 1 } }, { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }]
      responses: { "200": { description: "Historical detached link.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectDocument' } } } }, "404": { $ref: "#/components/responses/NotFound" }, "409": { description: "Idempotency or attachment-state conflict."}, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/document-sources:
    get:
      tags: [Finance]
      operationId: financeV2ProjectDocumentSourcesIndex
      summary: Search owner-validated attachable document sources
      description: Authorized API capability URL; storage metadata paths are never returned.
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: cursor, in: query, schema: { type: string, maxLength: 4096 } }, { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }]
      responses: { "200": { description: "Source page with opaque next_cursor."}, "404": { $ref: "#/components/responses/NotFound" }, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/notes:
    get:
      tags: [Finance]
      operationId: financeV2ProjectNotesIndex
      summary: List append-only project notes
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: page, in: query, schema: { type: integer, minimum: 1 } }, { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }]
      responses: { "200": { description: "Note page."}, "404": { $ref: "#/components/responses/NotFound" }, "422": { $ref: "#/components/responses/ValidationError" } }
    post:
      tags: [Finance]
      operationId: financeV2ProjectNotesCreate
      summary: Append a project note or correction
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectNoteInput' } } } }
      responses: { "201": { description: "Note appended.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2HistoryItem' } } } }, "404": { $ref: "#/components/responses/NotFound" }, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/projects/{project}/activities:
    get:
      tags: [Finance]
      operationId: financeV2ProjectActivitiesIndex
      summary: List stable merged project and linked-document activity
      parameters: [{ name: project, in: path, required: true, schema: { type: string, format: uuid } }, { name: cursor, in: query, schema: { type: string, maxLength: 4096 } }, { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }]
      responses: { "200": { description: "Activity page with opaque next_cursor and scrubbed payloads."}, "404": { $ref: "#/components/responses/NotFound" }, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/document-series/{series}/notes:
    get:
      tags: [Finance]
      operationId: financeV2DocumentSeriesNotesIndex
      summary: List append-only notes for an owned document series
      parameters: [{ name: series, in: path, required: true, schema: { type: string, format: uuid } }, { name: page, in: query, schema: { type: integer, minimum: 1 } }, { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100 } }]
      responses: { "200": { description: "Document note page."}, "404": { $ref: "#/components/responses/NotFound" }, "422": { $ref: "#/components/responses/ValidationError" } }
    post:
      tags: [Finance]
      operationId: financeV2DocumentSeriesNotesCreate
      summary: Append a note or correction to an owned document series
      parameters: [{ name: series, in: path, required: true, schema: { type: string, format: uuid } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2ProjectNoteInput' } } } }
      responses: { "201": { description: "Document note appended.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2HistoryItem' } } } }, "404": { $ref: "#/components/responses/NotFound" }, "422": { $ref: "#/components/responses/ValidationError" } }

  /finance-v2/quotes:
    get:
      tags: [Finance]
      operationId: financeV2QuotesIndex
      summary: List owner-scoped quotes with stable pagination
      parameters:
        - { name: q, in: query, schema: { type: string, maxLength: 255 } }
        - { name: status, in: query, schema: { type: string, enum: [draft, sent, accepted, declined, converted] } }
        - { name: effective_status, in: query, schema: { type: string, enum: [draft, sent, accepted, declined, converted, expired] } }
        - { name: published_from, in: query, schema: { type: string, format: date } }
        - { name: published_to, in: query, schema: { type: string, format: date } }
        - { name: sort, in: query, schema: { type: string, enum: [published_at] } }
        - { name: direction, in: query, schema: { type: string, enum: [desc] } }
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
      responses:
        "200": { description: "Quote page.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuotePage' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Finance]
      operationId: financeV2QuotesCreate
      summary: Create an idempotent server-calculated quote draft
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteDraftInput' } } }
      responses:
        "201": { description: "Draft created.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { description: "Idempotency conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/preview:
    post:
      tags: [Finance]
      operationId: financeV2QuotesPreview
      summary: Calculate quote totals without writing state
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteDraftInput' } } }
      responses:
        "200": { description: "Server-authoritative totals.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuotePreview' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}:
    get:
      tags: [Finance]
      operationId: financeV2QuotesShow
      summary: Read one owner-scoped quote aggregate
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200": { description: "Quote aggregate.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}/revisions:
    get:
      tags: [Finance]
      operationId: financeV2QuoteRevisionsIndex
      summary: List immutable quote revision history newest first
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200": { description: "Revision history.", content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/FinanceV2QuoteRevision' } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}/draft:
    put:
      tags: [Finance]
      operationId: financeV2QuoteDraftUpdate
      summary: Update a quote draft using optimistic version CAS
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - { $ref: '#/components/schemas/FinanceV2QuoteDraftInput' }
                - { type: object, required: [version], properties: { version: { type: integer, minimum: 0 } } }
      responses:
        "200": { description: "Draft updated.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeV2QuoteDraftDiscard
      summary: Discard a later-version draft using optimistic version CAS
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version], properties: { version: { type: integer, minimum: 0 } } } } } }
      responses:
        "200": { description: "Draft discarded.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}/versions:
    post:
      tags: [Finance]
      operationId: financeV2QuoteVersionCreate
      summary: Start a later quote version
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version], properties: { version: { type: integer, minimum: 0 } } } } } }
      responses:
        "201": { description: "Draft version started.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}/publish:
    post:
      tags: [Finance]
      operationId: financeV2QuotePublish
      summary: Publish the current draft as an immutable revision
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version], properties: { version: { type: integer, minimum: 0 }, change_reason: { type: [string, "null"], maxLength: 1000 } } } } } }
      responses:
        "200": { description: "Published or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version, idempotency, or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}/send:
    post:
      tags: [Finance]
      operationId: financeV2QuoteSend
      summary: Publish when needed and queue immutable quote delivery
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version], properties: { version: { type: integer, minimum: 0 }, recipient: { type: [string, "null"], format: email }, change_reason: { type: [string, "null"], maxLength: 1000 } } } } } }
      responses:
        "200": { description: "Existing idempotent result replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "202": { description: "Immutable revision delivery queued.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version, idempotency, or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}/accept:
    post:
      tags: [Finance]
      operationId: financeV2QuoteAccept
      summary: Accept the exact current quote revision
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version, expected_revision_id], properties: { version: { type: integer, minimum: 0 }, expected_revision_id: { type: integer, minimum: 1 } } } } } }
      responses:
        "200": { description: "Accepted or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version, revision, idempotency, or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}/decline:
    post:
      tags: [Finance]
      operationId: financeV2QuoteDecline
      summary: Decline the exact current quote revision
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version, expected_revision_id], properties: { version: { type: integer, minimum: 0 }, expected_revision_id: { type: integer, minimum: 1 } } } } } }
      responses:
        "200": { description: "Declined or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version, revision, idempotency, or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}/duplicate:
    post:
      tags: [Finance]
      operationId: financeV2QuoteDuplicate
      summary: Duplicate an exact quote draft or immutable revision into a new draft
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version], properties: { version: { type: integer, minimum: 0 }, source_revision_id: { type: [integer, "null"], minimum: 1 } } } } } }
      responses:
        "201": { description: "Duplicate draft created.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Quote' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version, idempotency, or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}/conversions/invoice:
    post:
      tags: [Finance]
      operationId: financeV2QuoteConvertInvoice
      summary: Convert an accepted exact immutable quote revision to an invoice draft
      parameters:
        - { name: quote, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version, expected_revision_id], properties: { version: { type: integer, minimum: 0 }, expected_revision_id: { type: integer, minimum: 1 } } } } } }
      responses:
        "201": { description: "Invoice draft target created.", content: { application/json: { schema: { type: object, additionalProperties: false, required: [target_reference, target_id], properties: { target_reference: { type: string }, target_id: { type: [integer, "null"] } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version, revision, idempotency, or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2QuoteConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2QuoteUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance-v2/quotes/{quote}/revisions/{revision}/pdf:
    get:
      tags: [Finance]
      operationId: financeV2QuoteRevisionPdf
      summary: Stream an immutable published quote revision PDF
      description: >
        Streams server-rendered PDF bytes for one published revision belonging
        to the authenticated owner. Deleted and foreign quotes, revisions from
        another series, unsafe storage metadata, missing objects, and digest
        mismatches all return 404. Set `download=true` for attachment disposition;
        otherwise the PDF is shown inline. Throttle: 120 requests/minute.
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: quote
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: revision
          in: path
          required: true
          schema: { type: integer, format: int64, minimum: 1, maximum: 9223372036854775807 }
        - name: download
          in: query
          required: false
          schema: { type: boolean, default: false }
      responses:
        "200":
          description: Immutable quote revision PDF bytes.
          headers:
            ETag:
              description: Quoted SHA-256 digest of the exact response bytes.
              schema: { type: string }
            Cache-Control:
              schema: { type: string, example: "private, max-age=31536000, immutable" }
            Content-Disposition:
              schema: { type: string }
          content:
            application/pdf:
              schema: { type: string, format: binary }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/invoices/{invoice}/revisions/{revision}/pdf:
    get:
      tags: [Finance]
      operationId: financeV2InvoiceRevisionPdf
      summary: Stream an immutable published invoice revision PDF
      description: >
        Streams server-rendered PDF bytes for one published revision belonging
        to the authenticated owner. Foreign invoices, revisions from another
        series, unsafe storage metadata, missing objects, non-PDF bytes, and
        digest mismatches all return 404. Set `download=true` for attachment
        disposition; otherwise the PDF is shown inline. Throttle: 120
        requests/minute.
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: invoice
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: revision
          in: path
          required: true
          schema: { type: integer, format: int64, minimum: 1, maximum: 9223372036854775807 }
        - name: download
          in: query
          required: false
          schema: { type: boolean, default: false }
      responses:
        "200":
          description: Immutable invoice revision PDF bytes.
          headers:
            ETag:
              description: Quoted SHA-256 digest of the exact response bytes.
              schema: { type: string }
            Cache-Control:
              schema: { type: string, example: "private, max-age=31536000, immutable" }
            Content-Disposition:
              schema: { type: string }
          content:
            application/pdf:
              schema: { type: string, format: binary }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/invoices:
    get:
      tags: [Finance]
      operationId: financeV2InvoicesIndex
      summary: List owner-scoped invoices with stable pagination
      parameters:
        - { name: q, in: query, schema: { type: string, maxLength: 255 } }
        - { name: status, in: query, schema: { type: string, enum: [draft, finalized, sent, partially_paid, paid, cancelled] } }
        - { name: kind, in: query, schema: { type: string, enum: [invoice, credit_note] } }
        - { name: overdue, in: query, schema: { type: boolean } }
        - { name: from, in: query, schema: { type: string, format: date } }
        - { name: to, in: query, schema: { type: string, format: date } }
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
      responses:
        "200": { description: "Invoice page.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoicePage' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Finance]
      operationId: financeV2InvoicesCreate
      summary: Create an exact server-calculated invoice draft
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceDraftInput' } } }
      responses:
        "201": { description: "Draft created.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Invoice' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/FinanceV2InvoiceUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/invoices/{invoice}:
    get:
      tags: [Finance]
      operationId: financeV2InvoicesShow
      summary: Read one owner-scoped invoice aggregate
      parameters:
        - { name: invoice, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200": { description: "Invoice aggregate.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Invoice' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    patch:
      tags: [Finance]
      operationId: financeV2InvoicesUpdate
      summary: Update a draft invoice using optimistic version CAS
      parameters:
        - { name: invoice, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - { $ref: '#/components/schemas/FinanceV2InvoiceDraftInput' }
                - { type: object, required: [version], properties: { version: { type: integer, minimum: 0 } } }
      responses:
        "200": { description: "Draft updated.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Invoice' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2InvoiceUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeV2InvoicesDestroy
      summary: Delete a draft-only invoice using optimistic version CAS
      parameters:
        - { name: invoice, in: path, required: true, schema: { type: string, format: uuid } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version], properties: { version: { type: integer, minimum: 0 } } } } } }
      responses:
        "204": { description: "Draft deleted."}
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version or not-a-draft conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceConflict' } } } }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/invoices/{invoice}/finalize:
    post:
      tags: [Finance]
      operationId: financeV2InvoicesFinalize
      summary: Atomically finalize a draft into an immutable numbered revision and PDF
      parameters:
        - { name: invoice, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      responses:
        "200": { description: "Finalized or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceFinalizeResult' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Idempotency or workflow conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2InvoiceUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/invoices/{invoice}/deliveries:
    post:
      tags: [Finance]
      operationId: financeV2InvoiceDeliveriesCreate
      summary: Queue idempotent immutable-revision invoice email delivery
      parameters:
        - { name: invoice, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, additionalProperties: false, properties: { recipient: { type: [string, "null"], format: email } } } } } }
      responses:
        "202": { description: "Delivery queued or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceDelivery' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Idempotency conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2InvoiceUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/invoices/{invoice}/reminders:
    post:
      tags: [Finance]
      operationId: financeV2InvoiceRemindersCreate
      summary: Queue an idempotent overdue-invoice reminder at a numbered level
      parameters:
        - { name: invoice, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, additionalProperties: false, required: [level], properties: { level: { type: integer, minimum: 1, maximum: 3 }, recipient: { type: [string, "null"], format: email } } } } } }
      responses:
        "202": { description: "Reminder queued or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceDelivery' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Idempotency conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2InvoiceUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/invoices/{invoice}/cancel:
    post:
      tags: [Finance]
      operationId: financeV2InvoicesCancel
      summary: Cancel a finalized invoice with a separately numbered immutable credit document
      parameters:
        - { name: invoice, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      responses:
        "201": { description: "Credit document created or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceFinalizeResult' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Idempotency conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2InvoiceConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2InvoiceUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/invoices/{invoice}/revisions:
    get:
      tags: [Finance]
      operationId: financeV2InvoiceRevisionsIndex
      summary: List invoice revision history newest first
      parameters:
        - { name: invoice, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200": { description: "Revision history.", content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/FinanceV2InvoiceRevision' } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/invoices/{invoice}/pdf:
    get:
      tags: [Finance]
      operationId: financeLegacyInvoicePdf
      summary: Stream a pre-cutover (legacy) invoice's own stored PDF
      description: >
        Read-only survivor of the legacy invoice write surface removed in the
        Task 17 cutover: GoBD requires an already-issued invoice's document
        stay reachable for the statutory retention period, so this streams the
        exact bytes stored before the cutover. `invoice` is the legacy
        `invoices.id` (a plain integer, never a finance-v2 uuid). With
        `version_seq` it streams that GoBD correction-trail version's own PDF
        instead of the current one. No corresponding write route exists.
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: invoice, in: path, required: true, schema: { type: integer } }
        - { name: version_seq, in: query, required: false, schema: { type: integer, minimum: 1 }, description: "Stream this versions[].seq entry's own PDF instead of the current invoice PDF." }
        - { name: download, in: query, required: false, schema: { type: boolean }, description: "true → Content-Disposition: attachment; default inline." }
      responses:
        "200": { description: "PDF bytes.", content: { application/pdf: { schema: { type: string, format: binary } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/payments:
    get:
      tags: [Finance]
      operationId: financeV2PaymentsIndex
      summary: List owner-scoped payments with stable pagination
      parameters:
        - { name: q, in: query, schema: { type: string, maxLength: 255 } }
        - { name: unallocated, in: query, schema: { type: boolean } }
        - { name: from, in: query, schema: { type: string, format: date } }
        - { name: to, in: query, schema: { type: string, format: date } }
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
      responses:
        "200": { description: "Payment page.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2PaymentPage' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Finance]
      operationId: financeV2PaymentsCreate
      summary: Record an idempotent exact signed payment
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecordPaymentInput' } } }
      responses:
        "201": { description: "Payment recorded or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Payment' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { description: "Idempotency conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2PaymentConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2PaymentUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/payments/{payment}:
    get:
      tags: [Finance]
      operationId: financeV2PaymentsShow
      summary: Read one owner-scoped payment
      parameters:
        - { name: payment, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200": { description: "Payment.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2Payment' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/payments/{payment}/suggestions:
    get:
      tags: [Finance]
      operationId: financeV2PaymentSuggestionsShow
      summary: Score non-mutating candidate invoices for a payment; never auto-confirms
      parameters:
        - { name: payment, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200": { description: "Ranked suggestions.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2PaymentSuggestions' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/payments/{payment}/allocations:
    post:
      tags: [Finance]
      operationId: financeV2PaymentAllocationsCreate
      summary: Append idempotent exact signed payment allocations under owner lock
      parameters:
        - { name: payment, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [lines]
              properties:
                lines: { type: array, minItems: 1, maxItems: 100, items: { $ref: '#/components/schemas/FinanceV2AllocationLineInput' } }
                expected_version: { type: [integer, "null"], minimum: 0 }
      responses:
        "201": { description: "Allocated or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2AllocationResult' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Idempotency or version conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2PaymentConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2PaymentUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/payment-allocations/{allocation}/reverse:
    post:
      tags: [Finance]
      operationId: financeV2PaymentAllocationsReverse
      summary: Append the exact append-only reversal of one allocation entry
      parameters:
        - { name: allocation, in: path, required: true, schema: { type: integer, format: int64, minimum: 1 } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, additionalProperties: false, properties: { expected_payment_version: { type: [integer, "null"], minimum: 0 } } } } } }
      responses:
        "200": { description: "Reversed or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2AllocationResult' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Idempotency, version, or already-reversed conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2PaymentConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2PaymentUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/recurring-invoice-templates:
    get:
      tags: [Finance]
      operationId: financeV2RecurringInvoiceTemplatesIndex
      summary: List owner-scoped recurring invoice templates with stable pagination
      parameters:
        - { name: status, in: query, schema: { type: string, enum: [active, paused, completed] } }
        - { name: mode, in: query, schema: { type: string, enum: [draft, auto_send] } }
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
      responses:
        "200": { description: "Template page.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceTemplatePage' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Finance]
      operationId: financeV2RecurringInvoiceTemplatesCreate
      summary: Create an idempotent versioned recurring invoice template
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceTemplateInput' } } }
      responses:
        "201": { description: "Template created or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceTemplate' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409": { description: "Idempotency conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2RecurringUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/recurring-invoice-templates/{template}:
    get:
      tags: [Finance]
      operationId: financeV2RecurringInvoiceTemplatesShow
      summary: Read one owner-scoped recurring invoice template
      parameters:
        - { name: template, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200": { description: "Template.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceTemplate' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/recurring-invoice-templates/{template}/versions:
    post:
      tags: [Finance]
      operationId: financeV2RecurringInvoiceTemplateVersionsCreate
      summary: Add a later effective-dated content version using optimistic version CAS
      parameters:
        - { name: template, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceTemplateVersionInput' } } }
      responses:
        "201": { description: "Version added or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceTemplate' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version, idempotency, or effective-date conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2RecurringUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/recurring-invoice-templates/{template}/pause:
    post:
      tags: [Finance]
      operationId: financeV2RecurringInvoiceTemplatesPause
      summary: Pause a template using optimistic version CAS, preserving its next due occurrence
      parameters:
        - { name: template, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [expected_version], properties: { expected_version: { type: integer, minimum: 0 } } } } } }
      responses:
        "200": { description: "Paused or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceTemplate' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version or idempotency conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2RecurringUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/recurring-invoice-templates/{template}/resume:
    post:
      tags: [Finance]
      operationId: financeV2RecurringInvoiceTemplatesResume
      summary: Resume a paused template using optimistic version CAS without skipping overdue occurrences
      parameters:
        - { name: template, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [expected_version], properties: { expected_version: { type: integer, minimum: 0 } } } } } }
      responses:
        "200": { description: "Resumed or idempotently replayed.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceTemplate' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Version or idempotency conflict.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringConflict' } } } }
        "422": { $ref: "#/components/responses/FinanceV2RecurringUnprocessable" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/recurring-invoice-templates/{template}/runs:
    get:
      tags: [Finance]
      operationId: financeV2RecurringInvoiceTemplateRunsIndex
      summary: List one template's scheduler runs with stable pagination
      parameters:
        - { name: template, in: path, required: true, schema: { type: string, format: uuid } }
        - { name: status, in: query, schema: { type: string, enum: [pending, creating_draft, draft_created, finalizing, finalized, sending, sent, failed] } }
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
        - { name: per_page, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
      responses:
        "200": { description: "Run page.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceRunPage' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/recurring-invoice-runs/{run}/retry:
    post:
      tags: [Finance]
      operationId: financeV2RecurringInvoiceRunsRetry
      summary: Retry a failed run from its persisted safe step, never repeating a completed step
      parameters:
        - { name: run, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "202": { description: "Retry accepted; run resumes from its safe step.", content: { application/json: { schema: { $ref: '#/components/schemas/FinanceV2RecurringInvoiceRun' } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Invalid run-state transition.", content: { application/json: { schema: { type: object, additionalProperties: false, required: [error], properties: { error: { type: string } } } } } }
        "422": { description: "Invalid run-state transition.", content: { application/json: { schema: { type: object, additionalProperties: false, required: [error], properties: { error: { type: string } } } } } }
        "429": { $ref: "#/components/responses/RateLimited" }

  /finance/data:
    get:
      tags: [Finance]
      operationId: financeData
      summary: All finance data (invoices, partners, payment methods, projects, categories, transactions)
      security: [ { bearerAuth: [] } ]
      responses:
        "200":
          description: Finance snapshot.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices: { type: array, items: { $ref: "#/components/schemas/Invoice" } }
                  partners: { type: array, items: { $ref: "#/components/schemas/FinancePartner" } }
                  paymentMethods: { type: array, items: { $ref: "#/components/schemas/PaymentMethod" } }
                  projects: { type: array, items: { $ref: "#/components/schemas/FinanceProject" } }
                  financeCategories: { type: array, items: { $ref: "#/components/schemas/FinanceCategory" } }
                  transactions: { type: array, items: { $ref: "#/components/schemas/BankTransaction" } }
                  standaloneReceipts: { type: array, items: { $ref: "#/components/schemas/FinanceReceipt" } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /finance/reports:
    get:
      tags: [Finance]
      operationId: financeReports
      summary: Server-side VAT return + revenue statistics for a year (read-only)
      description: >
        Authoritative server-computed finance analytics (the client consumes
        these instead of computing in-browser): VAT advance return, revenue
        KPIs, revenue by customer, and monthly revenue for the requested year,
        plus the current-year VAT for the dashboard and the list of years with
        realized invoices. Read-only; never mutates a finance row. Throttle 120/min.
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: year, in: query, required: false, schema: { type: integer }, description: "Target year (defaults to the current year)." }
      responses:
        "200":
          description: Analytics for the year.
          content:
            application/json:
              schema:
                type: object
                required: [year, years, currentVat, vat, kpis, customers, months, aging]
                properties:
                  year: { type: integer }
                  years: { type: array, items: { type: integer } }
                  currentVat: { $ref: "#/components/schemas/VatReturn" }
                  vat: { $ref: "#/components/schemas/VatReturn" }
                  kpis: { $ref: "#/components/schemas/FinanceKpis" }
                  customers: { type: array, items: { $ref: "#/components/schemas/RevenueByCustomer" } }
                  months:
                    type: array
                    items:
                      type: object
                      properties: { month: { type: integer }, net: { type: number } }
                  aging: { $ref: "#/components/schemas/InvoiceAging" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/reports/account-vat:
    get:
      tags: [Finance]
      operationId: financeAccountVat
      summary: VAT summary of one payment account's transactions for a year (read-only)
      description: >
        Summarises output VAT, input VAT (Vorsteuer) and the resulting payable for a
        single payment account's transactions in a year, broken down by rate.
        Read-only; never mutates a finance row. Throttle 120/min.
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: account_id, in: query, required: true, schema: { type: integer }, description: "Payment-method (account) id." }
        - { name: year, in: query, required: false, schema: { type: integer }, description: "Target year (defaults to the current year)." }
      responses:
        "200":
          description: Account VAT summary (output/input VAT, payable, by rate).
          content:
            application/json:
              schema: { $ref: "#/components/schemas/AccountVatSummary" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/reports/vat-advance:
    get:
      tags: [Finance]
      operationId: financeVatAdvance
      summary: Unified USt-Voranmeldung — output − input VAT = payable (read-only)
      description: >
        Server-authoritative combined VAT advance return: output VAT from realized
        invoices minus input VAT (Vorsteuer) from all of the user's bank
        transactions, for a year and optional quarter, yielding a single payable
        (Zahllast). §19 Kleinunternehmer → output VAT is zero. Read-only; never
        mutates a finance row. Throttle 120/min.
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: year, in: query, required: false, schema: { type: integer }, description: "Target year (defaults to the current year)." }
        - { name: quarter, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 4 }, description: "Optional quarter 1–4; omit for the full year." }
      responses:
        "200":
          description: The unified VAT advance return.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/VatAdvanceReturn" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/reports/euer:
    get:
      tags: [Finance]
      operationId: financeEuer
      summary: Simplified EÜR — income − expenses = profit (read-only)
      description: >
        Server-computed simplified Einnahmenüberschussrechnung for a year: income
        (realized invoices) minus expenses (expense bank transactions + project
        manual expenses) = profit, grouped by category. Read-only; never mutates a
        finance row. Throttle 120/min.
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: year, in: query, required: false, schema: { type: integer }, description: "Target year (defaults to the current year)." }
      responses:
        "200":
          description: The EÜR report.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/EuerReport" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/duplicates:
    get:
      tags: [Finance]
      operationId: financeDuplicates
      summary: Suspected duplicate invoices + transactions (read-only)
      description: >
        Read-only duplicate detection. Reports suspect groups only (same
        number, or same date+amount+customer for invoices; same EREF, or same
        date+amount+counterparty+purpose for transactions) — never deletes or
        merges anything. Throttle 60/min.
      security: [ { bearerAuth: [] } ]
      responses:
        "200":
          description: Suspect groups.
          content:
            application/json:
              schema:
                type: object
                required: [invoices, transactions]
                properties:
                  invoices: { type: array, items: { $ref: "#/components/schemas/DuplicateGroup" } }
                  transactions: { type: array, items: { $ref: "#/components/schemas/DuplicateGroup" } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/recurring:
    get:
      tags: [Finance]
      operationId: financeRecurring
      summary: Recurring charges (subscriptions, standing orders)
      description: >
        Read-only detection over the owner's expense bookings: groups them by
        normalised counterparty and reads the intervals. Reports the annualised
        cost, a price change against the previous charge, and whether the charge
        has stopped coming. Never mutates a row. Throttle 60/min.
      security: [ { bearerAuth: [] } ]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  recurring: { type: array, items: { $ref: "#/components/schemas/RecurringCharge" } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/number-gaps:
    get:
      tags: [Finance]
      operationId: financeNumberGaps
      summary: GoBD invoice-numbering gap report (read-only)
      description: >
        Read-only report of missing invoice numbers, grouped by numbering
        regime (YYYY-NNNN resets per year; every other format is one
        continuous ordinal sequence across all years). Reports only — never
        deletes, merges, or renumbers anything; the owner decides whether a
        gap is a still-unimported historical invoice or a real numbering
        problem. Throttle 60/min.
      security: [ { bearerAuth: [] } ]
      responses:
        "200":
          description: Groups with missing numbers (empty array when the numbering is gapless).
          content:
            application/json:
              schema:
                type: object
                required: [groups]
                properties:
                  groups: { type: array, items: { $ref: "#/components/schemas/NumberGapGroup" } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/receipt-matches:
    get:
      tags: [Finance]
      operationId: financeReceiptMatches
      summary: Suggested receipt<->transaction links (read-only)
      description: >
        Read-only suggestions for linking unlinked standalone receipts to
        unlinked bank transactions, in both directions. groups: one charge
        settled by SEVERAL receipts (e.g. Amazon splitting an order into
        multiple shipment invoices that are charged together) — deterministic
        and cent-exact: receipts sharing a merchant-printed payment/order
        reference are summed first, then a single exact-amount receipt, then
        a bounded subset-sum (<=4 receipts) within a date window of the
        transaction. splitPayments: the inverse — one receipt whose total was
        actually debited as SEVERAL separate charges (e.g. one INWX invoice
        billed as one document but settled by two transactions a week apart)
        — a bounded subset-sum (<=4 transactions) within a date window of the
        receipt. Accidental re-uploads of the same document are de-duplicated
        before matching and reported separately. Never mutates a row — the
        client applies an accepted `groups` entry by PUTing
        bank_transaction_id on each listed receipt, and an accepted
        `splitPayments` entry by PUTing linked_transaction_ids on the receipt
        (both via PUT /finance/receipts/{receipt}). Throttle 60/min.
      security: [ { bearerAuth: [] } ]
      responses:
        "200":
          description: Suggested groups (both directions) + de-duplicated receipts (all empty arrays when there is nothing to suggest).
          content:
            application/json:
              schema:
                type: object
                required: [groups, duplicates, splitPayments]
                properties:
                  groups: { type: array, items: { $ref: "#/components/schemas/ReceiptMatchGroup" } }
                  duplicates: { type: array, items: { $ref: "#/components/schemas/ReceiptDuplicate" } }
                  splitPayments: { type: array, items: { $ref: "#/components/schemas/SplitPaymentGroup" } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/category-suggestions:
    get:
      tags: [Finance]
      operationId: financeCategorySuggestions
      summary: Merchant-based category suggestions for uncategorised transactions (read-only)
      description: >
        Read-only merchant->category suggestions derived from the taught
        category on each business partner (the partner list doubles as the rule
        store). Suggests only — the client decides whether to apply; the server
        never writes a category onto a transaction. Throttle 60/min.
      security: [ { bearerAuth: [] } ]
      responses:
        "200":
          description: Suggestions for transactions with no category yet.
          content:
            application/json:
              schema:
                type: object
                required: [suggestions]
                properties:
                  suggestions:
                    type: array
                    items:
                      type: object
                      required: [tx_id, merchant, suggested_category]
                      properties:
                        tx_id: { type: integer }
                        merchant: { type: string }
                        suggested_category: { type: string }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/trash:
    get:
      tags: [Finance]
      operationId: financeTrash
      summary: Trashed finance rows
      security: [ { bearerAuth: [] } ]
      responses:
        "200": { description: "Trashed sets — same keys as /finance/data EXCEPT financeCategories (hard-deleted, not trashable) and standaloneReceipts (not surfaced in trash), each an array of soft-deleted rows.", content: { application/json: { schema: { type: object, additionalProperties: true } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /finance/partners:
    post:
      tags: [Finance]
      operationId: financePartnerStore
      summary: Create a business partner
      description: "`name` is required. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/PartnerInput" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, required: [partner], properties: { partner: { $ref: "#/components/schemas/FinancePartner" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/partners/{partner}:
    put:
      tags: [Finance]
      operationId: financePartnerUpdate
      summary: Update a partner (optimistic concurrency)
      description: "Send `version` for optimistic concurrency (409 on mismatch). Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: partner, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/PartnerInput" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, required: [partner], properties: { partner: { $ref: "#/components/schemas/FinancePartner" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/VersionConflict" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financePartnerDestroy
      summary: Soft-delete a partner
      description: "Move the partner to trash. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: partner, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/partners/{id}/restore:
    post:
      tags: [Finance]
      operationId: financePartnerRestore
      summary: Restore a partner
      description: "Restore a soft-deleted partner. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Restored.", content: { application/json: { schema: { type: object, required: [partner], properties: { partner: { $ref: "#/components/schemas/FinancePartner" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/partners/{id}/force:
    delete:
      tags: [Finance]
      operationId: financePartnerForce
      summary: Permanently delete a partner
      description: "Permanently delete a trashed partner. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/partners/{partner}/archive:
    post:
      tags: [Finance]
      operationId: financePartnerArchive
      summary: Hide a partner from the pickers without deleting it
      description: "An old customer's documents keep pointing at their partner, so the useful state is \"do not offer this any more\", not deletion. The row stays listed by `/finance/data`; the client filters on `archived_at`. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: partner, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [archived], properties: { archived: { type: boolean } } } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, required: [partner], properties: { partner: { $ref: "#/components/schemas/FinancePartner" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/partners/{partner}/notes:
    get:
      tags: [Finance]
      operationId: financePartnerNotes
      summary: A partner's contact log
      description: "Newest first by `occurred_at`, capped at 500. `occurred_at` is separate from `created_at` because a call is logged after it ends — sorting by the typing time would put the history in the order it was remembered. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: partner, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Log.", content: { application/json: { schema: { type: object, required: [notes], properties: { notes: { type: array, items: { $ref: "#/components/schemas/FinancePartnerNote" } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Finance]
      operationId: financePartnerNoteStore
      summary: Log a contact
      description: "`occurred_at` defaults to now but is meant to carry when it actually happened. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: partner, in: path, required: true, schema: { type: integer } } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                kind: { type: string, enum: [call, meeting, mail, note], default: note }
                body: { type: string, maxLength: 20000 }
                occurred_at: { type: [string, "null"], format: date-time }
      responses:
        "201": { description: "Logged.", content: { application/json: { schema: { type: object, required: [note], properties: { note: { $ref: "#/components/schemas/FinancePartnerNote" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/partners/{partner}/notes/{note}:
    delete:
      tags: [Finance]
      operationId: financePartnerNoteDestroy
      summary: Remove a log entry
      description: "Scoped through the partner as well as the owner: a note id alone must not reach into another partner's log. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: partner, in: path, required: true, schema: { type: integer } }
        - { name: note, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { type: object, required: [ok], properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/payment-methods:
    post:
      tags: [Finance]
      operationId: financePaymentStore
      summary: Create a payment method
      description: "`type` + `name` are required. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/PaymentMethodInput" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, required: [payment_method], properties: { payment_method: { $ref: "#/components/schemas/PaymentMethod" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/payment-methods/{paymentMethod}:
    put:
      tags: [Finance]
      operationId: financePaymentUpdate
      summary: Update a payment method (optimistic concurrency)
      description: "Send `version` for optimistic concurrency (409 on mismatch). Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: paymentMethod, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/PaymentMethodInput" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, required: [payment_method], properties: { payment_method: { $ref: "#/components/schemas/PaymentMethod" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/VersionConflict" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financePaymentDestroy
      summary: Soft-delete a payment method
      description: "Move the payment method to trash. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: paymentMethod, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/payment-methods/{id}/restore:
    post:
      tags: [Finance]
      operationId: financePaymentRestore
      summary: Restore a payment method
      description: "Restore a soft-deleted payment method. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Restored.", content: { application/json: { schema: { type: object, required: [payment_method], properties: { payment_method: { $ref: "#/components/schemas/PaymentMethod" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/payment-methods/{id}/force:
    delete:
      tags: [Finance]
      operationId: financePaymentForce
      summary: Permanently delete a payment method
      description: "Permanently delete a trashed payment method. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/projects:
    post:
      tags: [Finance]
      operationId: financeProjectStore
      summary: Create a cost project
      description: "`name` is required. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/ProjectInput" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, required: [project], properties: { project: { $ref: "#/components/schemas/FinanceProject" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/projects/{project}:
    put:
      tags: [Finance]
      operationId: financeProjectUpdate
      summary: Update a project (optimistic concurrency)
      description: "Send `version` for optimistic concurrency (409 on mismatch). Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: project, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/ProjectInput" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, required: [project], properties: { project: { $ref: "#/components/schemas/FinanceProject" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/VersionConflict" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeProjectDestroy
      summary: Soft-delete a project
      description: "Move the project to trash; its children keep their parent_id (surface as roots). Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: project, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/projects/{id}/restore:
    post:
      tags: [Finance]
      operationId: financeProjectRestore
      summary: Restore a project
      description: "Restore a soft-deleted project. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Restored.", content: { application/json: { schema: { type: object, required: [project], properties: { project: { $ref: "#/components/schemas/FinanceProject" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/projects/{id}/force:
    delete:
      tags: [Finance]
      operationId: financeProjectForce
      summary: Permanently delete a project
      description: "Permanently delete a trashed project. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/projects/{project}/move:
    post:
      tags: [Finance]
      operationId: financeProjectMove
      summary: Reparent a project (cycle-guarded)
      description: "Set/clear the project's parent_id. parent_id must be an existing owned, non-deleted project; a move that would create a cycle is rejected 422. Throttle 1200/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: project, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { parent_id: { type: [integer, "null"], description: "New parent (null = make it a root)." } } } } } }
      responses:
        "200": { description: "Moved.", content: { application/json: { schema: { type: object, required: [project], properties: { project: { $ref: "#/components/schemas/FinanceProject" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422":
          description: "Validation failed (unknown/unowned parent_id) OR the move would create a cycle (body { error: cycle })."
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ValidationError"
                  - allOf:
                      - $ref: "#/components/schemas/FinanceError"
                      - properties: { error: { enum: [cycle] } }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/products:
    post:
      tags: [Finance]
      operationId: financeProductStore
      summary: Create a catalogue article (service or hardware)
      description: "One catalogue holds both kinds: a quote line does not care whether it sells an hour or a switch. `stock_qty`/`stock_min` are NOT settable here — stock only moves through `/finance/products/{product}/stock`, which writes a ledger movement, so the figure always has a history that explains it. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/FinanceProductInput" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, required: [product], properties: { product: { $ref: "#/components/schemas/FinanceProduct" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/products/{product}:
    put:
      tags: [Finance]
      operationId: financeProductUpdate
      summary: Update an article
      description: "Partial: a field the request omits keeps its stored value. Optimistic — send `version` to be refused with 409 instead of overwriting a concurrent change. A `stock_qty`/`stock_min` in the body is ignored by design. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: product, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/FinanceProductInput" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, required: [product], properties: { product: { $ref: "#/components/schemas/FinanceProduct" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/VersionConflict" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeProductDestroy
      summary: Move an article to the bin
      description: "Soft delete. Its article number is free again while it sits in the bin. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: product, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { type: object, required: [ok], properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/products/{id}/restore:
    post:
      tags: [Finance]
      operationId: financeProductRestore
      summary: Restore an article from the bin
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Restored.", content: { application/json: { schema: { type: object, required: [product], properties: { product: { $ref: "#/components/schemas/FinanceProduct" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/products/{id}/force:
    delete:
      tags: [Finance]
      operationId: financeProductForceDelete
      summary: Delete an article for good
      description: "Removes the article and its stock movements. This is the one case where stock history disappears, and it takes the article it described with it. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { type: object, required: [ok], properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/products/{product}/stock:
    post:
      tags: [Finance]
      operationId: financeProductStock
      summary: Book a stock movement
      description: "The only way stock changes. `qty` is signed by the caller — positive is goods in, negative is goods out — because a correction can go either way and deriving the direction from the reason would be wrong exactly when it matters. The article's figure is carried in the same transaction, so ledger and figure cannot drift. An article with `track_stock=false` still records the movement (switching tracking on later then has a history) but keeps its figure at zero. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: product, in: path, required: true, schema: { type: integer } } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [qty]
              properties:
                qty: { type: number, description: "Signed. In positive, out negative. Zero is refused: it states nothing." }
                reason: { type: string, enum: [purchase, sale, correction, return, initial], default: correction }
                note: { type: [string, "null"], maxLength: 1000 }
                occurred_at: { type: [string, "null"], format: date-time, description: "Defaults to now." }
      responses:
        "201": { description: "Booked.", content: { application/json: { schema: { type: object, required: [movement, product], properties: { movement: { $ref: "#/components/schemas/FinanceStockMovement" }, product: { $ref: "#/components/schemas/FinanceProduct" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/products/{product}/movements:
    get:
      tags: [Finance]
      operationId: financeProductMovements
      summary: Stock movement history of one article
      description: "Newest first, capped at 500. Append-only: there is no update or delete for a movement — a mistake is corrected by booking the opposite one, which leaves both visible. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: product, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "History.", content: { application/json: { schema: { type: object, required: [movements], properties: { movements: { type: array, items: { $ref: "#/components/schemas/FinanceStockMovement" } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes:
    post:
      tags: [Finance]
      operationId: financeQuoteStore
      summary: Create a quote (Angebot)
      description: "Starts as a draft with no number. `lines` share the invoice line shape plus `productId` + `kind`, which is what makes accepting a quote a copy rather than a translation and keeps one totals implementation. `valid_until` defaults from the company profile. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/FinanceQuoteInput" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, required: [quote], properties: { quote: { $ref: "#/components/schemas/FinanceQuote" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes/{quote}:
    put:
      tags: [Finance]
      operationId: financeQuoteUpdate
      summary: Update a draft quote
      description: "Only a draft is editable. A sent quote answers 422 `quote_locked`: the customer holds a document with that number on it, and changing what it says under the same number would make the two disagree — use duplicate instead. Optimistic via `version`. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: quote, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/FinanceQuoteInput" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, required: [quote], properties: { quote: { $ref: "#/components/schemas/FinanceQuote" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/VersionConflict" }
        "422": { description: "Locked (`{error: quote_locked}`) or invalid.", content: { application/json: { schema: { type: object, properties: { error: { type: string, enum: [quote_locked] } } } } } }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeQuoteDestroy
      summary: Move a quote to the bin
      description: "Soft delete. Its number stays out of circulation: a customer holding AN-2026-0007 must never receive a different one. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: quote, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { type: object, required: [ok], properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes/{quote}/send:
    post:
      tags: [Finance]
      operationId: financeQuoteSend
      summary: Give the quote its number and mark it as out
      description: "Assigns the next number from the `quote_number_format` template (same machinery as an invoice number, so a configured format behaves identically) and sets the status to `sent`. Idempotent: a second call does not mint a second number. Not a GoBD-gapless sequence — but binned rows still count, so a number that has been seen is never reused. Answers 409 `number_taken` if the number raced; simply send again. Throttle 120/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: quote, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Sent.", content: { application/json: { schema: { type: object, required: [quote], properties: { quote: { $ref: "#/components/schemas/FinanceQuote" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { description: "Number raced; retriable.", content: { application/json: { schema: { type: object, properties: { error: { type: string, enum: [number_taken] } } } } } }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes/{quote}/decide:
    post:
      tags: [Finance]
      operationId: financeQuoteDecide
      summary: Record the customer's answer
      description: "Sets `accepted` or `declined` with its timestamp. Requires a sent quote (422 `quote_not_sent`): nothing was sent, so there is nothing to answer. Throttle 120/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: quote, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [decision], properties: { decision: { type: string, enum: [accepted, declined] } } } } } }
      responses:
        "200": { description: "Recorded.", content: { application/json: { schema: { type: object, required: [quote], properties: { quote: { $ref: "#/components/schemas/FinanceQuote" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "Not sent, or invalid decision.", content: { application/json: { schema: { type: object, properties: { error: { type: string, enum: [quote_not_sent] } } } } } }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes/{quote}/convert:
    post:
      tags: [Finance]
      operationId: financeQuoteConvert
      summary: Turn a quote into a draft invoice
      description: "Copies customer, lines (including `productId`), discount and currency into a NEW draft invoice, and marks the quote accepted. The invoice takes its own number when finalised — a quote number is not an invoice number. Idempotent: a second call returns the invoice it already made (`already: true`, 200) instead of billing the work twice. Hardware does NOT move stock here; goods leave when the invoice is finalised, not when someone accepts a price. Throttle 120/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: quote, in: path, required: true, schema: { type: integer } } ]
      responses:
        "201": { description: "Invoice created.", content: { application/json: { schema: { type: object, required: [invoice, quote], properties: { invoice: { $ref: "#/components/schemas/Invoice" }, quote: { $ref: "#/components/schemas/FinanceQuote" } } } } } }
        "200": { description: "Already converted; the existing invoice is returned.", content: { application/json: { schema: { type: object, required: [invoice, quote], properties: { invoice: { $ref: "#/components/schemas/Invoice" }, quote: { $ref: "#/components/schemas/FinanceQuote" }, already: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "Not sent yet.", content: { application/json: { schema: { type: object, properties: { error: { type: string, enum: [quote_not_sent] } } } } } }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes/{quote}/duplicate:
    post:
      tags: [Finance]
      operationId: financeQuoteDuplicate
      summary: Copy a quote into a fresh draft
      description: "The way to change a sent quote: the original stays as it was sent, the copy is editable and takes its own number when it goes out. Throttle 120/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: quote, in: path, required: true, schema: { type: integer } } ]
      responses:
        "201": { description: "Copied.", content: { application/json: { schema: { type: object, required: [quote], properties: { quote: { $ref: "#/components/schemas/FinanceQuote" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes/{quote}/pdf:
    post:
      tags: [Finance]
      operationId: financeQuotePdfStore
      summary: Store the rendered quote PDF
      description: "The sheet is rasterised in the browser from the same print templates the invoice uses, then kept here so it can be reopened and mailed without re-rendering. The path is server-generated (`invoices/{uuid}`) — a client cannot point this at a file it does not own; a previous PDF is deleted after the new one is stored. Throttle 120/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: quote, in: path, required: true, schema: { type: integer } } ]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary, description: "PDF only." }
      responses:
        "200": { description: "Stored.", content: { application/json: { schema: { type: object, required: [quote], properties: { quote: { $ref: "#/components/schemas/FinanceQuote" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    get:
      tags: [Finance]
      operationId: financeQuotePdf
      summary: Stream the quote PDF
      description: "Inline for a preview, `?download=1` as an attachment. Served with `nosniff` and a `default-src 'none'; sandbox` CSP like every other blob this app serves. 404 while no PDF has been rendered. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: quote, in: path, required: true, schema: { type: integer } }
        - { name: download, in: query, required: false, schema: { type: boolean }, description: "Force an attachment instead of inline." }
      responses:
        "200": { description: "The PDF.", content: { application/pdf: { schema: { type: string, format: binary } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes/{quote}/email:
    post:
      tags: [Finance]
      operationId: financeQuoteEmail
      summary: Mail the quote to the customer
      description: "Goes out over the user's OWN company SMTP, deliberately independent of the workspace notification mailer. Requires an issued quote (422 `quote_not_sent`) and a stored PDF (422 `no_pdf`) — a mail that arrives without its quote is worse than one that fails to send. Falls back to the customer's address when `to` is omitted (422 `no_recipient` if there is none), and 422 `no_smtp` when no company mailer is configured. Audited with the recipient DOMAIN only, never the address. Throttle 10/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: quote, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: false, content: { application/json: { schema: { type: object, properties: { to: { type: [string, "null"], format: email } } } } } }
      responses:
        "200": { description: "Sent.", content: { application/json: { schema: { type: object, required: [ok, sent_at], properties: { ok: { type: boolean }, sent_at: { type: string, format: date-time } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "Not issued, no PDF, no recipient, or no company mailer.", content: { application/json: { schema: { type: object, properties: { error: { type: string, enum: [quote_not_sent, no_pdf, no_recipient, no_smtp] } } } } } }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes/{id}/restore:
    post:
      tags: [Finance]
      operationId: financeQuoteRestore
      summary: Restore a quote from the bin
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Restored.", content: { application/json: { schema: { type: object, required: [quote], properties: { quote: { $ref: "#/components/schemas/FinanceQuote" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes/{id}/force:
    delete:
      tags: [Finance]
      operationId: financeQuoteForceDelete
      summary: Delete a quote for good
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { type: object, required: [ok], properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/products/{product}/line:
    get:
      tags: [Finance]
      operationId: financeProductLine
      summary: The catalogue article as a document line
      description: "One place decides how an article becomes a line, so a line added by the picker and one added by a future import cannot differ in shape. `vatRate` is null when the article follows the company default. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: product, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Line.", content: { application/json: { schema: { type: object, required: [line], properties: { line: { $ref: "#/components/schemas/FinanceDocumentLine" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/projects/{project}/plan:
    get:
      tags: [Finance]
      operationId: financeProjectPlan
      summary: A project's tasks, hours and derived figures
      description: "Everything hanging off one project, plus the figures that only make sense together: estimated against worked, and billable hours still waiting. Progress is derived from the tasks, never stored — a stored percentage is wrong the moment a task changes. Capped at 1000 rows each. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: project, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200":
          description: Plan.
          content:
            application/json:
              schema:
                type: object
                required: [tasks, entries, totals]
                properties:
                  tasks: { type: array, items: { $ref: "#/components/schemas/FinanceProjectTask" } }
                  entries: { type: array, items: { $ref: "#/components/schemas/FinanceTimeEntry" } }
                  totals:
                    type: object
                    properties:
                      tasks: { type: integer }
                      tasks_done: { type: integer }
                      estimate_hours: { type: number }
                      worked_hours: { type: number }
                      unbilled_hours: { type: number, description: "Billable and not yet on an invoice." }
                      unbilled_value: { type: number, description: "Those hours at their frozen rates." }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/projects/{project}/tasks:
    post:
      tags: [Finance]
      operationId: financeProjectTaskStore
      summary: Add a task to a project
      description: "Appended at the end unless `sort` is given. A milestone is the same row with `is_milestone` — a date that matters with no work in it. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: project, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/FinanceProjectTaskInput" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, required: [task], properties: { task: { $ref: "#/components/schemas/FinanceProjectTask" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/projects/{project}/tasks/reorder:
    post:
      tags: [Finance]
      operationId: financeProjectTaskReorder
      summary: Reorder a project's tasks
      description: "One call rather than one per task: a drag reorders many rows at once and half an applied order is worse than none. Ids from another project are ignored rather than pulled in. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: project, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [ids], properties: { ids: { type: array, maxItems: 1000, items: { type: integer } } } } } } }
      responses:
        "200": { description: "Reordered.", content: { application/json: { schema: { type: object, required: [ok], properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/project-tasks/{task}:
    put:
      tags: [Finance]
      operationId: financeProjectTaskUpdate
      summary: Update a task
      description: "Partial; optimistic via `version`. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: task, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/FinanceProjectTaskInput" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, required: [task], properties: { task: { $ref: "#/components/schemas/FinanceProjectTask" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/VersionConflict" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeProjectTaskDestroy
      summary: Delete a task
      description: "The hours worked on it survive and are detached: work that was done stays logged, it simply loses the task it was filed under. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: task, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { type: object, required: [ok], properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/projects/{project}/time:
    post:
      tags: [Finance]
      operationId: financeTimeStore
      summary: Log hours on a project
      description: "The task is optional: not everything worth logging was planned. `hourly_rate` is FROZEN on the entry — taken from the customer's rate if not given — because a rate change next year must not rewrite what last year's work was worth. `billable` defaults to true, since the usual case for tracked time is that someone pays for it. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: project, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/FinanceTimeEntryInput" } } } }
      responses:
        "201": { description: "Logged.", content: { application/json: { schema: { type: object, required: [entry], properties: { entry: { $ref: "#/components/schemas/FinanceTimeEntry" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/time-entries/{entry}:
    put:
      tags: [Finance]
      operationId: financeTimeUpdate
      summary: Correct a logged hour
      description: "Refused with 422 `time_invoiced` once the entry is on an invoice: editing the hours behind a document someone has been sent would make the two disagree. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: entry, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/FinanceTimeEntryInput" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, required: [entry], properties: { entry: { $ref: "#/components/schemas/FinanceTimeEntry" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/VersionConflict" }
        "422": { description: "Already invoiced, or invalid.", content: { application/json: { schema: { type: object, properties: { error: { type: string, enum: [time_invoiced] } } } } } }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeTimeDestroy
      summary: Delete a logged hour
      description: "Refused with 422 `time_invoiced` once it is on an invoice. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: entry, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { type: object, required: [ok], properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "Already invoiced.", content: { application/json: { schema: { type: object, properties: { error: { type: string, enum: [time_invoiced] } } } } } }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/projects/{project}/invoice-time:
    post:
      tags: [Finance]
      operationId: financeInvoiceTime
      summary: Bill the hours worked on a project
      description: "Creates a draft invoice with ONE line per rate — a customer wants \"18.5 hours at 120\", not eleven identical lines. Every entry taken is stamped with the invoice inside the same transaction, which is what stops the same hour going out twice; entries with no rate are grouped as a zero-rate line rather than dropped, because silently leaving work off an invoice is the worse failure. Optional `until` bills up to a cut-off date. Answers 422 `nothing_to_invoice` when there is nothing waiting. Throttle 120/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: project, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: false, content: { application/json: { schema: { type: object, properties: { until: { type: [string, "null"], format: date } } } } } }
      responses:
        "201": { description: "Invoice created.", content: { application/json: { schema: { type: object, required: [invoice, entries], properties: { invoice: { $ref: "#/components/schemas/Invoice" }, entries: { type: integer, description: "How many entries went onto it." } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "Nothing waiting to be billed.", content: { application/json: { schema: { type: object, properties: { error: { type: string, enum: [nothing_to_invoice] } } } } } }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/quotes/{quote}/project:
    post:
      tags: [Finance]
      operationId: financeQuoteToProject
      summary: Turn a quote into a project
      description: "Only the SERVICE lines become tasks, each carrying the hours it was quoted at — hardware is something you deliver, not something you plan a day around, and it is already accounted for on the invoice. The first line of a line's description becomes the task title, the rest its detail. Idempotent: a second call returns the project it already made (`already: true`, 200). Throttle 120/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: quote, in: path, required: true, schema: { type: integer } } ]
      responses:
        "201": { description: "Project created.", content: { application/json: { schema: { type: object, required: [project], properties: { project: { $ref: "#/components/schemas/FinanceProject" } } } } } }
        "200": { description: "Already converted; the existing project is returned.", content: { application/json: { schema: { type: object, required: [project], properties: { project: { $ref: "#/components/schemas/FinanceProject" }, already: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/categories:
    post:
      tags: [Finance]
      operationId: financeCategoryStore
      summary: Create a receipt category
      description: "`name` (unique per user) is required; optional `color` + `icon`. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/CategoryInput" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, required: [category], properties: { category: { $ref: "#/components/schemas/FinanceCategory" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/categories/{category}:
    put:
      tags: [Finance]
      operationId: financeCategoryUpdate
      summary: Update a category (name, colour, icon, account_no)
      description: "Full replace of name/colour/icon/account_no (not just a rename). Name uniqueness ignores the current id. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: category, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/CategoryInput" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, required: [category], properties: { category: { $ref: "#/components/schemas/FinanceCategory" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeCategoryDestroy
      summary: Delete a category
      description: "Hard-delete a receipt category (no soft-delete/trash for categories). Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: category, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/transactions:
    post:
      tags: [Finance]
      operationId: financeTxStore
      summary: Create a bank transaction
      description: "`payment_method_id` + `date` + `amount` are required. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/TransactionInput" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, required: [transaction], properties: { transaction: { $ref: "#/components/schemas/BankTransaction" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/transactions/bulk:
    post:
      tags: [Finance]
      operationId: financeTxBulk
      summary: Import parsed bank-statement transactions (server dedups by sig)
      description: "Bulk-inserts parsed statement lines for one account, deduplicating by `sig` (against existing rows AND within the batch). Parsing stays client-side. Throttle 120/min."
      security: [ { bearerAuth: [] } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [payment_method_id, transactions]
              properties:
                payment_method_id: { type: integer, description: "Target account (must be an existing, owned, non-deleted payment method)." }
                transactions: { type: array, maxItems: 5000, items: { $ref: "#/components/schemas/TransactionBulkRow" } }
      responses:
        "201": { description: "Import result.", content: { application/json: { schema: { type: object, required: [created, skipped], properties: { created: { type: integer }, skipped: { type: integer, description: "Rows skipped as duplicates (by sig) or malformed." } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/transactions/{transaction}:
    put:
      tags: [Finance]
      operationId: financeTxUpdate
      summary: Update a bank transaction (optimistic concurrency)
      description: "Send `version` for optimistic concurrency (409 on mismatch). A client-supplied receipt blob_path is always dropped. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: transaction, in: path, required: true, schema: { type: integer } } ]
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/TransactionInput" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, required: [transaction], properties: { transaction: { $ref: "#/components/schemas/BankTransaction" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/VersionConflict" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeTxDestroy
      summary: Soft-delete a bank transaction
      description: "Move the transaction to trash. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: transaction, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/transactions/{id}/restore:
    post:
      tags: [Finance]
      operationId: financeTxRestore
      summary: Restore a bank transaction
      description: "Restore a soft-deleted transaction. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Restored.", content: { application/json: { schema: { type: object, required: [transaction], properties: { transaction: { $ref: "#/components/schemas/BankTransaction" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/transactions/{id}/force:
    delete:
      tags: [Finance]
      operationId: financeTxForce
      summary: Permanently delete a bank transaction
      description: "Permanently delete a trashed transaction and its receipt blobs. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: id, in: path, required: true, schema: { type: integer } } ]
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/transactions/{transaction}/receipts:
    post:
      tags: [Finance]
      operationId: financeReceiptAttach
      summary: Attach a receipt file to a transaction (multipart)
      description: "Upload a receipt file (max files.max_upload_mb) and append it to the transaction's receipts[]. The server assigns id + blob_path. Throttle 1200/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: transaction, in: path, required: true, schema: { type: integer } } ]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
                name: { type: string, maxLength: 500 }
                kind: { type: string, maxLength: 24, description: "Defaults to 'receipt'." }
                category: { type: string, maxLength: 160 }
                tags: { type: array, maxItems: 100, items: { type: string, maxLength: 100 } }
                contact_id: { type: string, maxLength: 64 }
                partner_id: { type: integer }
                vat: { type: string, maxLength: 16 }
                sig: { type: string, maxLength: 80, description: "Content signature for upload dedup (see TransactionReceipt.sig)." }
      responses:
        "201": { description: "Receipt attached; returns the updated transaction.", content: { application/json: { schema: { type: object, required: [transaction], properties: { transaction: { $ref: "#/components/schemas/BankTransaction" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/transactions/{transaction}/receipts/{receipt}:
    delete:
      tags: [Finance]
      operationId: financeReceiptDelete
      summary: Remove a receipt from a transaction
      description: "Removes the receipt by id (and deletes its blob). Deleting an unknown receipt id is a no-op that still returns the transaction. Throttle 600/min."
      security: [ { bearerAuth: [] } ]
      parameters: [ { name: transaction, in: path, required: true, schema: { type: integer } }, { name: receipt, in: path, required: true, schema: { type: string, description: "Receipt entry UUID." } } ]
      responses:
        "200": { description: "Updated transaction.", content: { application/json: { schema: { type: object, required: [transaction], properties: { transaction: { $ref: "#/components/schemas/BankTransaction" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/transactions/{transaction}/receipts/{receipt}/raw:
    get:
      tags: [Finance]
      operationId: financeReceiptRaw
      summary: Stream a receipt file
      description: "Streams the receipt's stored bytes inline (sandboxed). Throttle 3000/min."
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: transaction, in: path, required: true, schema: { type: integer } }
        - { name: receipt, in: path, required: true, schema: { type: string, description: "Receipt entry UUID." } }
        - { name: download, in: query, required: false, schema: { type: boolean }, description: "true → Content-Disposition: attachment; default inline." }
      responses:
        "200": { description: "Receipt bytes.", content: { application/octet-stream: { schema: { type: string, format: binary } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/receipts:
    post:
      tags: [Finance]
      operationId: financeStandaloneReceiptStore
      summary: Upload a standalone receipt ("Fremdbeleg") without a bank transaction
      description: >
        Files a receipt document that is NOT tied to a bank booking (documentation
        that must be kept even with no imported statement). Multipart; the file is
        stored plaintext on the files disk (blob_path/size/sig server-set). An
        optional bank_transaction_id links it to a booking. If a client-computed
        sig (sha256 of the file) matches an already-stored receipt, no new row/blob
        is created — the existing receipt is returned with duplicate:true instead
        (200, not 201). Throttle 1200/min.
      security: [ { bearerAuth: [] } ]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file: { type: string, format: binary }
                name: { type: string, maxLength: 500 }
                scope: { type: string, enum: [business, private], description: "Omit to follow the linked booking (a loose receipt is business)." }
                kind: { type: string, maxLength: 24 }
                category: { type: string, maxLength: 160 }
                tags: { type: array, items: { type: string, maxLength: 100 } }
                vat: { type: string, maxLength: 16 }
                amount: { type: number, format: double }
                currency: { type: string, maxLength: 8, description: "Uppercased server-side." }
                date: { type: string, format: date }
                order_ref: { type: string, maxLength: 64 }
                doc_number: { type: string, maxLength: 64 }
                note: { type: string, maxLength: 2000 }
                ocr: { type: string, maxLength: 200000 }
                sig: { type: string, maxLength: 128, description: "Client-computed content-dedup signature (sha256 of the file). Omit to skip dedup." }
                partner_id: { type: integer }
                bank_transaction_id: { type: integer }
                finance_project_id: { type: integer }
      responses:
        "200": { description: "A receipt with the same sig already exists — that existing receipt is returned unchanged, no new row/blob created.", content: { application/json: { schema: { type: object, properties: { receipt: { $ref: "#/components/schemas/FinanceReceipt" }, duplicate: { type: boolean, enum: [true] } } } } } }
        "201": { description: "Created.", content: { application/json: { schema: { type: object, properties: { receipt: { $ref: "#/components/schemas/FinanceReceipt" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/receipts/{receipt}:
    put:
      tags: [Finance]
      operationId: financeStandaloneReceiptUpdate
      summary: Update a standalone receipt (optimistic version)
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: receipt, in: path, required: true, schema: { type: integer } }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, maxLength: 500 }
                category: { type: string, nullable: true }
                tags: { type: array, items: { type: string } }
                vat: { type: string, nullable: true }
                amount: { type: number, format: double, nullable: true }
                currency: { type: string, nullable: true, description: "Uppercased server-side." }
                date: { type: string, format: date, nullable: true }
                order_ref: { type: string, nullable: true }
                doc_number: { type: string, nullable: true }
                note: { type: string, nullable: true }
                partner_id: { type: integer, nullable: true }
                bank_transaction_id: { type: integer, nullable: true, description: "Link/unlink this receipt to a single bank transaction (null unlinks). Setting this server-side clears linked_transaction_ids — the two are mutually exclusive." }
                linked_transaction_ids: { type: array, items: { type: integer }, maxItems: 8, nullable: true, description: "Split-payment link: link/unlink this receipt to SEVERAL bank transactions whose amounts sum to it (null unlinks). Setting a non-empty array server-side clears bank_transaction_id." }
                finance_project_id: { type: integer, nullable: true }
                version: { type: integer, minimum: 0 }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, properties: { receipt: { $ref: "#/components/schemas/FinanceReceipt" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/VersionConflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Finance]
      operationId: financeStandaloneReceiptDestroy
      summary: Soft-delete a standalone receipt
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: receipt, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: "Trashed.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/receipts/{id}/restore:
    post:
      tags: [Finance]
      operationId: financeStandaloneReceiptRestore
      summary: Restore a soft-deleted standalone receipt
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: "Restored.", content: { application/json: { schema: { type: object, properties: { receipt: { $ref: "#/components/schemas/FinanceReceipt" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/receipts/{id}/force:
    delete:
      tags: [Finance]
      operationId: financeStandaloneReceiptForce
      summary: Permanently delete a standalone receipt (removes the stored file)
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: "Deleted.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /finance/receipts/{receipt}/raw:
    get:
      tags: [Finance]
      operationId: financeStandaloneReceiptRaw
      summary: Stream a standalone receipt file (sandboxed)
      security: [ { bearerAuth: [] } ]
      parameters:
        - { name: receipt, in: path, required: true, schema: { type: integer } }
        - { name: download, in: query, required: false, schema: { type: boolean } }
      responses:
        "200": { description: "Receipt bytes.", content: { application/octet-stream: { schema: { type: string, format: binary } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /invoices/ocr:
    post:
      tags: [Finance]
      operationId: invoicesOcr
      summary: OCR a receipt to line-structured text (transient plaintext)
      description: >
        Transient server-side OCR. The client POSTs the raw document bytes ONLY for
        text extraction; the server processes them in a shredded temp file, returns
        line-structured text, and stores/logs NOTHING (Cache-Control: no-store). The
        receipt file itself is stored separately as a plaintext blob via
        POST /finance/transactions/{transaction}/receipts (and invoice PDFs via
        POST /finance/invoices/{invoice}/pdf). The server returns ONLY text — it does
        NOT parse total/merchant/date/VAT (that recognition stays client-side and is
        identical across web/iOS/Android). PDFs use the embedded text layer when
        present (fast path, `source: pdf-text`), otherwise rasterise+OCR
        (`source: ocr`, ≤30 pages); images are OCR'd directly. `text` preserves visual
        line breaks (`\n`). Best-effort: a 501/timeout leaves manual entry intact.
        Requires the `finance` module. Throttle: 120 req/min (the receipt inbox
        fires one call per file sequentially for a batch upload).
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: >
                    The raw document bytes. Allowed: image/jpeg,png,gif,webp,bmp,tiff,avif
                    or application/pdf. Max 25 MiB.
                lang:
                  type: string
                  pattern: "^[a-z]{3}(\\+[a-z]{3})*$"
                  description: "Tesseract language string; default deu+eng."
                force_ocr:
                  type: boolean
                  description: >
                    Force rasterise+OCR of a PDF, skipping the embedded text layer.
                    Use when that layer is justified-mangled (spaces baked mid-word,
                    e.g. "Softw are"). Ignored for images. Default false.
      responses:
        "200":
          description: Extracted text.
          content:
            application/json:
              schema:
                type: object
                required: [text, source, pages]
                properties:
                  text:
                    type: string
                    description: Line-structured plain text (one visual line per newline).
                  source:
                    type: string
                    enum: [pdf-text, ocr]
                    description: "pdf-text = PDF embedded text layer; ocr = rasterised/scanned."
                  pages:
                    type: integer
                    description: Informational page count.
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "413":
          description: File exceeds the 25 MiB OCR size limit.
        "415":
          description: Unsupported document type.
        "422":
          description: >
            Either the request failed validation (missing/invalid `file`, a `lang`
            not matching ^[a-z]{3}(\+[a-z]{3})*$, or a non-boolean `force_ocr`) →
            standard Laravel body { message, errors }; OR OCR ran but produced no
            usable text → { error: "no_text" }.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ValidationError"
                  - type: object
                    required: [error]
                    properties:
                      error: { type: string, enum: [no_text] }
        "429":
          description: Rate limit exceeded (Retry-After header).
        "501":
          description: OCR toolchain not available on this server (client falls back to manual entry).

  /company:
    get:
      tags: [Company]
      operationId: companyShow
      summary: Read the caller's company profile + invoice defaults
      description: >
        The user's own business identity and invoice settings (name, address, tax/VAT
        ids, bank details, number format + next number, default VAT rate, payment terms,
        template, accent/heading colours). Non-secret — served in the clear. `has_logo`
        indicates whether a company logo is stored (fetch it at /company/logo).
      responses:
        "200":
          description: The company profile.
          content:
            application/json:
              schema:
                type: object
                properties:
                  company: { $ref: "#/components/schemas/CompanyProfile" }
        "401": { $ref: "#/components/responses/Unauthorized" }
    put:
      tags: [Company]
      operationId: companyUpdate
      summary: Update the caller's company profile
      description: >
        Update any subset of the company/invoice fields. Send JSON, or multipart to
        also set a raster `logo` (png/jpg/gif/webp, ≤2 MB; inline SVG is rejected as a
        stored-XSS vector) or `remove_logo=true`. Throttle 60/min.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CompanyProfile" }
          multipart/form-data:
            schema:
              allOf:
                - $ref: "#/components/schemas/CompanyProfile"
                - type: object
                  properties:
                    logo: { type: string, format: binary }
                    remove_logo: { type: boolean }
      responses:
        "200":
          description: Saved profile.
          content:
            application/json:
              schema:
                type: object
                properties:
                  company: { $ref: "#/components/schemas/CompanyProfile" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { description: "Rate limit exceeded."}

  /company/logo:
    get:
      tags: [Company]
      operationId: companyLogo
      summary: Stream the caller's company logo
      description: >
        Returns the stored raster logo inline (sandboxed, nosniff). 404 if none is set.
        Throttle 120/min.
      responses:
        "200":
          description: The logo image bytes.
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { description: "No logo stored."}

  # ── Per-user non-display settings (notify channels + file version cap) ──
  /settings:
    get:
      tags: [Preferences]
      operationId: settingsShow
      summary: Read the caller's per-user settings
      description: >
        Non-secret per-user settings a mobile client needs beyond display prefs:
        the personal file version cap.
      responses:
        "200": { description: "Settings.", content: { application/json: { schema: { $ref: "#/components/schemas/UserSettings" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
    put:
      tags: [Preferences]
      operationId: settingsUpdate
      summary: Update per-user settings (partial)
      description: "Updates any subset; unspecified keys are left unchanged. Throttle 60/min."
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UserSettings" }
      responses:
        "200": { description: "Updated settings.", content: { application/json: { schema: { $ref: "#/components/schemas/UserSettings" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { description: "Rate limit exceeded."}

  # ── Owner-side device pairing ──
  /device-pairings:
    post:
      tags: [DevicePairings]
      operationId: devicePairingStore
      summary: Generate a pairing code + QR (owner)
      description: "The owner (already paired) starts pairing a NEW device: returns a pairing id + QR data-URI carrying a short-lived one-time code (never a token). Throttle 20/min."
      responses:
        "200": { description: "Pairing started.", content: { application/json: { schema: { type: object, required: [id], properties: { id: { type: integer, format: int64 }, qr: { type: string, description: "SVG data-URI." }, expires_at: { type: string, format: date-time } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { description: "Rate limit exceeded."}
  /device-pairings/cli:
    post:
      tags: [DevicePairings]
      operationId: devicePairingStoreCli
      summary: Generate a CLI pairing code (owner)
      description: "Like /device-pairings but returns a copyable text code (60s TTL) for a CLI client. Throttle 20/min."
      responses:
        "200": { description: "Pairing started.", content: { application/json: { schema: { type: object, required: [id, code], properties: { id: { type: integer, format: int64 }, code: { type: string }, expires_at: { type: string, format: date-time } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { description: "Rate limit exceeded."}
  /device-pairings/{devicePairing}:
    get:
      tags: [DevicePairings]
      operationId: devicePairingShow
      summary: Poll a pairing's state (owner)
      description: "Owner-scoped (foreign pairing → 404). Returns the current status + the claiming device name."
      parameters: [{ name: devicePairing, in: path, required: true, schema: { type: integer, format: int64 } }]
      responses:
        "200": { description: "State.", content: { application/json: { schema: { type: [object, "null"], properties: { status: { type: string, enum: [pending, pending_approval, approved, rejected, consumed, expired] }, device_name: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
  /device-pairings/{devicePairing}/approve:
    post:
      tags: [DevicePairings]
      operationId: devicePairingApprove
      summary: Approve the claimed device (owner)
      description: "Owner-scoped. After approval the new device's POST /auth/pair/collect returns its token. Throttle 20/min."
      parameters: [{ name: devicePairing, in: path, required: true, schema: { type: integer, format: int64 } }]
      responses:
        "200": { description: "Approved.", content: { application/json: { schema: { type: object, properties: { status: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "Pairing is not awaiting approval (wrong state or expired)." }
        "429": { description: "Rate limit exceeded."}
  /device-pairings/{devicePairing}/reject:
    post:
      tags: [DevicePairings]
      operationId: devicePairingReject
      summary: Reject the claimed device (owner)
      description: "Owner-scoped. Throttle 20/min."
      parameters: [{ name: devicePairing, in: path, required: true, schema: { type: integer, format: int64 } }]
      responses:
        "200": { description: "Rejected.", content: { application/json: { schema: { type: object, properties: { status: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
        "410": { description: "Pairing code expired (Gone)." }

  # ── 2FA + app password (self-service) ──
  /user/two-factor/enable:
    post:
      tags: [TwoFactor]
      operationId: twoFactorEnable
      summary: Enable TOTP (generate secret + recovery codes)
      description: "Generates a new TOTP secret + recovery codes (stored encrypted). NOT yet active — call /confirm with a live code. Idempotent. Requires `current_password` (guard-agnostic Hash::check) on EVERY path — web and native alike; native device tokens no longer bypass it (max-security, internet-facing). Throttle 10/min."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [current_password]
              properties:
                current_password:
                  type: string
                  format: password
                  description: "Required on every path (web + native). 422 {errors:{current_password}} if missing/wrong."
      responses:
        "200": { description: "Secret generated.", content: { application/json: { schema: { type: object, properties: { enabled: { type: boolean, enum: [true] } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { description: "Rate limit exceeded."}
  /user/two-factor/qr:
    get:
      tags: [TwoFactor]
      operationId: twoFactorQr
      summary: Get the TOTP QR + secret + otpauth URI
      description: "ENROLLMENT-ONLY: available only in the window between enable and confirm. Once 2FA is confirmed the secret is never handed out again (a stolen device token must not be able to reproduce the second factor). 404 if 2FA not enabled OR already confirmed. Throttle 60/min."
      responses:
        "200": { description: "QR data.", content: { application/json: { schema: { type: object, required: [svg, secret, uri], properties: { svg: { type: string }, secret: { type: string }, uri: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { description: "2FA not enabled, or already confirmed."}
  /user/two-factor/confirm:
    post:
      tags: [TwoFactor]
      operationId: twoFactorConfirm
      summary: Confirm 2FA with a live TOTP code
      description: "Validates the code and activates 2FA (sets two_factor_confirmed_at). 422 on wrong/expired code. Throttle 10/min."
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [code], properties: { code: { type: string } } } } } }
      responses:
        "200": { description: "Confirmed.", content: { application/json: { schema: { type: object, properties: { confirmed: { type: boolean, enum: [true] } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { description: "Invalid/expired code."}
        "429": { description: "Rate limit exceeded."}
  /user/two-factor/recovery-codes:
    post:
      tags: [TwoFactor]
      operationId: twoFactorRecoveryCodes
      summary: List recovery codes
      description: "POST (not GET): the `current_password` step-up travels in the JSON body, never a query string — a password in a URL leaks into access/request logs, history and proxies (and OkHttp forbids a GET body). Only after 2FA is confirmed (else 404). Throttle 60/min."
      requestBody:
        required: true
        content: { application/json: { schema: { type: object, required: [current_password], properties: { current_password: { type: string, format: password, description: "Required on every path (web + native); native device tokens no longer bypass it. 422 if missing/wrong." } } } } }
      responses:
        "200": { description: "Codes.", content: { application/json: { schema: { type: object, required: [recovery_codes], properties: { recovery_codes: { type: array, items: { type: string } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { description: "2FA not active."}
        "422": { $ref: "#/components/responses/ValidationError" }
  /user/two-factor/recovery-codes/regenerate:
    post:
      tags: [TwoFactor]
      operationId: twoFactorRegenerateRecoveryCodes
      summary: Regenerate recovery codes
      description: "Invalidates the old set and returns a fresh one. Requires a fresh `current_password` step-up. Throttle 10/min."
      requestBody:
        required: true
        content: { application/json: { schema: { type: object, required: [current_password], properties: { current_password: { type: string, format: password, description: "Required on every path (web + native); native device tokens no longer bypass it. 422 if missing/wrong." } } } } }
      responses:
        "200": { description: "New codes.", content: { application/json: { schema: { type: object, required: [recovery_codes], properties: { recovery_codes: { type: array, items: { type: string } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { description: "Rate limit exceeded."}
  /user/two-factor:
    delete:
      tags: [TwoFactor]
      operationId: twoFactorDisable
      summary: Disable 2FA
      description: "Clears the TOTP secret, recovery codes, and confirmed flag. Idempotent. Requires a fresh `current_password` step-up so a stolen device token cannot disable 2FA. Throttle 10/min."
      requestBody:
        required: true
        content: { application/json: { schema: { type: object, required: [current_password], properties: { current_password: { type: string, format: password, description: "Required on every path (web + native); native device tokens no longer bypass it. 422 if missing/wrong." } } } } }
      responses:
        "200": { description: "Disabled.", content: { application/json: { schema: { type: object, properties: { enabled: { type: boolean, enum: [false] } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { $ref: "#/components/responses/ValidationError" }
  /user/passkeys:
    get:
      tags: [Passkeys]
      operationId: passkeysIndex
      summary: List the current user's passkeys
      responses:
        "200":
          description: Owner-scoped passkeys + whether WebAuthn is configured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  passkeys: { type: array, items: { $ref: '#/components/schemas/WebauthnCredential' } }
                  enabled: { type: boolean }
        "401": { $ref: "#/components/responses/Unauthorized" }
    post:
      tags: [Passkeys]
      operationId: passkeysRegister
      summary: Register a new passkey (verify attestation)
      description: >
        Verifies the attestation from navigator.credentials.create() against the
        cached challenge and stores the credential (public-key only). Requires a
        fresh `current_password` step-up. Throttle 20/min.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [credential, current_password]
              properties:
                credential: { type: object, additionalProperties: true, description: "Serialized PublicKeyCredential (attestation)." }
                name: { type: [string, "null"], maxLength: 120 }
                current_password: { type: string, format: password }
      responses:
        "201":
          description: Stored.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WebauthnCredential' }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: '#/components/responses/RateLimited' }
  /user/passkeys/options:
    post:
      tags: [Passkeys]
      operationId: passkeysRegisterOptions
      summary: WebAuthn attestation (creation) options for the current user
      description: "Standard PublicKeyCredentialCreationOptionsJSON; feed to navigator.credentials.create(). Challenge cached per user. Throttle 30/min."
      responses:
        "200": { description: "Creation options JSON.", content: { application/json: { schema: { type: object, additionalProperties: true } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: '#/components/responses/RateLimited' }
  /user/passkeys/{credential}:
    put:
      tags: [Passkeys]
      operationId: passkeysRename
      summary: Rename a passkey
      parameters:
        - { name: credential, in: path, required: true, schema: { type: integer } }
      requestBody:
        required: true
        content: { application/json: { schema: { type: object, required: [name], properties: { name: { type: string, maxLength: 120 } } } } }
      responses:
        "200": { description: "OK."}
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
    delete:
      tags: [Passkeys]
      operationId: passkeysDestroy
      summary: Remove a passkey
      parameters:
        - { name: credential, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: "Removed."}
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/NotFound" }
  /user/password:
    put:
      tags: [TwoFactor]
      operationId: userPasswordUpdate
      summary: Change the app login password
      description: >
        Validates `current_password` (guard-agnostic Hash::check — Fortify's
        current_password:web rule would fail for a bearer token) and sets a new
        password (min 12, confirmed).
        Throttle 10/min.
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, required: [current_password, password, password_confirmation], properties: { current_password: { type: string }, password: { type: string, minLength: 12 }, password_confirmation: { type: string } } }
      responses:
        "200": { description: "Changed.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { description: "Wrong current password or invalid new password."}
        "429": { description: "Rate limit exceeded."}
  /user/email/verify/resend:
    post:
      tags: [TwoFactor]
      operationId: emailVerifyResend
      summary: Re-send the e-mail verification link
      description: "No-op (ok:true) when already verified. Needs SMTP configured. Throttle 60/min."
      responses:
        "200": { description: "Queued (or already verified).", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { description: "Rate limit exceeded."}

  # ── Admin: users ──
  /users:
    get:
      tags: [Users]
      operationId: usersIndex
      summary: List users (admin)
      description: "All users with effective limits, groups, 2FA/verified state, and last login. No credentials. Admin-gated (403 otherwise)."
      responses:
        "200": { description: "Users.", content: { application/json: { schema: { type: object, required: [users], properties: { users: { type: array, items: { $ref: "#/components/schemas/AdminUser" } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    post:
      tags: [Users]
      operationId: usersStore
      summary: Create a user (admin)
      description: "role/quotas/modules are privilege fields (set server-side, never mass-assigned). Omit password to send a reset mail (if SMTP on). Throttle 60/min."
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/AdminUserWrite" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, properties: { user: { $ref: "#/components/schemas/AdminUser" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { description: "Rate limit exceeded."}
  /users/{user}:
    parameters: [{ name: user, in: path, required: true, schema: { type: integer } }]
    put:
      tags: [Users]
      operationId: usersUpdate
      summary: Update a user (admin)
      description: "Password prohibited (use reset-password). Guards: cannot demote the last admin. Throttle 60/min."
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/AdminUserWrite" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, properties: { user: { $ref: "#/components/schemas/AdminUser" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "Validation failed, or the last-admin guard tripped." }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Users]
      operationId: usersDestroy
      summary: Delete a user (admin, GDPR crypto-shred)
      description: "Purges the user + all owned data. Cannot delete self or the last admin. Throttle 10/min."
      responses:
        "204": { description: "Deleted (no content)."}
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "Self-delete or last-admin guard." }
        "429": { $ref: "#/components/responses/RateLimited" }
  /users/{user}/reset-password:
    parameters: [{ name: user, in: path, required: true, schema: { type: integer } }]
    post:
      tags: [Users]
      operationId: usersResetPassword
      summary: Send a password-reset mail (admin)
      description: "422 when SMTP is not configured (use invite-link instead). Throttle 10/min."
      responses:
        "200": { description: "Sent.", content: { application/json: { schema: { type: object, properties: { message: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "SMTP not configured."}
        "429": { $ref: "#/components/responses/RateLimited" }
  /users/{user}/reset-2fa:
    parameters: [{ name: user, in: path, required: true, schema: { type: integer } }]
    post:
      tags: [Users]
      operationId: usersResetTwoFactor
      summary: Clear a user's 2FA (admin recovery)
      description: "Nulls the TOTP secret/codes/confirmed flag. Throttle 10/min."
      responses:
        "200": { description: "Cleared.", content: { application/json: { schema: { type: object, properties: { message: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /users/{user}/avatar:
    parameters: [{ name: user, in: path, required: true, schema: { type: integer } }]
    get:
      tags: [Users]
      operationId: usersAvatar
      summary: Stream a user's avatar (admin)
      description: "Non-secret. 404 if none stored."
      responses:
        "200": { description: "Image.", content: { image/*: { schema: { type: string, format: binary } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { description: "No avatar stored (or user not found)."}
  /users/{user}/invite-link:
    parameters: [{ name: user, in: path, required: true, schema: { type: integer } }]
    post:
      tags: [Users]
      operationId: usersInviteLink
      summary: Generate a one-time login/password-set link (admin)
      description: "Single-use, time-limited link; the plaintext token appears only in `url` (never stored/logged — only its SHA-256). Optionally emails it. Throttle 20/min."
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [ttl_hours], properties: { ttl_hours: { type: integer, enum: [1, 24, 168, 720] }, send: { type: boolean, default: false } } } } } }
      responses:
        "200": { description: "Link.", content: { application/json: { schema: { type: object, required: [url, sent], properties: { url: { type: string, format: uri }, expires_at: { type: string, format: date-time }, sent: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { description: "Rate limit exceeded."}

  # ── Admin: security log ──
  /security-log:
    get:
      tags: [SecurityLog]
      operationId: securityLogIndex
      summary: List audit-log entries (admin, read-only)
      description: "Paginated, filterable audit trail. Metadata-only. Admin-gated. Throttle 60/min."
      parameters:
        - { name: action, in: query, schema: { type: string }, description: "Exact action, or a `prefix.*` group match." }
        - { name: user, in: query, schema: { type: integer } }
        - { name: since, in: query, schema: { type: string }, description: "ISO-8601 or -24h/-7d." }
        - { name: page, in: query, schema: { type: integer, default: 1 } }
        - { name: per_page, in: query, schema: { type: integer, default: 50, maximum: 100 } }
      responses:
        "200": { description: "Entries.", content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: "#/components/schemas/SecurityLogEntry" } }, meta: { type: object, properties: { total: { type: integer }, per_page: { type: integer }, current_page: { type: integer }, last_page: { type: integer } } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /security-log/export:
    get:
      tags: [SecurityLog]
      operationId: securityLogExport
      summary: Export the audit log (admin, CSV/NDJSON)
      description: "Streamed, capped 10000, same filters as index. CSV cells are formula-injection-neutralised. Throttle 10/min."
      parameters:
        - { name: format, in: query, schema: { type: string, enum: [csv, json], default: csv } }
        - { name: limit, in: query, schema: { type: integer, default: 10000, maximum: 10000 } }
        - { name: action, in: query, schema: { type: string } }
        - { name: user, in: query, schema: { type: integer } }
        - { name: since, in: query, schema: { type: string } }
      responses:
        "200": { description: "Stream.", content: { text/csv: { schema: { type: string, format: binary } }, application/x-ndjson: { schema: { type: string, format: binary } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ── Per-user Paperless ──
  /paperless/terms:
    get:
      tags: [Paperless]
      operationId: paperlessTerms
      summary: Cached Paperless term quick-picks
      description: "{configured, tags, document_types, correspondents} from the local cache (no live call). Throttle 60/min."
      responses:
        "200": { description: "Terms.", content: { application/json: { schema: { type: object, required: [configured, tags, document_types, correspondents], properties: { configured: { type: boolean }, tags: { type: array, items: { $ref: "#/components/schemas/PaperlessTerm" } }, document_types: { type: array, items: { $ref: "#/components/schemas/PaperlessTerm" } }, correspondents: { type: array, items: { $ref: "#/components/schemas/PaperlessTerm" } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
    post:
      tags: [Paperless]
      operationId: paperlessCreateTerm
      summary: Create a Paperless tag / document type / correspondent
      description: "Creates it in the live Paperless + caches. 422 if not configured or the call fails. Throttle 60/min."
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [kind, name], properties: { kind: { type: string, enum: [tag, document_type, correspondent] }, name: { type: string, maxLength: 255 } } } } } }
      responses:
        "200": { description: "Created/found.", content: { application/json: { schema: { type: object, required: [ok, id, name], properties: { ok: { type: boolean }, id: { type: integer }, name: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { description: "Not configured / validation / Paperless error."}
        "429": { $ref: "#/components/responses/RateLimited" }
  /paperless/documents:
    post:
      tags: [Paperless]
      operationId: paperlessSubmit
      summary: Forward a decrypted document to Paperless (transient cleartext)
      description: >
        **Transient-cleartext boundary** (like POST /invoices/ocr):
        the client posts the already-decrypted bytes; the server forwards them to
        the user's own Paperless and stores/logs nothing (`Cache-Control: no-store`).
        Returns the Paperless async task id. Throttle 20/min.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema: { type: object, required: [file], properties: { file: { type: string, format: binary, description: "Decrypted PDF/image, max 50 MB." }, title: { type: string, maxLength: 255 }, created: { type: string, format: date }, correspondent: { type: integer }, document_type: { type: integer }, tags: { type: array, items: { type: integer } } } }
      responses:
        "200": { description: "Accepted.", content: { application/json: { schema: { type: object, required: [ok, task], properties: { ok: { type: boolean }, task: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "413": { description: "File exceeds 50 MB."}
        "422": { description: "Not configured / validation / Paperless error."}
        "429": { $ref: "#/components/responses/RateLimited" }
  /paperless/sync:
    post:
      tags: [Paperless]
      operationId: paperlessSync
      summary: Refresh the cached Paperless terms from the live instance
      description: "Pulls all tags/document types/correspondents into the cache. {ok, counts}. Empty counts when unconfigured (no error). Throttle 20/min."
      responses:
        "200": { description: "Synced.", content: { application/json: { schema: { type: object, required: [ok, counts], properties: { ok: { type: boolean }, counts: { type: object, properties: { tag: { type: integer }, document_type: { type: integer }, correspondent: { type: integer } } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { description: "Paperless error."}
        "429": { $ref: "#/components/responses/RateLimited" }

  /paperless/config:
    get:
      tags: [Paperless]
      operationId: paperlessConfigShow
      summary: Per-user Paperless connection config
      description: "Instance URL + enabled flag + has_token (the API token is never returned) + cached term counts. Throttle 60/min."
      responses:
        "200": { description: "Config.", content: { application/json: { schema: { $ref: "#/components/schemas/PaperlessConfig" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
    put:
      tags: [Paperless]
      operationId: paperlessConfigUpdate
      summary: Update the per-user Paperless config
      description: "Sets URL / enabled / token. A blank/omitted token preserves the stored one; the token is never returned. Throttle 60/min."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paperless_enabled: { type: boolean }
                paperless_url: { type: [string, "null"], format: uri, maxLength: 255 }
                paperless_token: { type: [string, "null"], maxLength: 255, description: "Blank/omitted keeps the stored token." }
      responses:
        "200": { description: "Updated config.", content: { application/json: { schema: { $ref: "#/components/schemas/PaperlessConfig" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /paperless/config/test:
    post:
      tags: [Paperless]
      operationId: paperlessConfigTest
      summary: Test the Paperless connection
      description: "Pings Paperless using the posted URL+token (falling back to the stored ones). SSRF-guarded. Throttle 20/min."
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                paperless_url: { type: [string, "null"], format: uri }
                paperless_token: { type: [string, "null"] }
      responses:
        "200": { description: "Result (200 even on failure; check `ok`).", content: { application/json: { schema: { type: object, required: [ok], properties: { ok: { type: boolean }, detail: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ── Admin: settings ──
  /admin/notifications:
    get:
      tags: [Settings]
      operationId: adminNotificationsShow
      summary: Notification config (admin)
      description: "SMTP/NTFY/webhook config. Secret values are NEVER returned — has_smtp_password / has_ntfy_token / has_webhook_secret booleans instead."
      responses:
        "200": { description: "Config.", content: { application/json: { schema: { $ref: "#/components/schemas/NotificationConfig" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    put:
      tags: [Settings]
      operationId: adminNotificationsUpdate
      summary: Update notification config (admin)
      description: "Only submitted fields are persisted. A blank secret field preserves the stored value. Throttle 60/min."
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/NotificationConfigWrite" }
      responses:
        "200": { description: "Updated config (secrets masked).", content: { application/json: { schema: { $ref: "#/components/schemas/NotificationConfig" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /admin/notifications/test:
    post:
      tags: [Settings]
      operationId: adminNotificationsTest
      summary: Send a test notification (admin)
      description: "Sends a test message over one channel using the saved settings. A connection/send FAILURE returns 200 {ok:false, detail} (unified test-endpoint convention, matches backup/destinations/test); only request validation is 422. Throttle 20/min."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [channel]
              properties:
                channel: { type: string, enum: [mail, ntfy, webhook] }
      responses:
        "200": { description: "{ ok: boolean, detail?: string } — ok:false means the test send failed.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean }, detail: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { description: "Request validation failed (bad channel)." }
        "429": { $ref: "#/components/responses/RateLimited" }

  /admin/security:
    get:
      tags: [Settings]
      operationId: adminSecurityShow
      summary: Security policy (admin)
      description: "Workspace paired-device cap, password policy (min length + required classes + breach check) and the force-2FA toggle."
      responses:
        "200": { description: "Policy.", content: { application/json: { schema: { $ref: "#/components/schemas/SecurityPolicy" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    put:
      tags: [Settings]
      operationId: adminSecurityUpdate
      summary: Update security policy (admin)
      description: "Sets the device cap (1–100) plus the password policy + force-2FA. Audits the diff. Throttle 60/min."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [max_connected_devices]
              properties:
                max_connected_devices: { type: integer, minimum: 1, maximum: 100 }
                pw_min_length: { type: [integer, "null"], minimum: 8, maximum: 128 }
                pw_require_mixed_case: { type: boolean }
                pw_require_numbers: { type: boolean }
                pw_require_symbols: { type: boolean }
                pw_check_breaches: { type: boolean }
                force_2fa: { type: boolean }
      responses:
        "200": { description: "Updated policy.", content: { application/json: { schema: { $ref: "#/components/schemas/SecurityPolicy" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }

  /admin/limits:
    get:
      tags: [Settings]
      operationId: adminLimitsShow
      summary: Session/auth lifetimes and retention windows (admin)
      description: "Admin-editable workspace limits; each overlays a config('...') key at boot. NULL inherits the env/config default. Returns stored overrides + effective values."
      responses:
        "200": { description: "Limits.", content: { application/json: { schema: { type: object, properties: { settings: { type: object }, effective: { type: object } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    put:
      tags: [Settings]
      operationId: adminLimitsUpdate
      summary: Update workspace limits (admin)
      description: "Set any of: sanctum_expiration_minutes, session_lifetime_minutes, device_wipe_grace_minutes, device_idle_days, audit/access_log/request_log retention days, backup_stale_hours. null clears an override. Throttle 60/min."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: { type: [integer, "null"] }
      responses:
        "200": { description: "Saved.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /admin/dashboard:
    get:
      tags: [Settings]
      operationId: adminDashboard
      summary: Admin overview dashboard (admin)
      description: "Read-only aggregate for the admin dashboard: app/PHP/Laravel versions, DB+cache health, disk + per-module storage + growth trend, worker queue depth/failed, scheduled-task liveness, error + backup status, and fleet counts (users/sessions/devices/blocked). Container CPU/mem come from /admin/docker/containers."
      responses:
        "200":
          description: "Dashboard snapshot."
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions: { type: object, properties: { app: { type: string }, php: { type: string }, laravel: { type: string } } }
                  health: { type: object, properties: { database: { type: string }, cache: { type: string }, queue_driver: { type: string } } }
                  resources: { type: object }
                  queue: { type: object, properties: { pending: { type: integer }, failed: { type: integer } } }
                  scheduler: { type: object }
                  errors: { type: object }
                  backup: { type: object }
                  counts: { type: object }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /admin/docker/containers:
    get:
      tags: [Settings]
      operationId: adminDockerContainers
      summary: List compose services + state (admin)
      description: "Proxies the bounded docker-control agent sidecar. When the agent is not configured (no token) or unreachable, returns configured/reachable flags + operator commands instead. The app never touches the docker socket."
      responses:
        "200":
          description: "Services (or a not-configured / not-reachable payload)."
          content:
            application/json:
              schema:
                type: object
                properties:
                  configured: { type: boolean }
                  reachable: { type: boolean }
                  services: { type: array, items: { type: object, properties: { service: { type: string }, state: { type: string }, status: { type: string }, image: { type: string }, cpu: { type: string, description: "Live CPU%, e.g. 0.50%." }, mem: { type: string, description: "Live memory usage, e.g. 120MiB / 8GiB." }, mem_perc: { type: string } } } }
                  operator: { type: object, additionalProperties: { type: string } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /admin/docker/action:
    post:
      tags: [Settings]
      operationId: adminDockerAction
      summary: Run an allowlisted action on a compose service (admin)
      description: "Bounded control via the agent sidecar: restart/stop/start/recreate/pull/logs on a validated project service. Not arbitrary docker. 503 when the agent is unconfigured/unreachable. Throttle 60/min."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [service, action]
              properties:
                service: { type: string, maxLength: 64 }
                action: { type: string, enum: [restart, stop, start, recreate, pull, logs] }
      responses:
        "200": { description: "Result (ok + output).", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean }, action: { type: string }, service: { type: string }, output: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
        "503": { description: "Agent unconfigured or unreachable." }

  /admin/system:
    get:
      tags: [Settings]
      operationId: adminSystemShow
      summary: System / maintenance overview (admin, read-only)
      description: "Operational status snapshot (queue/storage/backup/scheduler/disk), scheduled-task liveness, the in-app error log and recent audit trail. Metadata only. Throttle 60/min."
      responses:
        "200": { description: "Overview.", content: { application/json: { schema: { $ref: "#/components/schemas/SystemOverview" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /admin/system/errors/{error}/resolve:
    post:
      tags: [Settings]
      operationId: adminSystemResolveError
      summary: Resolve an error event (admin)
      description: "Marks a recorded error as resolved (it reappears if it recurs). Throttle 60/min."
      parameters: [{ name: error, in: path, required: true, schema: { type: integer } }]
      responses:
        "200": { description: "Resolved.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }

  # ── Admin: backup ──
  /backup/destinations:
    get:
      tags: [Backup]
      operationId: backupDestinationsIndex
      summary: List backup destinations (admin)
      description: "Credentials (`config`) are NEVER returned — only {id, name, driver}."
      responses:
        "200": { description: "Destinations.", content: { application/json: { schema: { type: object, properties: { destinations: { type: array, items: { $ref: "#/components/schemas/BackupDestinationSummary" } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    post:
      tags: [Backup]
      operationId: backupDestinationsStore
      summary: Create a backup destination (admin)
      description: "Runs a reachability gate before saving. Credentials never echoed back. Throttle 20/min."
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/BackupDestinationWrite" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, properties: { destination: { $ref: "#/components/schemas/BackupDestinationSummary" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { description: "Validation failed, or the destination is unreachable (the reachability gate surfaces as a 422 on `name`)." }
        "429": { $ref: "#/components/responses/RateLimited" }
  /backup/destinations/{destination}:
    parameters: [{ name: destination, in: path, required: true, schema: { type: integer } }]
    put:
      tags: [Backup]
      operationId: backupDestinationsUpdate
      summary: Update a backup destination (admin)
      description: "Blank secret/password fields keep the stored value. Runs the reachability gate. Throttle 20/min."
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/BackupDestinationWrite" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, properties: { destination: { $ref: "#/components/schemas/BackupDestinationSummary" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "Validation failed, or the destination is unreachable." }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Backup]
      operationId: backupDestinationsDestroy
      summary: Delete a backup destination (admin)
      description: "Throttle 20/min."
      responses:
        "204": { description: "Deleted (no content)."}
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /backup/destinations/test:
    post:
      tags: [Backup]
      operationId: backupDestinationsTest
      summary: Test destination reachability (admin)
      description: "Tests a config (from the body, or an existing destination via destination_id) without saving. Throttle 20/min."
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/BackupDestinationWrite" } } } }
      responses:
        "200": { description: "Result — {ok:true} or {ok:false, detail:<error chain>}.", content: { application/json: { schema: { type: [object, "null"], properties: { ok: { type: boolean }, detail: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /backup/jobs:
    get:
      tags: [Backup]
      operationId: backupJobsIndex
      summary: List backup jobs + statistics (admin)
      description: "`passphrase` is NEVER returned."
      responses:
        "200": { description: "Jobs.", content: { application/json: { schema: { type: object, properties: { jobs: { type: array, items: { $ref: "#/components/schemas/BackupJobSummary" } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    post:
      tags: [Backup]
      operationId: backupJobsStore
      summary: Create a backup job (admin)
      description: "422 only when encrypt=true and no passphrase is available (job passphrase blank + no BACKUP_PASSPHRASE env). DB-dump encryption is recommended (cleartext PII) but not forced. Throttle 20/min."
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/BackupJobWrite" } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, properties: { job: { $ref: "#/components/schemas/BackupJobSummary" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { description: "Validation failed, or encrypt=true without an available passphrase (job passphrase blank and no BACKUP_PASSPHRASE env)." }
        "429": { $ref: "#/components/responses/RateLimited" }
  /backup/jobs/{job}:
    parameters: [{ name: job, in: path, required: true, schema: { type: integer } }]
    put:
      tags: [Backup]
      operationId: backupJobsUpdate
      summary: Update a backup job (admin)
      description: "Blank passphrase keeps the stored value. Throttle 20/min."
      requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/BackupJobWrite" } } } }
      responses:
        "200": { description: "Updated.", content: { application/json: { schema: { type: object, properties: { job: { $ref: "#/components/schemas/BackupJobSummary" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
    delete:
      tags: [Backup]
      operationId: backupJobsDestroy
      summary: Delete a backup job (admin)
      description: "Throttle 20/min."
      responses:
        "204": { description: "Deleted (no content)."}
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /backup/jobs/{job}/run:
    parameters: [{ name: job, in: path, required: true, schema: { type: integer } }]
    post:
      tags: [Backup]
      operationId: backupJobsRun
      summary: Trigger a backup run now (admin)
      description: "Dispatches the job to the queue. Throttle 10/min."
      responses:
        "200": { description: "Dispatched.", content: { application/json: { schema: { $ref: "#/components/schemas/OkResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /backup/runs:
    get:
      tags: [Backup]
      operationId: backupRunsIndex
      summary: List recent backup runs (admin)
      description: "The 20 most recent runs (reaps stale running rows first)."
      responses:
        "200": { description: "Runs.", content: { application/json: { schema: { type: object, properties: { runs: { type: array, items: { $ref: "#/components/schemas/BackupRunSummary" } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
  /backup/runs/{run}/download:
    parameters:
      - { name: run, in: path, required: true, schema: { type: integer } }
      - { name: source, in: query, required: true, schema: { type: string, enum: [database, invoices, avatars] }, description: "Which source's archive in the run's batch to download." }
    get:
      tags: [Backup]
      operationId: backupRunsDownload
      summary: Download one source's archive from a run's batch (admin)
      description: "Streams the raw archive bytes for the given source (may be encrypted)."
      responses:
        "200": { description: "Archive bytes.", content: { application/octet-stream: { schema: { type: string, format: binary } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { description: "Not found — run missing, not successful, no such source archive, or the destination/file is gone." }
  /backup/runs/{run}/verify:
    parameters: [{ name: run, in: path, required: true, schema: { type: integer } }]
    post:
      tags: [Backup]
      operationId: backupRunsVerify
      summary: Verify one source's archive integrity (admin)
      description: "Read-only integrity check of one source's archive in the batch. Throttle 10/min."
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [source], properties: { source: { type: string, enum: [database, invoices, avatars] }, passphrase: { type: [string, "null"], maxLength: 255, description: "Required for encrypted (.enc) archives." } } } } } }
      responses:
        "200": { description: "Result.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean }, message: { type: string }, verifiedHuman: { type: [string, "null"] } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { description: "Run missing or no such source archive." }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /backup/runs/{run}/restore:
    parameters: [{ name: run, in: path, required: true, schema: { type: integer } }]
    post:
      tags: [Backup]
      operationId: backupRunsRestore
      summary: Restore a blob source onto live data (admin)
      description: "Restores a blob source (invoices/avatars) in-place from its mirror back onto the live disk (additive overwrite, decrypting per-file when encrypted). DESTRUCTIVE. The database is NOT restorable via API — download the dump and run `php artisan backup:restore-db`. Throttle 10/min."
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [source], properties: { source: { type: string, enum: [invoices, avatars] } } } } } }
      responses:
        "200": { description: "Restored.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean }, files: { type: integer, description: "Number of files written." } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { description: "Run missing or not a successful batch." }
        "422": { description: "Restore failed, or an invalid/non-blob source (validation)." }
        "429": { $ref: "#/components/responses/RateLimited" }
  /backup/runs/{run}/cancel:
    parameters: [{ name: run, in: path, required: true, schema: { type: integer } }]
    post:
      tags: [Backup]
      operationId: backupRunsCancel
      summary: Cancel a running backup (admin)
      description: "First call requests a graceful cancel; a second (while pending) force-finalises. Throttle 20/min."
      responses:
        "200": { description: "Result.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean }, forced: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /backup/runs/{run}/decrypt:
    parameters: [{ name: run, in: path, required: true, schema: { type: integer } }]
    post:
      tags: [Backup]
      operationId: backupRunsDecrypt
      summary: Stream a decrypted archive (admin/CLI)
      description: "Fetches an encrypted (.enc) archive for the given source, decrypts it with the passphrase, and streams the plaintext archive. Nothing is written to live data. Throttle 10/min."
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [passphrase, source], properties: { source: { type: string, enum: [database, invoices, avatars] }, passphrase: { type: string, maxLength: 255 } } } } } }
      responses:
        "200": { description: "Decrypted bytes.", content: { application/octet-stream: { schema: { type: string, format: binary } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { description: "Run missing, not a successful .enc archive, or the file is gone." }
        "422": { description: "Wrong passphrase or corrupt archive, or a missing `passphrase` (validation)." }
        "429": { $ref: "#/components/responses/RateLimited" }


  # --------------------------------------------------------------------------
  # Public account lifecycle (no auth) — mirrors the web Fortify pipeline.
  # --------------------------------------------------------------------------
  /auth/forgot-password:
    post:
      tags: [Auth]
      operationId: authForgotPassword
      summary: Request a password-reset link (public)
      description: >
        Sends a password-reset email via the Fortify broker. Always responds with a
        generic 200 regardless of whether the email exists — the endpoint cannot be
        used to enumerate accounts. Mirrors the web forgot-password POST.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email }
      responses:
        "200":
          description: Generic acknowledgement (sent iff the email exists).
          content:
            application/json:
              schema: { type: object, properties: { status: { type: string, example: reset-link-sent } } }
        "422": { $ref: '#/components/responses/ValidationError' }
        "429": { $ref: '#/components/responses/RateLimited' }
  /auth/reset-password:
    post:
      tags: [Auth]
      operationId: authResetPassword
      summary: Consume a password-reset token (public)
      description: >
        Resets the password using an emailed reset token. Reuses the Fortify
        ResetUserPassword action, so it applies the same password rules and acts as a
        kill switch (revokes every device token + persisted session). Returns 200 on
        success. Every non-success case (unknown email, bad/expired token, weak
        password) collapses to ONE neutral 422 `{status:"reset-failed", message}`
        (v1.562.0) — the response no longer signals account existence, so do NOT
        branch on distinct broker error codes. Mirrors the web reset-password POST.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token, email, password, password_confirmation]
              properties:
                token: { type: string }
                email: { type: string, format: email }
                password: { type: string, minLength: 12 }
                password_confirmation: { type: string }
      responses:
        "200":
          description: Password reset.
          content:
            application/json:
              schema: { type: object, properties: { status: { type: string, example: password-reset } } }
        "422":
          description: >
            Any failure — unknown email, invalid/expired token, or a password that
            failed the rules. The body is always the same neutral shape (no
            account-existence oracle).
          content:
            application/json:
              schema: { type: object, properties: { status: { type: string, example: reset-failed }, message: { type: string } } }
        "429": { $ref: '#/components/responses/RateLimited' }
  /auth/register:
    post:
      tags: [Auth]
      operationId: authRegister
      summary: Self-register a new account (public, gated)
      description: >
        Creates a new account via the Fortify CreateNewUser action. Gated by the
        workspace `allow_registration` flag — 403 when self-registration is disabled.
        The privileged `role` is never taken from input (always `user`). Because email
        verification is required, no bearer is minted until the address is verified:
        responds {status: "verify-email"} and sends the verification email. Mirrors
        the web register POST.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, email, password, password_confirmation]
              properties:
                name: { type: string, maxLength: 255 }
                email: { type: string, format: email }
                password: { type: string, minLength: 12 }
                password_confirmation: { type: string }
                device_name: { type: [string, "null"], maxLength: 64 }
      responses:
        "201":
          description: >
            Created. When email verification is pending, {status:"verify-email"} (no
            token). If verification is ever disabled, returns {token, user} instead.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: verify-email }
                  token: { type: string }
                  user: { $ref: '#/components/schemas/MeUser' }
        "403":
          description: Self-registration is disabled workspace-wide.
        "422": { $ref: '#/components/responses/ValidationError' }
        "429": { $ref: '#/components/responses/RateLimited' }

  # --------------------------------------------------------------------------
  # Public file-share consumption (no auth) — the share token in the path is the
  # credential. Same controller as the web /file-share routes; a password-gated
  # share issues a stateless HMAC grant on unlock, carried on manifest/raw.
  # --------------------------------------------------------------------------
  /invite/{invite}/{token}:
    get:
      tags: [Users]
      operationId: inviteShow
      summary: Check an invite / reset link (public)
      description: >
        Reports whether the (hashed, single-use, expiring) invite token is still
        valid, plus the target email. JSON only — never a redirect.
      security: []
      parameters:
        - { name: invite, in: path, required: true, schema: { type: integer } }
        - { name: token, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: Valid link.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid: { type: boolean, example: true }
                  email: { type: string, format: email }
                  expiresAt: { type: [string, "null"], format: date-time }
        "404": { description: "Invalid, consumed, or expired link (valid:false)." }
        "429": { $ref: '#/components/responses/RateLimited' }
    post:
      tags: [Users]
      operationId: inviteConsume
      summary: Consume an invite / reset link — set password, get a bearer (public)
      description: >
        Sets the target user's password (constant-time token check + single-use +
        expiry) and mints a device-scoped bearer token (rather than a session login).
        Consuming the link is a kill switch (v1.562.0): it REVOKES every pre-existing
        device token + web session for the account BEFORE minting the fresh bearer —
        a client holding an older token must re-authenticate.
      security: []
      parameters:
        - { name: invite, in: path, required: true, schema: { type: integer } }
        - { name: token, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [password, password_confirmation]
              properties:
                password: { type: string, minLength: 12 }
                password_confirmation: { type: string }
                device_name: { type: [string, "null"], maxLength: 64 }
      responses:
        "200":
          description: Password set — bearer + user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
                  user: { $ref: '#/components/schemas/MeUser' }
        "404": { description: "Invalid, consumed, or expired link."}
        "422": { $ref: '#/components/responses/ValidationError' }
        "429": { $ref: '#/components/responses/RateLimited' }

  # --------------------------------------------------------------------------
  # CardDAV Apple configuration profile download (device auth + module:contacts).
  # --------------------------------------------------------------------------
  /admin/registration:
    get:
      tags: [Users]
      operationId: adminRegistrationShow
      summary: Read the workspace self-registration toggle (admin)
      responses:
        "200":
          description: Current toggle state.
          content:
            application/json:
              schema: { type: object, properties: { allow_registration: { type: boolean } } }
        "401": { $ref: '#/components/responses/Unauthorized' }
        "403": { $ref: '#/components/responses/Forbidden' }
    put:
      tags: [Users]
      operationId: adminRegistrationUpdate
      summary: Set the workspace self-registration toggle (admin)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [allow_registration]
              properties:
                allow_registration: { type: boolean }
      responses:
        "200":
          description: Updated toggle state.
          content:
            application/json:
              schema: { type: object, properties: { allow_registration: { type: boolean } } }
        "401": { $ref: '#/components/responses/Unauthorized' }
        "403": { $ref: '#/components/responses/Forbidden' }
        "422": { $ref: '#/components/responses/ValidationError' }

  # ── Security portal (admin) ──
  /admin/request-log:
    get:
      tags: [SecurityPortal]
      operationId: adminRequestLog
      summary: List HTTP request-trail rows (admin)
      description: "Paginated, filterable verbose request log. Metadata only. Admin-gated. Throttle 120/min."
      parameters:
        - { name: ip, in: query, schema: { type: string } }
        - { name: user_id, in: query, schema: { type: integer } }
        - { name: method, in: query, schema: { type: string, enum: [GET, POST, PUT, PATCH, DELETE] } }
        - { name: status, in: query, schema: { type: integer } }
        - { name: path, in: query, schema: { type: string }, description: "Substring match." }
        - { name: since, in: query, schema: { type: string }, description: "ISO-8601 or -24h/-7d." }
        - { name: page, in: query, schema: { type: integer, default: 1 } }
        - { name: per_page, in: query, schema: { type: integer, default: 50, maximum: 100 } }
      responses:
        "200": { description: "Rows.", content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: "#/components/schemas/RequestLogEntry" } }, meta: { type: object, properties: { total: { type: integer }, current_page: { type: integer }, last_page: { type: integer } } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /admin/request-log/export:
    get:
      tags: [SecurityPortal]
      operationId: adminRequestLogExport
      summary: Export the request log (admin, CSV/JSON)
      description: "Streamed download, same filters as the index. Throttle 10/min."
      parameters:
        - { name: export, in: query, schema: { type: string, enum: [csv, json], default: csv } }
        - { name: ip, in: query, schema: { type: string } }
        - { name: user_id, in: query, schema: { type: integer } }
        - { name: method, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { type: integer } }
        - { name: path, in: query, schema: { type: string } }
        - { name: since, in: query, schema: { type: string } }
      responses:
        "200": { description: "Stream.", content: { text/csv: { schema: { type: string, format: binary } }, application/json: { schema: { type: string, format: binary } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /admin/blocked-ips:
    get:
      tags: [SecurityPortal]
      operationId: adminBlockedIpsIndex
      summary: List blocked IPs/CIDRs (admin)
      responses:
        "200": { description: "Block-list.", content: { application/json: { schema: { type: object, properties: { blocks: { type: array, items: { $ref: "#/components/schemas/BlockedIp" } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    post:
      tags: [SecurityPortal]
      operationId: adminBlockIp
      summary: Add an IP/CIDR to the block-list (admin)
      description: "Throttle 60/min. 422 on malformed CIDR or duplicate."
      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [cidr], properties: { cidr: { type: string, maxLength: 64, example: 203.0.113.0/24 }, reason: { type: [string, "null"] } } } } } }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { type: object, required: [id], properties: { id: { type: integer } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "422": { $ref: "#/components/responses/ValidationError" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /admin/blocked-ips/{blockedIp}:
    delete:
      tags: [SecurityPortal]
      operationId: adminUnblockIp
      summary: Remove an IP/CIDR from the block-list (admin)
      description: "Throttle 60/min."
      parameters:
        - { name: blockedIp, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: "Removed.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /admin/users/{user}/block:
    post:
      tags: [SecurityPortal]
      operationId: adminBlockUser
      summary: Block a user (admin)
      description: "Signs the user out and prevents sign-in. Throttle 60/min."
      parameters:
        - { name: user, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: "Blocked.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean }, blocked_at: { type: string, format: date-time } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "422": { description: "You cannot block yourself." }
        "429": { $ref: "#/components/responses/RateLimited" }
  /admin/users/{user}/unblock:
    post:
      tags: [SecurityPortal]
      operationId: adminUnblockUser
      summary: Unblock a user (admin)
      description: "Throttle 60/min."
      parameters:
        - { name: user, in: path, required: true, schema: { type: integer } }
      responses:
        "200": { description: "Unblocked.", content: { application/json: { schema: { type: object, properties: { ok: { type: boolean } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /admin/sessions:
    get:
      tags: [SecurityPortal]
      operationId: adminSessions
      summary: Cross-user session/device overview (admin)
      description: "Active web sessions + device tokens across all users. Throttle 60/min."
      responses:
        "200": { description: "Overview.", content: { application/json: { schema: { $ref: "#/components/schemas/SessionsOverview" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "429": { $ref: "#/components/responses/RateLimited" }