docs(scanner): update Bruno requests for new scanner endpoints

- Update Scan Ebooks.bru to reflect async background scanning
- Add Get Scan Status.bru for checking job progress
- Add Start Watch Mode.bru for instant file monitoring
- Add Stop Watch Mode.bru for stopping library monitoring
- Add Get Watch Mode Status.bru for checking watched libraries
- Document all new endpoints with examples and status codes

bruno/scanner/Get Scan Status.bru

@@ -0,0 +1,71 @@
+meta {
+  name: Get Scan Status
+  type: http
+  seq: 4
+}
+
+get {
+  url: {{base_url}}/api/scanner/status/{{job_id}}
+  auth: inherit
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}
+
+docs {
+  ## Get Scan Status
+  
+  Retrieves the status and progress of an asynchronous scan job.
+  
+  **Method:** GET
+  
+  **Endpoint:** /api/scanner/status/:jobId
+  
+  **Authentication:** Required (Bearer token, Admin only)
+  
+  **URL Parameters:**
+  - `jobId` (string, required): The job ID returned from the scan endpoint
+    - Example: `550e8400-e29b-41d4-a716-446655440000`
+  
+  **Response:**
+  ```json
+  {
+    "job_id": "550e8400-e29b-41d4-a716-446655440000",
+    "status": "completed",
+    "error": "",
+    "result": {
+      "message": "scan completed",
+      "library_id": "550e8400-e29b-41d4-a716-446655440000"
+    },
+    "progress": 1.0
+  }
+  ```
+  
+  **Properties:**
+  - `job_id` (string): Job identifier
+  - `status` (string): Current status
+    - `pending`: Job is queued
+    - `running`: Job is currently processing
+    - `completed`: Job finished successfully
+    - `failed`: Job failed with error
+    - `cancelled`: Job was cancelled
+  - `error` (string): Error message if status is "failed"
+  - `result` (object): Scan results when completed
+    - `message` (string): Completion message
+    - `library_id` (string): Library that was scanned
+  - `progress` (number): Progress indicator (0.0 to 1.0)
+  
+  **Status Codes:**
+  - 200: Job status retrieved successfully
+  - 401: Unauthorized
+  - 403: Forbidden (admin access required)
+  - 404: Job not found
+  
+  **Example Workflow:**
+  1. POST /api/scanner/scan with folder_paths
+  2. Receive job_id in response
+  3. Poll GET /api/scanner/status/{job_id} every few seconds
+  4. When status is "completed" or "failed", stop polling
+}

bruno/scanner/Get Watch Mode Status.bru

@@ -0,0 +1,47 @@
+meta {
+  name: Get Watch Mode Status
+  type: http
+  seq: 7
+}
+
+get {
+  url: {{base_url}}/api/scanner/watch/status
+  auth: inherit
+}
+
+docs {
+  ## Get Watch Mode Status
+  
+  Retrieves the current status of watch mode for all libraries.
+  
+  **Method:** GET
+  
+  **Endpoint:** /api/scanner/watch/status
+  
+  **Authentication:** Required (Bearer token, Admin only)
+  
+  **Response:** HTTP 200 (OK)
+  ```json
+  {
+    "watching_libraries": [
+      "550e8400-e29b-41d4-a716-446655440000",
+      "660e8400-e29b-41d4-a716-446655440001"
+    ],
+    "total_watching": 2
+  }
+  ```
+  
+  **Properties:**
+  - `watching_libraries` (array of strings): List of library IDs currently being watched
+  - `total_watching` (number): Total number of libraries being watched
+  
+  **Status Codes:**
+  - 200: Status retrieved successfully
+  - 401: Unauthorized
+  - 403: Forbidden (admin access required)
+  
+  **Use cases:**
+  - Check which libraries are currently being monitored
+  - Verify that watch mode started successfully after server boot
+  - Debug file system monitoring issues
+}

bruno/scanner/Scan Ebooks.bru

@@ -1,5 +1,5 @@
 meta {
-  name: Scan Ebooks
+  name: Scan Ebooks (Background)
   type: http
   seq: 1
 }
@@ -15,37 +15,48 @@ settings {
   timeout: 0
 }
 
