docs: document automatic pairing retry feature (CG-19)

Updated documentation for the automatic retry logic added to code-based
probe pairing:

- guides/user/getting-started/pairing-probes.md: Added "Automatic Retries"
  section explaining retry behavior and Skip Retry button
- reference/firmware/controller/thread-br.md: Added comprehensive
  "Automatic Pairing Retry" section with configuration, API, events, and
  UI integration details
- reference/ui/screen-inventory.md: Updated PAIRING_PROGRESS entry with
  retry UI changes
- reference/architecture/controller/event-system.md: Added
  CLEARGROW_EVENT_PAIRING_RETRY and CLEARGROW_EVENT_PAIRING_SKIP_RETRY
  events, updated probe pairing flow diagram

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

guides/user/getting-started/pairing-probes.md

@@ -49,6 +49,16 @@ The controller will automatically scan for nearby probes on the Thread network.
 
 The probe LED will blink during pairing.
 
+### Automatic Retries
+
+**Added 2025-12-11 (CG-19):** If the pairing attempt times out (default 2 minutes), the controller will automatically retry up to 2 additional times before showing an error. During retries:
+
+- The screen shows "Attempt X of 3" to indicate progress
+- Your pairing code is preserved—you don't need to re-enter it
+- A **Skip Retry** button appears if you want to stop retrying early
+
+This helps account for transient network conditions or if the probe takes time to power on fully.
+
 ### Step 4: Confirm Connection
 
 When successful:
@@ -86,6 +96,17 @@ Repeat the process for each probe. Tips:
 
 ## Troubleshooting
 
+### Pairing Times Out
+
+If pairing times out after all automatic retries:
+
+- The controller tried 3 times (1 initial + 2 retries by default)
+- Check probe battery and power state
+- Move probe closer to controller
+- Tap **Try Again** to restart the pairing process
+
+If you want to stop waiting before retries complete, tap **Skip Retry** on the progress screen.
+
 ### "Code Not Found"
 
 - Verify code matches the card exactly

reference/architecture/controller/event-system.md

