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

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

@@ -0,0 +1,123 @@
+# Implementation Plan: SUMA Phase 2 — Contract Listing, Switching & Management
+
+**Branch**: `feat/suma` | **Date**: 2026-06-15 | **Spec**: [spec.md](./spec.md)
+
+**Input**: Feature specification from `specs/001-suma-phase-2/spec.md`
+
+## Summary
+
+Add a Contract Listing page as the new account homepage (behind a feature flag) that lets buyers view all their Organizational Unit's contracts, switch the active contract via BFF integration, and supports multi-select with keyboard shortcuts. Admin users additionally get add/remove/set-default management flows with optional child-unit propagation. Cross-tab state synchronization is handled via BroadcastChannel. All new code lives in `src/features/contracts/` following the existing domain structure; two new pages are registered in `plugin.config.js`.
+
+## Technical Context
+
+**Language/Version**: TypeScript (strict mode) / Next.js (FastStore plugin — no standalone dev server)
+
+**Primary Dependencies**: `@faststore/ui` (Toggle, Dropdown, Drawer patterns), `next/router` for navigation, React hooks for state and side effects
+
+**Storage**: N/A — plugin is stateless; BFF owns persistence; active contract session is managed externally by the Identity/Auth team
+
+**Testing**: Vitest (unit tests for hooks, services, pure functions), Cypress (E2E for contract switch happy path)
+
+**Target Platform**: Browser — plugin consumed via `yarn link` in a FastStore host store (`b2bfaststoredev.store`)
+
+**Project Type**: FastStore plugin (not a standalone web application)
+
+**Performance Goals**: Contract switch end-to-end < 10 seconds; loading indicator visible < 500ms after click; admin actions confirmed < 5 seconds; cross-tab sync < 2 seconds
+
+**Constraints**: Must not break host store build; TypeScript strict mode (`tsc --noEmit` zero errors); no cross-domain imports (only via `shared/`); zero regressions when feature flag is inactive; all new pages registered in `plugin.config.js` and `buyerPortalRoutes.ts`
+
+**Scale/Scope**: All buyer portal users across any org unit; typical org unit has tens of contracts; no pagination required for MVP (BFF returns all contracts)
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-checked post-design.*
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| I. Plugin Encapsulation | ✅ PASS | New pages registered in `plugin.config.js`; routes in `buyerPortalRoutes.ts`; no host-store coupling |
+| II. Feature-per-Domain | ✅ PASS | All new code in `src/features/contracts/`; cross-domain (Org Unit selector) goes through `shared/` |
+| III. Type Safety | ✅ PASS | No `any` usage; strict TypeScript throughout; `ContractData` type extended if needed |
+| IV. Test Coverage | ✅ PASS | Unit tests for selection hook, activation hook, service wrappers; E2E for P1 contract switch flow |
+| V. Spec-Driven | ✅ PASS | This plan follows the approved spec |
+
+No violations → Complexity Tracking section not needed.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-suma-phase-2/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output (BFF API contracts)
+│   ├── contracts-api.md
+│   └── feature-flag.md
+├── checklists/
+│   └── requirements.md
+└── tasks.md             # Phase 2 output (/speckit-tasks command)
+```
+
+### Source Code (repository root)
+
+```text
+src/
+├── pages/
+│   ├── home.tsx                          # MODIFIED: conditional redirect (flag on → contracts)
+│   ├── contracts.tsx                     # NEW: Contract Listing page
+│   └── contract-information.tsx          # NEW: Contract Information page (active contract home)
+│
+└── features/
+    └── contracts/
+        ├── clients/
+        │   └── ContractsClient.ts        # MODIFIED: add BFF methods (add, remove, set-default, activate)
+        │
+        ├── components/
+        │   ├── ContractsCard/            # EXISTING (no change)
+        │   ├── ContractListItem/         # NEW: single row in listing (name, default badge, selection state)
+        │   ├── ContractSelectionList/    # NEW: full list with multi-select + keyboard shortcuts
+        │   ├── AddContractsDrawer/       # NEW: modal/drawer to add one/many/all contracts
+        │   ├── RemoveContractsDrawer/    # NEW: confirmation + block for last contract
+        │   └── SetDefaultContractAction/ # NEW: trigger to mark contract as default
+        │
+        ├── hooks/
+        │   ├── useUpdateContractStatus.ts  # EXISTING (no change)
+        │   ├── useActivateContract.ts      # NEW: activate contract via BFF + navigate
+        │   ├── useContractSelection.ts     # NEW: multi-select state + keyboard shortcuts
+        │   ├── useAddContracts.ts          # NEW: add contracts mutation
+        │   ├── useRemoveContracts.ts       # NEW: remove contracts mutation
+        │   ├── useSetDefaultContract.ts    # NEW: set default mutation
+        │   └── useCrossTabContractSync.ts  # NEW: BroadcastChannel listener + router.refresh
+        │
+        ├── layouts/
+        │   ├── ContractsLayout/           # EXISTING (repurposed — becomes base for old toggle view)
+        │   ├── ContractListingLayout/     # NEW: Contract Listing page layout (new homepage)
+        │   └── ContractInformationLayout/ # NEW: Contract Information page layout
+        │
+        ├── services/
+        │   ├── get-contracts-org-by-unit-id.service.ts  # EXISTING (no change)
+        │   ├── get-contract-details.service.ts           # EXISTING (no change)
+        │   ├── update-contract-status.service.ts         # EXISTING (no change)
+        │   ├── activate-contract.service.ts              # NEW: BFF activate (distinct from toggle)
+        │   ├── add-contracts.service.ts                  # NEW
+        │   ├── remove-contracts.service.ts               # NEW
+        │   └── set-default-contract.service.ts           # NEW
+        │
+        └── types/
+            ├── ContractData.ts    # MODIFIED: add `isDefault` boolean field
+            └── index.ts
+
+    └── shared/
+        ├── components/
+        │   └── BuyerPortalProvider/
+        │       └── BuyerPortalProvider.tsx  # MODIFIED: add `suma` to FeatureFlags type
+        └── utils/
+            ├── buyerPortalRoutes.ts         # MODIFIED: add `contracts` and `contractInformation` routes
+            └── constants.ts                 # No change
+
+plugin.config.js   # MODIFIED: register `contracts` and `contract-information` pages
+```
+
+**Structure Decision**: Single feature domain (`contracts/`) following the established FastStore plugin pattern. No new top-level directories needed. Cross-domain navigation (Org Unit selector) reuses the existing `OrgUnitBreadcrumb` component from `shared/`.

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

@@ -0,0 +1,156 @@
+# Quickstart Validation Guide: SUMA Phase 2
+
+**Feature**: Contract Listing, Switching & Management  
+**Date**: 2026-06-15
+
+This guide documents how to validate each user story end-to-end once the implementation is in place. It is not a setup guide for the plugin itself — see [docs/README.md](../../docs/README.md) for host store linking instructions.
+
+---
+
+## Prerequisites
+
+1. Plugin linked to host store via `yarn link @vtex/faststore-plugin-buyer-portal`
+2. Host store running locally or pointing to `b2bfaststoredev.store`
+3. Test account: a buyer user belonging to an org unit with **at least 2 contracts**
+4. `enable_suma_phase_2` feature flag **enabled** in FeatureHub for the test environment
+5. Admin test account: same org unit, role with contract management permissions
+
+---
+
+## US-1: View & Switch Active Contract (P1 — Core Flow)
+
+**Scenario**: Feature flag ON, buyer with 2+ contracts
+
+1. Log in as the buyer user
+2. Navigate to `/pvt/organization-account`
+3. **Expected**: Redirect lands on Contract Listing page (`/contracts/{orgUnitId}`), not `org-unit-details`
+4. Verify all contracts for the org unit are listed
+5. Verify the default contract is visually distinguished (badge, highlight, etc.)
+6. Click on a non-active contract
+7. **Expected**: Loading indicator appears within 500ms
+8. **Expected**: On success, browser navigates to the Profile page (`/profile/{orgUnitId}/{contractId}`) — Contract Information
+9. Verify the newly activated contract is reflected as active in the UI
+
+**Error path**:  
+Simulate a BFF failure (disable the activate endpoint or use a network throttle to force timeout).  
+**Expected**: User stays on Contract Listing; an error toast/message appears.
+
+---
+
+## US-2: Multi-Select with Keyboard Shortcuts
+
+**Scenario**: Buyer on Contract Listing with 4+ contracts
+
+1. Navigate to Contract Listing
+2. Press **Cmd+A** (Mac) or **Ctrl+A** (Windows/Linux)
+3. **Expected**: All contracts are visually selected (checkboxes or highlight)
+4. Click on a contract — **Expected**: loading overlay, then navigation to Profile (Contract Information); selection cleared on single click when applicable
+5. **Cmd+Click** (Mac) / **Ctrl+Click** (Win) on contract #1 — **Expected**: selected without navigating
+6. **Cmd+Click** on contract #3 — **Expected**: both #1 and #3 selected
+7. **Shift+Click** on contract #5 — **Expected**: range from #1 (or last anchor) to #5 selected
+
+---
+
+## US-3: Admin — Add Contracts
+
+**Scenario**: Admin user, org unit has at least 1 available contract not yet added
+
+1. Log in as admin, navigate to Contract Listing
+2. Click the "Add contracts" button/trigger
+3. **Expected**: Modal/drawer opens showing available contracts not yet in the unit
+4. Select one contract, click Confirm
+5. **Expected**: Contract appears in the listing
+6. Repeat, selecting multiple contracts at once — **Expected**: all added
+7. Use "Add all available" option — **Expected**: all remaining contracts added
+
+**Propagation test**:  
+When the org unit has child units, toggle "Apply to child units" before confirming.  
+**Expected**: Child units also show the added contracts.
+
+---
+
+## US-4: Admin — Remove Contracts
+
+**Scenario**: Admin user, org unit has 3 contracts
+
+1. Navigate to Contract Listing
+2. **Expected**: Remove option/button is visible (3 contracts > 1)
+3. Select 1 contract via Cmd+Click, click Remove
+4. Confirm in the confirmation UI
+5. **Expected**: Contract removed from listing (now 2 remain)
+
+**Single-contract guard**:  
+Set up an org unit with exactly 1 contract.  
+**Expected**: Remove option is not visible at all.
+
+**Last-contract guard**:  
+With 2 contracts, select both and attempt to remove.  
+**Expected**: UI blocks the action (or unselects the last one) with an informative message.
+
+---
+
+## US-5: Admin — Set Default Contract
+
+**Scenario**: Admin user, org unit has 2+ contracts; Contract A is the default
+
+1. Navigate to Contract Listing — Contract A has default visual indicator
+2. Trigger "Set as default" on Contract B (via dropdown or action button)
+3. **Expected**: Contract B now shows the default indicator; Contract A does not
+
+---
+
+## US-6: Navigation — Org Unit Hierarchy
+
+**Scenario**: User in a child org unit with a parent unit
+
+1. Navigate to Contract Listing for the child unit
+2. Use the Org Unit selector (breadcrumb/dropdown) to navigate to the parent unit
+3. **Expected**: Contract Listing reloads showing the parent unit's contracts and orgUnitId updates in the URL
+4. From an Org Units page, click on a child unit
+5. **Expected**: Navigates to that child unit's Contract Listing
+
+---
+
+## US-7: Cross-Tab State Synchronization
+
+**Scenario**: Same user session open in two browser tabs
+
+1. Open Contract Listing in Tab A and Tab B (same session)
+2. In Tab A, activate a different contract
+3. **Expected**: Within 2 seconds, Tab B reflects the new active contract without manual refresh
+
+---
+
+## Feature Flag Regression Test
+
+**Scenario**: `enable_suma_phase_2` flag is **disabled**
+
+1. Log in as any buyer
+2. Navigate to `/pvt/organization-account`
+3. **Expected**: Redirect goes to `org-unit-details` (existing behavior) — NOT Contract Listing
+4. Verify all existing navigation and pages work without any change
+
+---
+
+## Run Checklist
+
+```
+[ ] US-1: Contract switch success path
+[ ] US-1: Contract switch error path (BFF failure)
+[ ] US-1: Feature flag OFF regression
+[ ] US-2: Cmd/Ctrl+A select all
+[ ] US-2: Cmd/Ctrl+Click individual toggle
+[ ] US-2: Shift+Click range selection
+[ ] US-3: Add single contract
+[ ] US-3: Add multiple contracts
+[ ] US-3: Add all available
+[ ] US-3: Propagate to children
+[ ] US-4: Remove contract (2+ contracts)
+[ ] US-4: Remove option hidden (1 contract)
+[ ] US-4: Block removal of last contract
+[ ] US-4: Propagate removal to children
+[ ] US-5: Set default contract
+[ ] US-6: Navigate to parent org unit
+[ ] US-6: Navigate to child org unit
+[ ] US-7: Cross-tab sync (2-second window)
+```

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

@@ -0,0 +1,150 @@
+# Research: SUMA Phase 2
+
+**Feature**: Contract Listing, Switching & Management  
+**Date**: 2026-06-15  
+**Branch**: `feat/suma`
+
+---
+
+## 1. BFF Endpoint Signatures
+
+### Decision (updated 2026-06-17 — aligned with BFF v1.0.2 changelog)
+
+Use the existing REST pattern (`units/{orgUnitId}/contracts/*`). The confirmed v1.0.2 endpoints:
+
+| Operation | Method | Endpoint | Status |
+|-----------|--------|----------|--------|
+| List attached contracts | `GET` | `units/{orgUnitId}/contracts/attached` | ✅ v1.0.2 |
+| List available contracts | `GET` | `units/{orgUnitId}/contracts/available` | ✅ v1.0.2 |
+| Add contracts to unit | `POST` | `units/{orgUnitId}/contracts/attached` (body: `{ ids: string[] }`) | ✅ v1.0.2 |
+| Remove one contract | `DELETE` | `units/{orgUnitId}/contracts/attached/{contractId}` | ✅ v1.0.2 |
+| Activate contract (switch session) | `POST` | TBD | ⏳ Not in v1.0.2 |
+| Set default contract | `POST` | TBD | ⏳ Not in v1.0.2 |
+
+Management endpoints use a different base (`/_v/contracts-management/unit-contracts/{unitId}`) — see `contracts-api.md` for full details.
+
+**Note on body shape**: Add uses `{ ids: string[] }` (not `{ contractIds }` as originally assumed). DELETE is per-resource, not bulk — call in sequence for multiple removals. Max 20 attached contracts per unit.
+
+**Alternatives considered**: GraphQL mutation — rejected; this project uses REST throughout.
+
+---
+
+## 2. Contract Activation vs. Status Toggle
+
+### Decision
+The existing `updateContractStatus` hook toggles `isActive` on a contract (enabled/disabled in the org unit). The new `useActivateContract` hook performs a different operation: it designates one contract as the session's active contract (the one under which the buyer operates). These are two independent BFF calls and must not be conflated.
+
+**Rationale**: Phase 1 (already shipped) made the first contract always active by default. Phase 2 lets the user choose. The `isActive` flag controls whether a contract is available in the unit; the activation endpoint controls which one the session is scoped to.
+
+**How to apply**: Do not reuse `useUpdateContractStatus` for the contract switch flow. Create `useActivateContract` separately.
+
+---
+
+## 3. Feature Flag Name
+
+### Decision
+Feature flag key: `suma`  
+TypeScript property: `suma` (no conversion needed — key matches property name directly)
+
+**Rationale**: The BFF team confirmed the flag key is `suma`. Unlike `enableAlternativeLogin` which requires snake_case → camelCase normalization, `suma` maps 1:1. Normalization is added in `getBuyerPortalFeatureFlags()` in `get-feature-flags.service.ts`.
+
+**Where to add**:
+1. BFF `flags.constants.ts`: add `'suma'` to `BUYER_PORTAL_FEATURE_FLAGS`
+2. Frontend `BuyerPortalProvider.tsx`: add `suma?: boolean` to `FeatureFlags` type
+3. `get-feature-flags.service.ts`: add `suma: normalized["suma"] ?? false` to `getBuyerPortalFeatureFlags()` return value
+
+**Alternatives considered**: `enable_suma_phase_2` — rejected; BFF team confirmed key is `suma`.
+
+---
+
+## 4. Contract Information Page — New vs. Reuse
+
+### Decision
+The **Contract Information** page is a **new page** (`src/pages/contract-information.tsx`) registered at `/pvt/organization-account/contract-information/[orgUnitId]/[contractId]`. The existing `org-unit-details` page remains unchanged as the homepage when the feature flag is inactive.
+
+**Rationale**: The spec lists "Contract Information" as "Novo" (New). In SUMA Phase 2, after the user activates a contract from the Contract Listing, they land on a page scoped to both `orgUnitId` and `contractId`, showing the active contract context (the contract's home). This is architecturally different from `org-unit-details` which currently shows all contracts via a toggle. Separating them keeps backward compatibility with the flag-off flow.
+
+**How to apply**: The Contract Listing page (`contracts.tsx`) navigates to `contractInformation({ orgUnitId, contractId })` on successful activation. The existing tabs/layouts that use `orgUnitId+contractId` (budgets, buying policies, etc.) are accessible from the Contract Information page's navigation.
+
+**Alternatives considered**: Repurpose `org-unit-details` — rejected; would require feature-flag branching inside the layout, increasing complexity and regression risk.
+
+---
+
+## 5. Multi-Select with Keyboard Shortcuts
+
+### Decision
+Implement `useContractSelection` as a pure React state hook managing a `Set<string>` of selected contract IDs, with event handler factories for:
+
+- **Cmd/Ctrl+A**: `handleSelectAll()` — fills the set with all visible contract IDs
+- **Cmd/Ctrl+Click**: `handleModifierClick(id)` — toggles the contract in the set
+- **Shift+Click**: `handleShiftClick(id, allIds)` — selects the range from the last-clicked index to the target
+
+The hook exposes `selectedIds`, `isSelected(id)`, `clearSelection()`, and the three handlers.
+
+**Rationale**: No external library needed — the combination of a `Set` and standard keyboard event APIs (`event.metaKey`, `event.ctrlKey`, `event.shiftKey`) covers all requirements. This pattern is standard for file-manager-style lists.
+
+**Platform detection**: Use `event.metaKey || event.ctrlKey` for Cmd/Ctrl to support both Mac and Windows/Linux without user-agent sniffing.
+
+**Alternatives considered**: External drag-select library — rejected; overkill for keyboard-only selection; adds bundle weight to a plugin.
+
+---
+
+## 6. Cross-Tab Contract State Synchronization
+
+### Decision
+Use the browser's `BroadcastChannel` API with channel name `'buyer-portal-active-contract'`. After a successful contract activation, post a message `{ type: 'CONTRACT_ACTIVATED', contractId, orgUnitId }`. Other tabs listen on this channel and call `router.refresh()` (Next.js App Router) or `router.replace(router.asPath)` (Pages Router) to reload data.
+
+**Rationale**: `BroadcastChannel` is supported in all modern browsers (Chrome, Firefox, Safari 15.4+, Edge). No backend changes needed. The host store's Next.js version uses the Pages Router (evident from `useRouter` from `next/router` throughout the codebase), so `router.replace(router.asPath)` is the correct refresh mechanism.
+
+**Implementation**: Encapsulated in `useCrossTabContractSync` hook — both sends (on activation success) and listens (on mount). Cleanup removes the channel on unmount.
+
+**Alternatives considered**: `localStorage` + `storage` event — works but less clean than BroadcastChannel; same-tab events can fire unexpectedly. SharedWorker — too complex for this use case. Server-Sent Events — requires backend changes, explicitly excluded by assumptions.
+
+---
+
+## 7. Org Unit Selector (Parent Navigation)
+
+### Decision
+Reuse the existing `OrgUnitBreadcrumb` / `OrgUnitBreadcrumbPath` component from `src/features/org-units/components/OrgUnitBreadcrumb/`. This component is in `shared/components` exports and handles hierarchy navigation. Adapt its integration point in the new `ContractListingLayout` to display the current org unit path and allow navigation to parent nodes.
+
+**Rationale**: The component already exists and solves the same problem (navigating the org unit hierarchy). Importing from `shared/` is compliant with Constitution Principle II.
+
+**Alternatives considered**: New custom selector — rejected; duplicates existing functionality.
+
+---
+
+## 8. ContractData Type Extension
+
+### Decision
+Extend `ContractData` with an `isDefault?: boolean` field. The BFF's list endpoint is expected to return this field (per spec: "the BFF already implements this").
+
+```typescript
+export type ContractData = {
+  name: string | null;
+  id: string;
+  email: string;
+  isActive: boolean;
+  isDefault?: boolean;         // NEW: added for SUMA Phase 2
+  creationDate: string;
+  salesRepresentative?: string;
+  imageUrl?: string;
+  assortment?: unknown[];
+};
+```
+
+**Rationale**: The visual distinction of the default contract requires this field. Optional (`?`) for backward compatibility with existing code that uses `ContractData`.
+
+---
+
+## Summary Table
+
+| Topic | Decision | Status |
+|-------|----------|--------|
+| BFF endpoints | REST pattern; 4 new methods in ContractsClient | Resolved |
+| Activate vs. status toggle | Separate hook and endpoint | Resolved |
+| Feature flag name | `enable_suma_phase_2` / `enableSumaPhase2` | Resolved |
+| Contract Information page | New page at `contract-information/[orgUnitId]/[contractId]` | Resolved |
+| Multi-select | `useContractSelection` hook with Set + keyboard events | Resolved |
+| Cross-tab sync | BroadcastChannel + `router.replace` | Resolved |
+| Org Unit selector | Reuse `OrgUnitBreadcrumb` from shared | Resolved |
+| ContractData type | Add `isDefault?: boolean` | Resolved |

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

@@ -0,0 +1,186 @@
+# Feature Specification: SUMA Phase 2 — Contract Listing, Switching & Management
+
+**Feature Branch**: `feat/suma`
+
+**Created**: 2026-06-15
+
+**Status**: Draft
+
+**Input**: User description: "SUMA Fase 2 — Permite que uma Unidade Organizacional visualize, gerencie e troque o contrato ativo entre múltiplos contratos comerciais disponíveis."
+
+> **Terminology**: **Contract Information** refers to the existing **Profile** page (`/pvt/organization-account/profile/[orgUnitId]/[contractId]`). After switching contracts, buyers land on Profile to operate under the selected contract.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - View and Switch Active Contract (Priority: P1)
+
+A buyer opens the Contract Listing page (new account homepage, active when feature flag is on), sees all contracts for their Organizational Unit with the default contract visually highlighted, clicks a contract, and is navigated to the Profile page (Contract Information) where they now operate under the selected contract.
+
+**Why this priority**: This is the core value of SUMA Phase 2 — enabling users to choose which commercial agreement they operate under. Without this flow, the feature delivers no value.
+
+**Independent Test**: Can be fully tested by visiting the Contract Listing page, clicking a non-active contract, and verifying the user lands on Contract Information operating under the new contract.
+
+**Acceptance Scenarios**:
+
+1. **Given** a buyer is on the Contract Listing page with multiple contracts available, **When** they click on a non-default contract, **Then** a loading indicator appears, the BFF is called to switch the contract session, and the user is navigated to the Profile page upon success.
+2. **Given** the BFF returns an error during contract activation, **When** the request fails, **Then** the user remains on the Contract Listing page and an error message is displayed.
+3. **Given** the feature flag is inactive, **When** the user accesses their account homepage, **Then** the original navigation and homepage are displayed without any regression.
+
+---
+
+### User Story 2 - Multi-Select Contracts with Keyboard Shortcuts (Priority: P2)
+
+A buyer on the Contract Listing page uses keyboard shortcuts to efficiently select multiple contracts for bulk management actions (add, remove, set default).
+
+**Why this priority**: Keyboard shortcuts significantly improve efficiency for power users managing large numbers of contracts. Required for the bulk add/remove flows.
+
+**Independent Test**: Can be fully tested by visiting the Contract Listing page and verifying that Cmd+A selects all, Cmd+Click toggles individual selection, and Shift+Click selects a range — without triggering navigation to the contract detail.
+
+**Acceptance Scenarios**:
+
+1. **Given** a buyer is on the Contract Listing page, **When** they press Cmd+A (Mac) or Ctrl+A (Windows/Linux), **Then** all contracts are selected.
+2. **Given** a buyer is on the Contract Listing page, **When** they Cmd+Click or Ctrl+Click a contract, **Then** that contract is toggled in the selection without navigating to its detail.
+3. **Given** a buyer has selected one contract and then Shift+Clicks another, **Then** all contracts between the two are selected as a range.
+
+---
+
+### User Story 3 - Admin: Add Contracts to Organizational Unit (Priority: P2)
+
+An admin opens the Contract Listing page, opens the add-contracts modal/drawer, selects one, multiple, or all available contracts, optionally propagates to child Organizational Units, and confirms the addition.
+
+**Why this priority**: Admins need to be able to expand their unit's available contracts. This directly enables the P1 switching flow for contracts that are currently unavailable.
+
+**Independent Test**: Can be fully tested by adding a contract as an admin and verifying it appears in the Contract Listing for that Organizational Unit.
+
+**Acceptance Scenarios**:
+
+1. **Given** an admin is on the Contract Listing page, **When** they open the add-contracts interface and select one or more contracts and confirm, **Then** the selected contracts are added to the Organizational Unit and appear in the listing.
+2. **Given** an admin adds contracts, **When** they choose to propagate to child Organizational Units, **Then** the contracts are also added to all direct and indirect child units.
+3. **Given** an admin uses "add all available", **When** confirmed, **Then** every contract available to the unit is added at once.
+
+---
+
+### User Story 4 - Admin: Remove Contracts from Organizational Unit (Priority: P2)
+
+An admin selects one or more contracts and removes them from the Organizational Unit. The system blocks removal of the last contract, and hides the remove option entirely when only one contract is present.
+
+**Why this priority**: Lifecycle management of contracts is essential for admins to keep their unit's contract list accurate.
+
+**Independent Test**: Can be fully tested by removing a contract as an admin (with at least 2 in the list) and verifying it no longer appears in the Contract Listing.
+
+**Acceptance Scenarios**:
+
+1. **Given** an admin has an Organizational Unit with 2+ contracts, **When** they select one or more and confirm removal, **Then** the contracts are removed from the listing.
+2. **Given** an Organizational Unit has exactly 1 contract, **When** the admin views the listing, **Then** the remove option is not displayed.
+3. **Given** an admin selects the last remaining contract for removal, **When** they attempt to remove it, **Then** the UI blocks the action and displays an informative message.
+4. **Given** an admin removes contracts, **When** they choose to propagate to child Organizational Units, **Then** the contracts are also removed from all child units.
+
+---
+
+### User Story 5 - Admin: Set Default Contract (Priority: P2)
+
+An admin designates a specific contract as the default for their Organizational Unit. The default contract is visually highlighted in the listing.
+
+**Why this priority**: The default contract determines which contract new users or unspecified flows start under — a key configuration for org admins.
+
+**Independent Test**: Can be fully tested by setting a non-default contract as the default and verifying the visual highlight updates accordingly.
+
+**Acceptance Scenarios**:
+
+1. **Given** an admin is on the Contract Listing page, **When** they mark a contract as the default, **Then** the listing updates to visually distinguish that contract as the default.
+2. **Given** a default contract is already set, **When** the admin sets a different contract as default, **Then** the previous default loses its default status and the new one gains it.
+
+---
+
+### User Story 6 - Navigation: Parent and Child Org Unit Hierarchy (Priority: P3)
+
+A buyer or admin navigates the Organizational Unit hierarchy — going up to parent units via the Org Unit selector, and down to child units via the Org Units page.
+
+**Why this priority**: Hierarchy navigation is a supporting capability; the core contract features (P1/P2) are usable without it, but it is needed for complete org management workflows.
+
+**Independent Test**: Can be fully tested by using the Org Unit selector to navigate to a parent unit and verifying the Contract Listing reflects the parent unit's contracts.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user is viewing a child Organizational Unit's Contract Listing, **When** they use the Org Unit selector, **Then** they can navigate to a parent unit in the hierarchy.
+2. **Given** a user is on the Org Units page, **When** they select a child unit, **Then** they navigate to that child unit's context.
+
+---
+
+### User Story 7 - Cross-Tab Contract State Synchronization (Priority: P3)
+
+When a user switches their active contract in one browser tab, all other open tabs for the same session automatically reflect the updated contract.
+
+**Why this priority**: Prevents confusing inconsistent state across tabs; important for reliability but not blocking core functionality.
+
+**Independent Test**: Can be fully tested by switching the active contract in one tab and verifying that another open tab updates its displayed active contract within 2 seconds.
+
+**Acceptance Scenarios**:
+
+1. **Given** a user has the buyer portal open in two tabs, **When** they switch the active contract in Tab A, **Then** Tab B updates to reflect the new active contract within 2 seconds without requiring a manual refresh.
+
+---
+
+### Edge Cases
+
+- What happens when the Organizational Unit has exactly 1 contract? The remove option is hidden entirely; the user can only add more contracts.
+- What happens when a user attempts to remove all contracts? The UI blocks the action at the last contract — a minimum of 1 contract is always required per Organizational Unit.
+- What happens when the BFF call to activate a contract fails? The user stays on the Contract Listing page and an error toast/message is displayed with guidance.
+- What happens when the feature flag is turned off? The current homepage and navigation are preserved with no regressions.
+- What happens with multi-tab state sync after a contract switch? The active contract state is synchronized across tabs within 2 seconds.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST display all contracts associated with the user's Organizational Unit on the Contract Listing page.
+- **FR-002**: System MUST visually distinguish the default contract from non-default contracts in the listing.
+- **FR-003**: System MUST display a loading state when a contract activation request is in progress.
+- **FR-004**: System MUST call the BFF endpoint to activate a contract when the user clicks on a contract in the listing.
+- **FR-005**: System MUST navigate the user to the Profile page (Contract Information) upon successful contract switch.
+- **FR-006**: System MUST return the user to the Contract Listing page and display an error message when contract activation fails.
+- **FR-007**: System MUST support multi-selection of contracts via Cmd+A / Ctrl+A (select all), Cmd+Click / Ctrl+Click (toggle individual selection without navigating), and Shift+Click (range selection).
+- **FR-008**: Admin users MUST be able to add one or more contracts — including all available at once — to their Organizational Unit.
+- **FR-009**: Admin users MUST be able to remove individual or multiple contracts in batch from their Organizational Unit.
+- **FR-010**: Admin users MUST be able to designate a contract as the default for their Organizational Unit from the listing.
+- **FR-011**: System MUST block the removal of the last contract in an Organizational Unit — a minimum of 1 contract is always required.
+- **FR-012**: System MUST hide the remove option when an Organizational Unit has exactly 1 contract.
+- **FR-013**: Admin users MUST have the option to propagate contract additions and removals to child Organizational Units.
+- **FR-014**: System MUST replace the current account homepage with the Contract Listing page when the feature flag is active.
+- **FR-015**: System MUST preserve the existing homepage and navigation when the feature flag is inactive, with no regressions.
+- **FR-016**: System MUST synchronize active contract state across multiple browser tabs within the same session.
+- **FR-017**: System MUST include the Organization Manager Agent button as specified in the approved UX prototype.
+- **FR-018**: Users MUST be able to navigate to parent Organizational Units via the Org Unit selector.
+- **FR-019**: Users MUST be able to navigate to child Organizational Units from the Org Units page.
+
+### Key Entities
+
+- **Contract**: A commercial agreement between the VTEX merchant and the buyer's organization. Attributes: identifier, name, default flag. Can be active or inactive for a given session.
+- **Active Contract**: The contract currently selected by the user, under which all operations (pricing, catalog, payment) are evaluated. Stored in session; must be reflected consistently across browser tabs.
+- **Organizational Unit**: A logical group within the buyer organization hierarchy. Holds a set of contracts. Has parent/child relationships with other units.
+- **Admin Profile**: A role within an Organizational Unit that grants contract management capabilities (add, remove, set default, propagate to children).
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: A buyer can switch their active contract and reach the Profile page (Contract Information) in under 10 seconds from the moment of clicking.
+- **SC-002**: 100% of the Organizational Unit's contracts are displayed in the listing without missing entries.
+- **SC-003**: A loading indicator appears within 500 milliseconds of initiating a contract switch.
+- **SC-004**: Users are returned to the Contract Listing with a clear error message within 5 seconds of a failed contract activation, with no session data lost.
+- **SC-005**: Multi-selection keyboard shortcuts (Cmd+A, Ctrl+A, Cmd+Click, Ctrl+Click, Shift+Click) work correctly on both Mac and Windows/Linux platforms.
+- **SC-006**: Enabling or disabling the feature flag produces zero regressions in the existing homepage and navigation behavior.
+- **SC-007**: Active contract state synchronizes across all open browser tabs within 2 seconds of a change.
+- **SC-008**: Admin contract management actions (add, remove, set default) complete with confirmation feedback within 5 seconds.
+- **SC-009**: The remove option is correctly hidden for any Organizational Unit with exactly 1 contract, verified across all admin views.
+
+## Assumptions
+
+- BFF endpoints for listing contracts, activating a contract, setting the default contract, adding contracts, and removing contracts are already implemented and production-ready; this feature covers only frontend integration.
+- The feature flag mechanism is already in place; toggling it per account or environment is the responsibility of the feature flag service, not this feature's implementation.
+- Session state that reflects the active contract is managed by the Identity/Auth team; this feature will consume the session API but does not own its implementation (integration to be confirmed with the Identity/Auth team before coding begins).
+- The Organization Manager Agent is a pre-existing UI component that requires wiring into the Contract Listing page per the approved UX prototype.
+- Propagating changes to child Organizational Units is an opt-in action at the admin's discretion; the default behavior affects only the current unit.
+- The approved UX prototype is the authoritative source for visual design, component layout, and interaction details.
+- Multi-tab synchronization will be implemented using browser-native mechanisms (e.g., BroadcastChannel + router refresh); no backend changes are needed for this behavior.
+- "Notifications of new contracts added by the merchant" are explicitly out of scope and deferred to a future release.