-docs {
+body:json {
-  ## Scan Ebooks
+  {
+    "folder_paths": ["/path/to/ebooks"]
+  }
+}
 
-  Triggers a scanning operation to discover and index ebook files in the library.
+docs {
+  ## Scan Ebooks (Background)
+  
+  Triggers an asynchronous ebook scanning operation. The scan runs in the background and can be monitored using the job ID.
   
   **Method:** POST
   
   **Endpoint:** /api/scanner/scan
   
-  **Authentication:** Required (Bearer token)
+  **Authentication:** Required (Bearer token, Admin only)
   
-  **Request Body:** (optional)
+  **Request Body:**
-  - `library_id` (string, optional): Specific library ID to scan
+  - `folder_paths` (array of strings, required): List of folder paths to scan
-  - `scan_depth` (number, optional): Maximum directory depth to scan
+    - Example: `["/path/to/ebooks", "/another/path"]`
-  - `file_types` (array, optional): File extensions to include
   
-  **Response:**
+  **Response:** HTTP 202 (Accepted)
-  - JSON object containing scan operation details
+  ```json
-    - `scan_id` (string): Unique scan operation identifier
+  {
-    - `status` (string): Scan status ("initiated", "running", "completed")
+    "message": "scan job enqueued",
-    - `library_id` (string): Library being scanned
+    "job_id": "550e8400-e29b-41d4-a716-446655440000",
-    - `files_found` (number): Number of files discovered
+    "status": "pending"
-    - `files_processed` (number): Number of files processed
+  }
-    - `started_at` (string): Scan start timestamp
+  ```
-    - `estimated_completion` (string): Estimated completion time
+  
+  **Properties:**
+  - `message` (string): Confirmation message
+  - `job_id` (string): Unique job identifier for tracking progress
+  - `status` (string): Initial job status ("pending")
   
   **Status Codes:**
-  - 200: Scan initiated successfully
+  - 202: Scan job successfully enqueued
-  - 400: Invalid request parameters
+  - 400: Invalid request (missing folder_paths)
   - 401: Unauthorized
-  - 403: Forbidden (insufficient permissions)
+  - 403: Forbidden (admin access required)
-  - 409: Scan already in progress
+  - 500: Failed to enqueue scan job
-  - 500: Internal server error
+  
+  **Next Steps:**
+  Use the returned `job_id` with `GET /api/scanner/status/:jobId` to check scan progress.
 }

bruno/scanner/Start Watch Mode.bru

@@ -0,0 +1,61 @@
+meta {
+  name: Start Watch Mode
+  type: http
+  seq: 5
+}
+
+post {
+  url: {{base_url}}/api/scanner/watch/start
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "library_id": "{{library_id}}"
+  }
+}
+
+docs {
+  ## Start Watch Mode
+  
+  Starts real-time file system monitoring for a specific library. New ebooks will be detected and processed almost instantly.
+  
+  **Method:** POST
+  
+  **Endpoint:** /api/scanner/watch/start
+  
+  **Authentication:** Required (Bearer token, Admin only)
+  
+  **Request Body:**
+  - `library_id` (string, required): UUID of the library to watch
+    - Example: `"550e8400-e29b-41d4-a716-446655440000"`
+  
+  **Response:** HTTP 200 (OK)
+  ```json
+  {
+    "message": "watch mode started for library",
+    "library_id": "550e8400-e29b-41d4-a716-446655440000"
+  }
+  ```
+  
+  **How it works:**
+  - Monitors all folders configured for the library
+  - Automatically detects new ebook files (CREATE events)
+  - Detects modifications to existing files (WRITE events)
+  - Processes new files within milliseconds of detection
+  - Automatically watches new subdirectories as they're created
+  
+  **Supported file types:**
+  - `.epub`, `.pdf`, `.mobi`, `.azw3`, `.fb2`, `.txt`
+  
+  **Status Codes:**
+  - 200: Watch mode started successfully
+  - 400: Invalid request (missing library_id)
+  - 401: Unauthorized
+  - 403: Forbidden (admin access required)
+  - 409: Already watching this library
+  - 500: Failed to start watch mode (no folders configured, etc.)
+  
+  **Note:** Watch mode is automatically started for all libraries when the server starts.
+}

bruno/scanner/Stop Watch Mode.bru

@@ -0,0 +1,51 @@
+meta {
+  name: Stop Watch Mode
+  type: http
+  seq: 6
+}
+
+post {
+  url: {{base_url}}/api/scanner/watch/stop
+  body: json
+  auth: inherit
+}
+
+body:json {
+  {
+    "library_id": "{{library_id}}"
+  }
+}
+
+docs {
+  ## Stop Watch Mode
+  
+  Stops real-time file system monitoring for a specific library.
+  
+  **Method:** POST
+  
+  **Endpoint:** /api/scanner/watch/stop
+  
+  **Authentication:** Required (Bearer token, Admin only)
+  
+  **Request Body:**
+  - `library_id` (string, required): UUID of the library to stop watching
+    - Example: `"550e8400-e29b-41d4-a716-446655440000"`
+  
+  **Response:** HTTP 200 (OK)
+  ```json
+  {
+    "message": "watch mode stopped for library",
+    "library_id": "550e8400-e29b-41d4-a716-446655440000"
+  }
+  ```
+  
+  **Status Codes:**
+  - 200: Watch mode stopped successfully
+  - 400: Invalid request (missing library_id)
+  - 401: Unauthorized
+  - 403: Forbidden (admin access required)
+  - 404: Not watching this library
+  - 500: Internal server error
+  
+  **Note:** If no libraries are being watched, the watch mode context is cleaned up automatically.
+}