feat: scope notification to permission actions

packages/types/src/freight/notifications.ts

@@ -90,13 +90,16 @@ export interface NotificationRecipients {
   companyProfileId?: string;
   /** Backoffice: all current employees of this organization. */
   organizationId?: string;
-  /** Backoffice: every current employee across all organizations. */
-  allBackoffice?: boolean;
   /**
    * Backoffice: current employees (any org) who hold ANY of these permission
-   * keys — e.g. notify only marketing, not every employee. Super/org admins
-   * are not implicitly included; add `allBackoffice`/explicit userIds too if
-   * admins should also see it.
+   * keys. Resolution mirrors the request-time guard `hasFreightPermission` —
+   * IAM role grants, direct position grants, position TYPE grants, delegated
+   * positions, and the `super_admin` bypass. `organization_admin` is NOT
+   * implicitly included (it only bypasses approval steps, not permission
+   * checks); grant it a key explicitly if it should be notified.
+   *
+   * Prefer the dedicated `<module>:get_notification` keys over reusing a domain
+   * key: they let ops tune who gets pinged without touching who has access.
    */
   permissionKeys?: string[];
 }