@@ -624,6 +624,49 @@ typedef struct {
 
 **Handlers**: UI shows error message
 
+#### CLEARGROW_EVENT_PAIRING_RETRY
+
+**Added**: 2025-12-11 (CG-19)
+
+**Posted by**: Code Pairing module (via `post_retry_event()`)
+
+**Event Data**: `pairing_retry_event_data_t`
+
+```c
+typedef struct {
+    uint8_t current_attempt;  /**< Current attempt number (1-based) */
+    uint8_t max_attempts;     /**< Total number of attempts */
+} pairing_retry_event_data_t;
+```
+
+**Purpose**: Automatic retry starting after pairing timeout
+
+**Handlers**:
+- **UI** (`scr_pairing_progress.c`): Updates "Attempt X of Y" display, shows Skip Retry button
+
+**Example**:
+```c
+case CLEARGROW_EVENT_PAIRING_RETRY: {
+    pairing_retry_event_data_t *data = (pairing_retry_event_data_t *)event_data;
+    if (data) {
+        update_retry_display(data->current_attempt, data->max_attempts);
+    }
+    break;
+}
+```
+
+#### CLEARGROW_EVENT_PAIRING_SKIP_RETRY
+
+**Added**: 2025-12-11 (CG-19)
+
+**Posted by**: UI (Skip Retry button press)
+
+**Event Data**: None
+
+**Purpose**: User requested to skip remaining automatic retries
+
+**Handlers**: Code Pairing module sets `skip_retry` flag (via `code_pairing_skip_retry()`)
+
 ### Discovery Events
 
 #### CLEARGROW_EVENT_DISCOVERY_START
@@ -874,7 +917,21 @@ static void system_event_handler(void *arg, esp_event_base_t base,
     └─> Device Registry adds probe
     └─> UI shows success, navigates to probe config
 
-4b. Failure path:
+4b. Timeout with retry (CG-19):
+    Thread Manager posts CLEARGROW_EVENT_PAIRING_RETRY
+    └─> UI updates "Attempt X of Y"
+    └─> UI shows Skip Retry button
+    └─> Return to step 2 (retry pairing)
+
+    User can press Skip Retry:
+    └─> UI calls code_pairing_skip_retry()
+    └─> Sets skip_retry flag, next timeout goes to 4c
+
+4c. Final timeout path:
+    Thread Manager posts CLEARGROW_EVENT_PAIRING_TIMEOUT
+    └─> UI shows timeout error
+
+4d. Failure path:
     Thread Manager posts CLEARGROW_EVENT_PAIRING_FAILED
     └─> UI shows error message
 ```

reference/firmware/controller/thread-br.md

@@ -223,6 +223,87 @@ The Thread BR task registers for pairing events and coordinates code-based pairi
 
 **Implementation**: `/opt/repos/controller/components/thread_manager/src/thread_br.c` - `pairing_event_handler()`
 
+### Automatic Pairing Retry
+
+**Implementation Date**: 2025-12-11 (CG-19)
+
+When a pairing attempt times out, the system automatically retries to improve reliability in transient network conditions.
+
+#### Configuration
+
+| Kconfig Option | Default | Range | Description |
+|----------------|---------|-------|-------------|
+| `CONFIG_CODE_PAIRING_MAX_RETRIES` | 2 | 0-5 | Number of automatic retries after initial attempt |
+| `CONFIG_CODE_PAIRING_TIMEOUT_MS` | 120000 | 30000-600000 | Timeout per attempt (ms) |
+
+Set `CONFIG_CODE_PAIRING_MAX_RETRIES=0` to disable automatic retries.
+
+#### Retry State
+
+The `pairing_state_t` structure tracks retry progress:
+
+```c
+typedef struct {
+    // ... other fields ...
+    uint8_t retry_count;    // Current retry attempt (0 = first attempt)
+    uint8_t max_retries;    // Maximum retry attempts allowed
+    bool skip_retry;        // User requested to skip remaining retries
+} pairing_state_t;
+```
+
+Retry count is persisted to NVS, allowing recovery if the device reboots during pairing.
+
+#### Retry Flow
+
+```
+1. Initial pairing attempt starts (retry_count = 0)
+2. Timeout occurs after CONFIG_CODE_PAIRING_TIMEOUT_MS
+3. code_pairing_handle_timeout() checks:
+   - If retry_count < max_retries AND !skip_retry:
+     a. Increment retry_count
+     b. Post CLEARGROW_EVENT_PAIRING_RETRY
+     c. Restart pairing with same PSKd
+   - Otherwise:
+     a. Post CLEARGROW_EVENT_PAIRING_TIMEOUT
+     b. Navigate to error screen
+```
+
+#### API Functions
+
+```c
+// Skip remaining retries (user requested)
+esp_err_t code_pairing_skip_retry(void);
+
+// Get current retry status
+esp_err_t code_pairing_get_retry_info(uint8_t *current_attempt, uint8_t *max_attempts);
+```
+
+Both functions return `ESP_ERR_INVALID_STATE` if pairing is not active.
+
+#### Events
+
+| Event | Direction | Data | Description |
+|-------|-----------|------|-------------|
+| `CLEARGROW_EVENT_PAIRING_RETRY` | thread_mgr → UI | `pairing_retry_event_data_t` | Retry started |
+| `CLEARGROW_EVENT_PAIRING_SKIP_RETRY` | UI → thread_mgr | none | Skip remaining retries |
+
+```c
+typedef struct {
+    uint8_t current_attempt;  // Current attempt number (1-based)
+    uint8_t max_attempts;     // Total number of attempts
+} pairing_retry_event_data_t;
+```
+
+#### UI Integration
+
+The pairing progress screen (`scr_pairing_progress.c`) responds to retry events:
+
+- Shows "Attempt X of Y" label when retries occur
+- Displays "Skip Retry" button when more retries are available
+- Updates hint text to indicate retry in progress
+
+**Implementation**: `/opt/repos/controller/components/thread_manager/src/code_pairing.c`
+
 ### RCP Interface Architecture
 
 **Implementation Date**: 2025-12-09 (CTRL-TA-002)

reference/ui/screen-inventory.md

@@ -102,10 +102,16 @@ typedef enum {
 |--------|----------|---------|
 | PAIRING_CODE | 1 | Enter pairing code |
 | PAIRING_DISCOVERY | 2 | Searching for probe |
-| PAIRING_PROGRESS | 3 | Commissioning |
+| PAIRING_PROGRESS | 3 | Commissioning (with automatic retry) |
 | PAIRING_SUCCESS | 4a | Success confirmation |
 | PAIRING_ERROR | 4b | Error handling |
 
+**Updated 2025-12-11 (CG-19):** The `PAIRING_PROGRESS` screen now supports automatic retry:
+- Shows "Attempt X of Y" label during retries
+- Displays "Skip Retry" button when retries are available
+- Responds to `CLEARGROW_EVENT_PAIRING_RETRY` events
+- Default: 3 total attempts (1 initial + 2 retries)
+
 **Updated 2025-12-10:** The `PAIRING_DISCOVERY` screen now uses active probe discovery via `probe_discovery_start()`. Probes are discovered through:
 1. Device registry query (immediate)
 2. Thread child table enumeration (via Spinel)