@vtex/faststore-plugin-buyer-portal 2.0.7 → 2.0.9

package/specs/001-suma-phase-2/tasks.md

@@ -0,0 +1,253 @@
+# Tasks: SUMA Phase 2 — Contract Listing, Switching & Management
+
+**Input**: Design documents from `specs/001-suma-phase-2/`
+
+**Prerequisites**: plan.md ✅ | spec.md ✅ | research.md ✅ | data-model.md ✅ | contracts/ ✅ | quickstart.md ✅
+
+**Tests**: Minimum unit + integration tests required by Constitution (Principle IV) for new hooks and API services. No TDD was explicitly requested — tests are in the Polish phase.
+
+**Organization**: Tasks grouped by user story (US1–US7) in priority order. Each phase is independently testable.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no shared dependencies)
+- **[Story]**: Which user story this task belongs to (US1–US7)
+- Paths are relative to repository root
+
+---
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Register new routes and pages so the plugin recognizes them before any implementation begins.
+
+- [ ] T001 Register `contracts` page (`path: /pvt/organization-account/contracts/[orgUnitId]`) and `contract-information` page (`path: /pvt/organization-account/contract-information/[orgUnitId]/[contractId]`) in `plugin.config.js`
+- [ ] T002 Add `contracts` and `contractInformation` route builder functions to `src/features/shared/utils/buyerPortalRoutes.ts` following the existing `replaceParams` pattern
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core type extensions, feature flag wiring, BFF client methods, and service wrappers that ALL user story phases depend on.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete.
+
+- [ ] T003 Extend `ContractData` type with `isDefault?: boolean` in `src/features/contracts/types/ContractData.ts` (optional field for backward compat with existing code)
+- [ ] T004 [P] Add `suma?: boolean` to the `FeatureFlags` type in `src/features/shared/components/BuyerPortalProvider/BuyerPortalProvider.tsx`; add `suma: normalized["suma"] ?? false` to `getBuyerPortalFeatureFlags()` in `src/features/shared/services/feature-flags/get-feature-flags.service.ts` (no snake_case conversion needed — key matches property name)
+- [ ] T005 [P] Add four new methods to `src/features/contracts/clients/ContractsClient.ts`: `listAttachedContracts(orgUnitId, cookie, details?)`, `listAvailableContracts(orgUnitId, cookie)`, `addContracts(orgUnitId, ids, cookie)`, `removeContract(orgUnitId, contractId, cookie)` — see `specs/001-suma-phase-2/contracts/contracts-api.md` for confirmed v1.0.2 endpoint signatures. Note: `activateContract` and `setDefaultContract` endpoints are TBD (not yet in BFF v1.0.2)
+- [ ] T006 [P] Create `src/features/contracts/services/activate-contract.service.ts` wrapping `contractsClient.activateContract` with `withClientErrorBoundary` (same pattern as `update-contract-status.service.ts`)
+- [ ] T007 [P] Create `src/features/contracts/services/add-contracts.service.ts`, `src/features/contracts/services/remove-contracts.service.ts`, and `src/features/contracts/services/set-default-contract.service.ts` — each wrapping the corresponding client method with `withClientErrorBoundary`
+- [ ] T008 Update `src/features/contracts/services/index.ts` to export all new services; update `src/pages/home.tsx` loader to redirect to `buyerPortalRoutes.contracts({ orgUnitId })` when `featureFlags?.suma` is true, preserving the existing `orgUnitDetails` redirect when false
+
+**Checkpoint**: Foundation complete — all user story phases can begin in parallel.
+
+---
+
+## Phase 3: User Story 1 — View and Switch Active Contract (Priority: P1) 🎯 MVP
+
+**Goal**: A buyer opens the Contract Listing page (new account homepage when flag is on), sees all org unit contracts with the default visually highlighted, clicks a contract, and lands on the Profile page (Contract Information) operating under the selected contract. BFF switch errors show a toast on the listing.
+
+**Independent Test**: Visit `/pvt/organization-account` with flag ON → verify redirect to `/contracts/{orgUnitId}`; click a contract → verify navigation to `/profile/{orgUnitId}/{contractId}`; simulate BFF switch failure → verify error feedback on listing page.
+
+- [ ] T009 [US1] Create `src/features/contracts/hooks/useSwitchContract.ts` — wraps `changeContractToken`, exposes `{ switchContract, loading, error }`; on success navigates to `buyerPortalRoutes.profileDetails(...)`, on error surfaces error toast on listing
+- [ ] T010 [P] [US1] Create `ContractListItem.tsx` — default star badge when `isDefault === true`, loading overlay during switch; plain click calls `useSwitchContract`
+- [ ] T011 [US1] Create `ContractListingLayout.tsx` — listing page with org sidebar, add/remove/set-default admin actions, BroadcastChannel listener
+- [ ] T012 [US1] Create `src/pages/contracts.tsx` — Contract Listing page; loader fetches attached contracts + org unit data
+- [ ] T013 [P] [US1] *(Optional)* `ContractInformationLayout` — SUMA-specific contract detail layout at `/contract-information`; **switch destination is Profile** (`src/pages/profile.tsx`)
+- [ ] T014 [US1] Switch flow lands on Profile via `buyerPortalRoutes.profileDetails` — no separate contract-information navigation on row click
+
+**Checkpoint**: US1 complete — buyers can switch their active contract end-to-end. MVP deliverable.
+
+---
+
+## Phase 4: User Story 2 — Multi-Select with Keyboard Shortcuts (Priority: P2)
+
+**Goal**: A buyer on the Contract Listing page can select multiple contracts using Cmd+A (select all), Cmd+Click (toggle individual), and Shift+Click (range selection) without triggering navigation, enabling bulk admin actions in later phases.
+
+**Independent Test**: Visit Contract Listing; press Cmd+A → all contracts highlighted; Cmd+Click toggles individual without navigating; Shift+Click selects a contiguous range.
+
+- [ ] T015 [US2] Create `src/features/contracts/hooks/useContractSelection.ts` — manages `selectedIds: Set<string>` and `lastSelectedIndex: number`; exposes `isSelected(id)`, `handleSelectAll(allIds)`, `handleModifierClick(id)`, `handleShiftClick(id, allIds)`, `clearSelection()`; uses `event.metaKey || event.ctrlKey` for cross-platform Cmd/Ctrl support
+- [ ] T016 [P] [US2] Create `src/features/contracts/components/ContractSelectionList/ContractSelectionList.tsx` — renders the full contracts list as a selectable list; attaches `onKeyDown` for Cmd+A; passes `handleModifierClick` and `handleShiftClick` to each `ContractListItem`; shows bulk action toolbar (contract count + action buttons) when `selectedIds.size > 0`
+- [ ] T017 [US2] Integrate `useContractSelection` and `ContractSelectionList` into `src/features/contracts/layouts/ContractListingLayout/ContractListingLayout.tsx` — replace plain list with `ContractSelectionList`; bulk toolbar appears when selection is non-empty
+
+**Checkpoint**: US2 complete — multi-select UI is functional for all subsequent admin actions.
+
+---
+
+## Phase 5: User Story 3 — Admin: Add Contracts (Priority: P2)
+
+**Goal**: An admin can open an add-contracts drawer, select one, multiple, or all available contracts (with optional child-unit propagation), confirm, and see the new contracts in the listing.
+
+**Independent Test**: As admin, click "Add contracts" → drawer opens with available contracts; select one and confirm → contract appears in listing; toggle "Apply to children" and confirm → child units also show the contract.
+
+- [ ] T018 [US3] Create `src/features/contracts/hooks/useAddContracts.ts` — wraps `addContractsService`; on success triggers contract list refetch (invalidate query or call `router.replace(router.asPath)`)
+- [ ] T019 [US3] Create `src/features/contracts/components/AddContractsDrawer/AddContractsDrawer.tsx` — drawer component using `@faststore/ui` Drawer or Modal pattern; fetches available contracts not yet in the unit; supports individual/multiple selection and "Add all" shortcut; includes propagate-to-children toggle; confirm calls `useAddContracts`; cancel closes without changes
+- [ ] T020 [US3] Wire `AddContractsDrawer` into `src/features/contracts/layouts/ContractListingLayout/ContractListingLayout.tsx` — show "Add contracts" button for admin users only (gate on user role from `currentUser`); open drawer on click; refresh contract list on successful addition
+
+**Checkpoint**: US3 complete — admins can add contracts to the org unit.
+
+---
+
+## Phase 6: User Story 4 — Admin: Remove Contracts (Priority: P2)
+
+**Goal**: An admin can remove individual or multiple selected contracts (bulk). The remove option is hidden when only 1 contract remains. The action is blocked if it would leave 0 contracts.
+
+**Independent Test**: With 2+ contracts, select one and remove → no longer in listing; with 1 contract → remove option invisible; attempt to remove all → UI blocks with message.
+
+- [ ] T021 [US4] Create `src/features/contracts/hooks/useRemoveContracts.ts` — wraps `removeContractsService`; on success triggers list refetch and clears selection
+- [ ] T022 [US4] Create `src/features/contracts/components/RemoveContractsDrawer/RemoveContractsDrawer.tsx` — confirmation drawer; lists contracts to be removed; shows warning if action would leave fewer than 1 (guard before calling service); includes propagate-to-children toggle; confirm calls `useRemoveContracts`
+- [ ] T023 [US4] Wire `RemoveContractsDrawer` into `src/features/contracts/layouts/ContractListingLayout/ContractListingLayout.tsx` — hide "Remove" button entirely when `contracts.length === 1`; show in bulk action toolbar when `selectedIds.size > 0` and `contracts.length > 1`; guard: disable confirm if `contracts.length - selectedIds.size < 1`
+
+**Checkpoint**: US4 complete — admins can safely remove contracts with appropriate guards.
+
+---
+
+## Phase 7: User Story 5 — Admin: Set Default Contract (Priority: P2)
+
+**Goal**: An admin can mark any contract as the default from the listing. The default contract gains a visual indicator; the previous default loses it.
+
+**Independent Test**: As admin, trigger "Set as default" on a non-default contract → default badge moves to that contract; re-trigger on original → badge moves back.
+
+- [ ] T024 [US5] Create `src/features/contracts/hooks/useSetDefaultContract.ts` — wraps `setDefaultContractService`; on success optimistically updates `isDefault` in local contract list state (or triggers refetch)
+- [ ] T025 [P] [US5] Create `src/features/contracts/components/SetDefaultContractAction/SetDefaultContractAction.tsx` — a `DropdownItem` (admin-only) rendered inside each `ContractListItem`'s action dropdown; hidden on the current default contract; calls `useSetDefaultContract` on click
+- [ ] T026 [US5] Integrate `SetDefaultContractAction` into `src/features/contracts/components/ContractListItem/ContractListItem.tsx` — add admin-gated action dropdown with `SetDefaultContractAction`; ensure `isDefault` prop drives the visual badge reactively
+
+**Checkpoint**: US5 complete — admins can manage the default contract designation.
+
+---
+
+## Phase 8: User Story 6 — Navigation: Org Unit Hierarchy (Priority: P3)
+
+**Goal**: Users can navigate up to parent org units via the Org Unit selector in the Contract Listing, and down to child org units via the Org Units page.
+
+**Independent Test**: In a child unit's Contract Listing, use breadcrumb/selector to navigate to parent → URL changes to parent's `/contracts/{parentOrgUnitId}`; from Org Units page, click child → navigates to child's Contract Listing.
+
+- [ ] T027 [US6] Integrate `OrgUnitBreadcrumb` (from `src/features/org-units/components/OrgUnitBreadcrumb/`) into `src/features/contracts/layouts/ContractListingLayout/ContractListingLayout.tsx` — pass `orgUnit` and `currentOrgUnit` from page loader data; breadcrumb links use `buyerPortalRoutes.contracts({ orgUnitId })` for each ancestor
+- [ ] T028 [US6] Verify `src/pages/org-units.tsx` and its layout — ensure the "navigate to child unit" action links to `buyerPortalRoutes.contracts({ orgUnitId: childId })` when `enableSumaPhase2` is active; add feature-flag-conditional navigation so flag-off behavior (linking to `orgUnitDetails`) is preserved
+
+**Checkpoint**: US6 complete — full org unit hierarchy navigation functional.
+
+---
+
+## Phase 9: User Story 7 — Cross-Tab Contract State Sync (Priority: P3)
+
+**Goal**: When the user activates a contract in Tab A, Tab B automatically refreshes to reflect the new active contract within 2 seconds.
+
+**Independent Test**: Open Contract Listing in two tabs; activate a contract in Tab A; within 2 seconds, Tab B reloads and shows the updated active contract without manual refresh.
+
+- [ ] T029 [US7] Create `src/features/contracts/hooks/useCrossTabContractSync.ts` — on mount, opens a `BroadcastChannel('buyer-portal-active-contract')`; listens for `{ type: 'CONTRACT_ACTIVATED', contractId, orgUnitId }` messages and calls `router.replace(router.asPath)` to refresh; exposes `broadcastActivation(contractId, orgUnitId)` to emit after a successful activation; closes channel on unmount
+- [ ] T030 [US7] Integrate `useCrossTabContractSync` into `src/features/contracts/layouts/ContractListingLayout/ContractListingLayout.tsx` — mount the hook; call `broadcastActivation` inside `useActivateContract`'s onSuccess callback
+
+**Checkpoint**: US7 complete — cross-tab contract state is consistent.
+
+---
+
+## Phase 10: Polish & Cross-Cutting Concerns
+
+**Purpose**: Minimum test coverage required by Constitution Principle IV, final validation.
+
+- [ ] T031 [P] Add unit test for `useActivateContract` in `src/features/contracts/hooks/__tests__/useActivateContract.test.ts` — cover: success path (calls service + navigates), error path (surfaces error without navigating), loading state during call
+- [ ] T032 [P] Add unit test for `useContractSelection` in `src/features/contracts/hooks/__tests__/useContractSelection.test.ts` — cover: `handleSelectAll`, `handleModifierClick` toggle, `handleShiftClick` range, `clearSelection`, empty state
+- [ ] T033 [P] Add integration test for `activate-contract.service.ts` happy path in `src/features/contracts/services/__tests__/activate-contract.service.test.ts` — mock BFF response, assert correct endpoint and headers called
+- [ ] T034 Run `make check` (lint + typecheck + test) from repo root and fix all failures before opening PR
+- [ ] T035 Run quickstart.md validation checklist (`specs/001-suma-phase-2/quickstart.md`) manually against `b2bfaststoredev.store` — mark all 18 items complete before requesting review
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies — start immediately
+- **Foundational (Phase 2)**: Requires Phase 1 — **BLOCKS all user stories**
+- **US1–US5 (Phases 3–7)**: All require Foundational; can run in parallel across developers
+- **US6 (Phase 8)**: Requires Phase 3 (US1) — Contract Listing must exist before adding breadcrumb
+- **US7 (Phase 9)**: Requires Phase 3 (US1) — hook integrates into Contract Listing Layout
+- **Polish (Phase 10)**: Requires all desired user stories complete
+
+### User Story Dependencies
+
+| Story    | Depends on                             | Can run in parallel with |
+| -------- | -------------------------------------- | ------------------------ |
+| US1 (P1) | Foundational                           | US2, US3, US4, US5       |
+| US2 (P2) | Foundational                           | US1, US3, US4, US5       |
+| US3 (P2) | Foundational                           | US1, US2, US4, US5       |
+| US4 (P2) | Foundational                           | US1, US2, US3, US5       |
+| US5 (P2) | Foundational                           | US1, US2, US3, US4       |
+| US6 (P3) | US1 (ContractListingLayout must exist) | US7                      |
+| US7 (P3) | US1 (ContractListingLayout must exist) | US6                      |
+
+### Within Each User Story
+
+- Hooks → Components → Layout integration (strict order within a story)
+- Exception: [P]-marked tasks within a story can run in parallel
+
+---
+
+## Parallel Example: Foundational Phase (Phase 2)
+
+```
+Start T003 (type extension — no deps)
+
+Then in parallel:
+  T004: Feature flag wiring (BuyerPortalProvider.tsx + withAuthLoader.ts)
+  T005: ContractsClient.ts new methods (4 BFF methods)
+  T006: activate-contract.service.ts
+  T007: add/remove/set-default services (3 files)
+
+Then:
+  T008: index.ts exports + home.tsx redirect logic (depends on T005, T006, T007)
+```
+
+## Parallel Example: User Story 1 (Phase 3)
+
+```
+Start T009 (useActivateContract hook — no deps in this phase)
+
+In parallel with T009:
+  T010: ContractListItem component (no deps in this phase)
+  T013: ContractInformationLayout (no deps on T009–T012)
+
+Then:
+  T011: ContractListingLayout (depends on T009, T010)
+
+Then:
+  T012: contracts.tsx page (depends on T011)
+  T014: contract-information.tsx page (depends on T013)
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup (T001–T002)
+2. Complete Phase 2: Foundational (T003–T008) — **critical blocker**
+3. Complete Phase 3: US1 (T009–T014)
+4. **STOP and VALIDATE**: Run quickstart.md US-1 section against `b2bfaststoredev.store`
+5. Demo to stakeholders — flag-off regression test passes
+
+### Incremental Delivery
+
+1. Setup + Foundational → Foundation shipped
+2. US1 → Contract Listing + Switch (MVP — core SUMA Phase 2 value)
+3. US2 → Multi-select (enables bulk admin workflows)
+4. US3 + US4 + US5 → Full admin management (add/remove/default — can be one PR)
+5. US6 + US7 → Navigation hierarchy + cross-tab sync (polish for power users)
+
+### Parallel Team Strategy (3 developers after Foundational)
+
+- **Dev A**: US1 (P1 core) → US6 (P3 nav hierarchy)
+- **Dev B**: US2 (P2 multi-select) → US3 (P2 add contracts)
+- **Dev C**: US4 (P2 remove) → US5 (P2 set default) → US7 (P3 cross-tab)
+
+---
+
+## Notes
+
+- `[P]` tasks touch different files — safe to parallelise
+- `[Story]` label maps each task to its user story for JIRA epic/story linking
+- Each phase checkpoint is a valid demo/deploy milestone
+- `make check` must exit 0 before any PR — run it at each checkpoint
+- Flag-off regression (feature flag disabled → original navigation) must pass at every checkpoint
+- Total: **35 tasks** across 10 phases

package/specs/suma-add-contracts.md

@@ -0,0 +1,224 @@
+# SUMA: Add Contracts to Organizational Unit
+
+> **Status**: Done
+> **Created**: 2026-06-22
+
+## 1. Business Context
+
+### Problem Statement
+
+Admins managing a Buyer Organization need to expand the pool of contracts available to their Organizational Unit (OU). Contracts exist at the root unit scope; they are not automatically available to every sub-unit. Without an "Add Contracts" UI, admins have no self-service way to attach relevant contracts to their OU, blocking buyers from switching to contracts their unit should have access to.
+
+### Goals
+
+- Users can add one or more contracts from the available pool to their OU in under 5 seconds.
+- The new contracts appear immediately in the Contract Listing without a full page reload.
+
+### User Stories
+
+#### US-1: Add Available Contracts to an Organizational Unit
+
+- **Story**: As a user, I want to select contracts from the available pool and add them to my Organizational Unit, so that buyers in that unit can switch to those contracts.
+- **Acceptance Criteria**:
+  - **Given** an admin is on the Contract Listing page, **when** they click "Add contracts", **then** a drawer opens showing all contracts available to the OU (not yet attached).
+  - **Given** the drawer is open, **when** the admin selects one or more contracts and clicks "Add", **then** the selected contracts are added to the OU and appear in the Contract Listing.
+  - **Given** no contracts are selected, **when** the drawer footer is rendered, **then** the "Add" button is disabled.
+  - **Given** the addition is in progress, **when** the BFF call is pending, **then** the drawer shows a loading state and all interactions are disabled.
+  - **Given** the BFF call fails, **when** the drawer returns from the loading state, **then** an error toast is shown on the listing page and the drawer closes without modifying the list.
+
+#### US-2: Search and Paginate Available Contracts
+
+- **Story**: As a user, I want to search and paginate through the available contracts list, so that I can efficiently find specific contracts when the available pool is large.
+- **Acceptance Criteria**:
+  - **Given** the drawer is open, **when** the admin types in the search field, **then** the list filters to contracts whose names contain the query (case-insensitive) and the page resets to 1.
+  - **Given** the filtered list has more than 25 results, **when** the drawer renders, **then** pagination controls appear showing the current range and allowing navigation.
+  - **Given** the admin presses Cmd+A or Ctrl+A while the search field is not focused, **when** the drawer is open, **then** all contracts in the filtered list are selected.
+  - **Given** the admin Shift+Clicks a contract, **when** a previous contract was already clicked, **then** all contracts between the two (in displayed order) are selected as a range.
+
+### Key Scenarios
+
+| Scenario | Pre-conditions | Steps | Expected Result |
+|---|---|---|---|
+| Happy path — add single contract | User on Contract Listing; OU has available contracts | Open drawer → select 1 contract → click Add | Contract added via BFF; drawer closes; contract appears in listing; success toast shown |
+| Happy path — add all available | User on Contract Listing; multiple available contracts | Open drawer → click "Select all" → click Add | All available contracts added; listing refreshes |
+| BFF error | BFF returns 5xx | Open drawer → select contract → confirm | Drawer closes with error state; error toast shown on listing; listing unchanged |
+| Empty available pool | All root-unit contracts already attached | Open drawer | Drawer shows empty state: "No contracts available to add" |
+| Search with no results | Available contracts exist | Type a query matching nothing | Empty state message shown; "Select all" shows "(0)"; Add button disabled |
+| Drawer closed mid-flow | Admin has selected contracts | Click backdrop or close button | Drawer closes; no BFF call made; listing unchanged |
+
+### Functional Requirements
+
+- **FR-1**: The drawer MUST load the list of available contracts (not yet attached) from the BFF when opened.
+- **FR-2**: Available contracts MUST be displayed with their name; if a name is not available, fall back to the contract ID.
+- **FR-3**: The user MUST be able to select any combination of available contracts via individual click, Shift+Click (range), and Cmd+A / Ctrl+A (select all in filtered view).
+- **FR-4**: The drawer MUST include a text search that filters the list client-side by contract name.
+- **FR-5**: The list MUST paginate client-side at 25 items per page when the filtered list exceeds 25 entries.
+- **FR-6**: On confirmation, the selected IDs MUST be sent to `addContractsService`.
+- **FR-7**: While the BFF call is in progress, the drawer MUST disable all interactions and show a loading indicator on the "Add" button.
+- **FR-8**: On success, the drawer MUST close and the Contract Listing MUST refresh to include the newly added contracts.
+- **FR-9**: On BFF failure, the drawer MUST close, and an error toast MUST appear on the Contract Listing.
+
+### Non-Functional Requirements
+
+- BFF call end-to-end MUST complete within 5 seconds.
+- Loading indicator MUST appear within 500ms of clicking "Add".
+- The drawer animation MUST follow the same slide-in-from-right pattern used elsewhere in the plugin (`cubic-bezier(0.16, 1, 0.3, 1)`, 550ms).
+- The feature MUST be gated behind the `suma` feature flag — no entry point is rendered when the flag is off.
+- TypeScript strict mode: zero `any` usage, zero `tsc --noEmit` errors.
+
+### Out of Scope
+
+- Creating new contracts (contracts originate in the root unit's pool, managed outside this plugin).
+- Adding contracts to multiple OUs simultaneously from a single UI action (propagation covers the hierarchy case).
+- Editing or renaming contracts.
+- Propagating contract additions to child organizational units.
+
+---
+
+## 2. Arch Decisions
+
+### Proposed Solution
+
+A new `AddContractsDrawer` component (controlled open/close) is added under `src/features/contracts/components/AddContractsDrawer/`. A companion `useAddContracts` hook handles the mutation. Both are wired into `ContractListingLayout`, which already owns the admin-gated toolbar. The drawer fetches available contracts when it opens (lazy load) using the existing `listAvailableContractsService`.
+
+### Architecture Overview
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant ContractListingLayout
+  participant AddContractsDrawer
+  participant useAddContracts
+  participant BFF
+
+  User->>ContractListingLayout: click "Add contracts"
+  ContractListingLayout->>AddContractsDrawer: isOpen=true
+  AddContractsDrawer->>BFF: GET /units/{orgUnitId}/contracts/available
+  BFF-->>AddContractsDrawer: { contracts: AvailableContract[] }
+  User->>AddContractsDrawer: select contracts, click Add
+  AddContractsDrawer->>useAddContracts: addContracts(ids)
+  useAddContracts->>BFF: POST /units/{orgUnitId}/contracts/attached
+  BFF-->>useAddContracts: 200 OK
+  useAddContracts-->>AddContractsDrawer: success
+  AddContractsDrawer->>ContractListingLayout: onSuccess()
+  ContractListingLayout->>BFF: reload contract list
+```
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Verdict |
+|---|---|---|---|
+| Modal (full-screen overlay) instead of drawer | Familiar pattern | Inconsistent with other admin flows in the plugin (ConfirmRemoveDrawer, ContractAccountDrawer) | Rejected — drawer is prototype-validated |
+| Server-side pagination | Handles very large lists | Extra API call per page; BFF doesn't support cursor/offset on this endpoint | Rejected — client-side pagination sufficient given typical OU pool size |
+| Fetch available contracts in page loader | Data available immediately | Loads data even when admin never opens drawer; increases page load time | Rejected — lazy fetch on drawer open preferred |
+| Inline list on Contract Listing (no drawer) | Fewer interactions | Complex layout conflict with selection list; prototype uses drawer | Rejected |
+
+### Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|---|---|---|---|
+| BFF `listAvailableContracts` returns only IDs, not names | High — UI shows meaningless labels | High — confirmed by current API contract | Coordinate with BFF team to return `{ contracts: [{ id, name }] }` before implementation; fall back to ID display in interim |
+| BFF `addContracts` doesn't support `propagateToChildren` flag | Med — US-2 not deliverable | Med — v1.0.2 API contract doesn't document this param | BFF team must confirm or add the param; US-2 is blocked until confirmed |
+
+### Key Decisions
+
+#### Decision 1: Lazy-load Available Contracts on Drawer Open
+
+- **Status**: Accepted
+- **Context**: Available contracts are only needed when the admin opens the drawer, which is not guaranteed on every page visit.
+- **Decision**: Fetch `listAvailableContractsService` inside the drawer (via `useEffect` on `isOpen`) rather than in the page loader.
+- **Consequences**: Slight delay on first open (one extra BFF call); avoids loading data for every admin visiting the listing.
+
+#### Decision 2: Client-Side Search and Pagination
+
+- **Status**: Accepted
+- **Context**: `listAvailableContracts` returns the full set of available IDs at once. BFF does not support server-side filtering/pagination on this endpoint.
+- **Decision**: Hold the full available list in component state; filter and paginate with `useMemo` (25 items per page), matching the prototype implementation.
+- **Consequences**: Works well for typical OU pool sizes (< 100 contracts). If future pool sizes grow into the thousands, client-side filtering may need revisiting.
+
+#### Decision 3: Contract Name Resolution Dependency on BFF Upgrade
+
+- **Status**: Pending BFF team confirmation
+- **Context**: The current BFF `listAvailableContracts` endpoint returns `{ contractIds: string[] }` — IDs only. The UI prototype shows contract names, which requires an upgrade.
+- **Decision**: Block implementation of the name column until BFF confirms the endpoint will return `{ contracts: Array<{ id: string; name: string }> }`. The service layer (`listAvailableContractsService`) will be updated accordingly.
+- **Consequences**: Implementation is blocked on this BFF change. The fallback (display ID) is acceptable only for internal testing, not for release.
+
+### Implementation Plan
+
+1. **BFF coordination** (blocker): Confirm `listAvailableContracts` returns names; confirm `propagateToChildren` support.
+2. **Update `listAvailableContractsService`** to handle new response shape `{ contracts: AvailableContract[] }`.
+3. **Create `useAddContracts` hook** — wraps `addContractsService`, exposes `{ addContracts, isLoading, hasError }`.
+4. **Create `AddContractsDrawer` component** — implements full drawer UI from prototype spec.
+5. **Wire into `ContractListingLayout`** — add "Add contracts" button; pass `onSuccess` to refresh listing.
+6. **Unit test `useAddContracts`** — success, error, loading state.
+
+---
+
+## 3. Technical Contract
+
+### Data Models
+
+```ts
+// Available contract as returned by the upgraded BFF endpoint
+interface AvailableContract {
+  id: string
+  name: string
+}
+
+// Props for AddContractsDrawer
+interface AddContractsDrawerProps {
+  isOpen: boolean
+  onClose: () => void
+  orgUnitId: string
+  orgUnitName: string
+  existingContractIds: string[]  // IDs already attached — excluded from available list
+  onSuccess: () => void          // called after successful addition (triggers listing refresh)
+}
+```
+
+### Interfaces
+
+```ts
+// useAddContracts hook
+interface UseAddContractsReturn {
+  addContracts: (params: {
+    orgUnitId: string
+    ids: string[]
+    cookie: string
+  }) => Promise<void>
+  isLoading: boolean
+  hasError: boolean
+}
+
+// Updated listAvailableContractsService signature (after BFF upgrade)
+function listAvailableContractsService(params: {
+  orgUnitId: string
+  cookie: string
+}): Promise<AvailableContract[]>
+
+// addContractsService
+function addContractsService(params: {
+  orgUnitId: string
+  ids: string[]
+  cookie: string
+}): Promise<unknown>
+```
+
+### Integration Points
+
+| Point | Direction | Details |
+|---|---|---|
+| `listAvailableContractsService` | Read | Fetches available contracts on drawer open; response shape upgrade required |
+| `addContractsService` | Write | Called on confirm; currently at `POST units/{orgUnitId}/contracts/attached` |
+| `ContractListingLayout` | Parent | Controls `isOpen`; calls `router.replace(router.asPath)` via `onSuccess` to refresh |
+| `useContractSwitchChannel` | None | Not involved — adding contracts does not trigger cross-tab sync |
+| Feature flag `suma` | Gate | `AddContractsDrawer` entry point is only rendered when `featureFlags.suma === true` |
+
+### Invariants & Constraints
+
+- The "Add" button MUST be disabled when `selectedIds.size === 0`.
+- The drawer MUST disable all interactions (search, list, toggles, buttons) while `isLoading === true`.
+- The available list MUST exclude contracts already in `existingContractIds`.
+- Clicking the backdrop while `isLoading` is true MUST NOT close the drawer.
+- On close (backdrop click or cancel button), no BFF call is made and the listing is unchanged.
+- Selection state, search query, and current page reset to their defaults each time the drawer closes.