docs: Comprehensive examples and API documentation improvements (#39)

* docs: Clarify multi-log API and add multi_flight_export example

IMPROVEMENTS:

1. New Example: multi_flight_export.rs
   - Demonstrates how to export ALL flights from a BBL file
   - Shows proper use of parse_bbl_file_all_logs()
   - Displays flight numbering and automatic suffixing

2. Updated Examples/README.md
   - Added quick-start section with usage for both single/multi-flight cases
   - Clear explanation of when to use each example
   - API pattern guide showing correct usage
   - Common mistakes section with dos/don'ts
   - Flight numbering table explaining suffixes

3. Updated csv_export.rs Comments
   - Added prominent note about multi-log handling
   - Reference to multi_flight_export example
   - Clarified that this exports only first flight

4. Enhanced CRATE_USAGE.md
   - Added warning section about parse_bbl_file() vs parse_bbl_file_all_logs()
   - Renamed sections for clarity (Single-flight, Multi-flight)
   - Best practices: Handle both cases with parse_bbl_file_all_logs()
   - New Flight Numbering section with detailed explanation
   - Suffix rules documentation
   - Production code recommendation

This addresses the issue where users might accidentally use parse_bbl_file() on multi-flight files and only export the first flight. The new example and documentation make the distinction clear.

* docs: Remove export_demo duplication in examples/README.md

Consolidated duplicate content:

- Removed brief 3-line description of export_demo (lines 72-77)
- Replaced with single cross-reference to the comprehensive section below
- Comprehensive section (Features, Usage, Example Output, Implementation Notes)
  remains intact at line 148+
- Anchor #export_demo-example correctly links from line 73

Improves readability and reduces redundancy while maintaining complete documentation.

* docs: Remove csv_export duplication in examples/README.md

Consolidated duplicate documentation:

- Removed redundant csv_export block from 'Additional Export Examples' section
- Replaced with single cross-reference to comprehensive entry in 'Available Examples'
- Anchor links correctly reference sections above
- Reduces file length by 11 lines while maintaining complete documentation

Improves readability by centralizing example documentation.

* docs: Clarify CLI vs Library API in examples/README.md

Addressed ambiguity about bbl_parser CLI tool usage:

Changes:
1. Removed confusing CLI fallback references from gpx_export and event_export
   - Deleted: 'Use CLI: bbl_parser --gps flight.BBL'
   - Deleted: 'Use CLI: bbl_parser --event flight.BBL'

2. Added new 'CLI Tool vs Library Examples' section explaining:
   - What the CLI binary is (src/main.rs in the crate)
   - When to use CLI (command-line processing, batch operations)
   - When to use library API (Rust integration, programmatic access)
   - How to build/install the CLI
   - Relationship between library, examples, and CLI

This clarifies that:
- bbl_parser CLI is part of the crate (not separate tool)
- It's a convenience wrapper on the library API
- Readers should choose based on their use case
- Examples focus on library integration patterns

* docs: Correct GPS and Event export implementation status

Fixed inaccurate documentation:

Test Results (BTFL_KWONGKAN_10inch_0326_00_Filter.BBL):
- gpx_export: ✅ Successfully exported 833 GPS coordinates
  - Includes home position, elevation, timestamps
  - Valid GPX format with proper structure
- event_export: ✅ Successfully exported 5 events
  - Includes sync beep, flight mode, disarm, log end
  - Proper timestamp collection

Documentation Updates:
- gpx_export status: ⏳ Partial → ✅ Fully functional
- event_export status: ⏳ Partial → ✅ Fully functional
- multi_export status: ⏳ Partial → ✅ Production Ready
- export_demo status: ⏳ Partial → ✅ Production Ready
- Removed misleading footnote about parser enhancement needed
- Updated implementation status table

GPS and Event data collection are fully functional in the parser module.
No parser enhancements are needed.

* docs: Update multi_export status to fully functional

- Changed multi_export status from 'Fully functional for CSV, ⏳ GPS/Event pending'
  to '✅ Fully functional - Exports all available formats'
- Aligns with verified GPS and Event export functionality

* refactor: Simplify output logic in multi_flight_export.rs

- Removed unused 'suffix' variable
- Simplified conditional output with direct if/else branches
- Clearer output messages:
  - Single flight: '✓ Exported'
  - Multiple flights: '✓ Exported as .NN.csv'
- Reduces code complexity and improves readability

* docs: Add status indicator to export_demo section

- Added status line after Usage examples (line 171)
- Consistent with gpx_export, event_export, and multi_export examples
- Status: '✅ Fully functional - Exports all formats (CSV, GPX, events) with comprehensive logging'
- Improves visual consistency and clarity across all example sections

* fix: Add language identifiers to fenced code blocks

- Added 'text' language identifier to multi_flight_export example output (line 42)
- Added 'text' language identifier to export_demo example output (line 176)
- Improves syntax highlighting and markdown linting compliance
- All code blocks now properly labeled: bash, rust, or text

Author: nerdCopter

CRATE_USAGE.md

@@ -2,13 +2,25 @@
 
 Focused guidance for using the bbl_parser Rust crate.
 
+## ⚠️ Important: Understanding Log Numbers and Flight Suffixes
+
+A single BBL file can contain **multiple flight sessions** (separated by LOG_END events). The crate handles this with two different parsing functions:
+
+| Function | Returns | Use Case | Output |
+|----------|---------|----------|--------|
+| `parse_bbl_file()` | First log only | Single-flight files or when you only need the first flight | No suffix (e.g., `flight.csv`) |
+| `parse_bbl_file_all_logs()` | **All logs** | Multi-flight files or when you need all flights | With suffixes (e.g., `flight.01.csv`, `flight.02.csv`) |
+
+**⚠️ Common mistake:** Using `parse_bbl_file()` on a multi-flight file will only export the first flight!
+
 ## Table of Contents
 - [Installation](#installation)
 - [Cargo features](#cargo-features)
-- [Basic usage](#basic-usage)
-- [Multi-log processing](#multi-log-processing)
+- [Single-flight usage](#single-flight-usage)
+- [Multi-flight usage](#multi-flight-usage)
 - [Parsing from memory](#parsing-from-memory)
 - [Export functionality](#export-functionality)
+- [Flight numbering](#flight-numbering)
 - [Examples](#examples)
 - [Notes](#notes)
 
@@ -31,7 +43,9 @@ bbl_parser = { path = "path/to/bbl_parser" }
 
 If you only need the parser types and functions, the defaults are fine.
 
-## Basic usage
+## Single-flight usage
+
+For BBL files containing a single flight:
 
 ```rust
 use bbl_parser::{parse_bbl_file, ExportOptions};
@@ -40,27 +54,53 @@ use std::path::Path;
 fn main() -> anyhow::Result<()> {
     let log = parse_bbl_file(Path::new("flight.BBL"), ExportOptions::default(), false)?;
     println!("firmware: {}", log.header.firmware_revision);
-    println!("frames: {}", log.sample_frames.len());
+    println!("frames: {}", log.stats.total_frames);
     Ok(())
 }
 ```
 
 Key outputs on the BBLLog:
 - `header`: configuration and metadata
-- `sample_frames`: decoded I/P/S/G/H/E frames
+- `frames`: decoded flight data frames
 - `event_frames`: flight events (when present)
 - `gps_track`: GPS coordinates (when present)
+- `log_number` / `total_logs`: Current log number and total (useful to know if multi-log)
+
+## Multi-flight usage
 
-## Multi-log processing
+**For files with multiple flight sessions, ALWAYS use `parse_bbl_file_all_logs()`:**
 
 ```rust
 use bbl_parser::{parse_bbl_file_all_logs, ExportOptions};
 use std::path::Path;
 
 fn main() -> anyhow::Result<()> {
     let logs = parse_bbl_file_all_logs(Path::new("multi_flight.BBL"), ExportOptions::default(), false)?;
+    
     for log in logs {
-        println!("log {} of {} -> frames {}", log.log_number, log.total_logs, log.sample_frames.len());
+        println!("Flight {}/{}", log.log_number, log.total_logs);
+        println!("  Frames: {}", log.stats.total_frames);
+        println!("  Firmware: {}", log.header.firmware_revision);
+    }
+    Ok(())
+}
+```
+
+### Best Practice: Handle Both Cases
+
+To write robust code that works with any BBL file:
+
+```rust
+use bbl_parser::{parse_bbl_file_all_logs, ExportOptions};
+use std::path::Path;
+
+fn main() -> anyhow::Result<()> {
+    let logs = parse_bbl_file_all_logs(Path::new("flight.BBL"), ExportOptions::default(), false)?;
+    
+    // This works whether the file has 1 flight or many
+    for log in logs {
+        println!("Flight {}/{}: {} frames", log.log_number, log.total_logs, log.stats.total_frames);
+        // Process this flight
     }
     Ok(())
 }
@@ -69,26 +109,32 @@ fn main() -> anyhow::Result<()> {
 ## Parsing from memory
 
 ```rust
-use bbl_parser::{parse_bbl_bytes, ExportOptions};
+use bbl_parser::{parse_bbl_bytes, parse_bbl_bytes_all_logs, ExportOptions};
 
 fn main() -> anyhow::Result<()> {
     let bytes = std::fs::read("flight.BBL")?;
+    
+    // Single flight (first only):
     let log = parse_bbl_bytes(&bytes, ExportOptions::default(), false)?;
-    println!("frames: {}", log.sample_frames.len());
+    
+    // All flights:
+    let logs = parse_bbl_bytes_all_logs(&bytes, ExportOptions::default(), false)?;
+    
+    println!("frames: {}", log.stats.total_frames);
     Ok(())
 }
 ```
 
 ## Export functionality
 
-The crate now provides full export capabilities for CSV, GPX, and Event data formats.
+The crate provides full export capabilities for CSV, GPX, and Event data formats.
 
 ### CSV Export
 
 Export parsed log data to CSV files (flight data + headers):
 
 ```rust
-use bbl_parser::{parse_bbl_file, export_to_csv, ExportOptions};
+use bbl_parser::{parse_bbl_file_all_logs, export_to_csv, ExportOptions};
 use std::path::Path;
 
 fn main() -> anyhow::Result<()> {
@@ -100,23 +146,30 @@ fn main() -> anyhow::Result<()> {
         force_export: false,
     };
 
-    let log = parse_bbl_file(Path::new("flight.BBL"), export_opts.clone(), false)?;
-    export_to_csv(&log, Path::new("flight.BBL"), &export_opts)?;
+    // Export all logs from the file (handles both single and multi-log files)
+    let logs = parse_bbl_file_all_logs(Path::new("flight.BBL"), export_opts.clone(), false)?;
+    for log in logs {
+        export_to_csv(&log, Path::new("flight.BBL"), &export_opts)?;
+    }
     println!("CSV exported successfully");
     Ok(())
 }
 ```
 
-This creates two files:
-- `flight.csv` - Main flight data with blackbox_decode compatible format
-- `flight.headers.csv` - Complete header information
+This creates two files per flight:
+- `flight.csv` or `flight.01.csv`, `flight.02.csv`, etc. - Main flight data with blackbox_decode compatible format
+- `flight.headers.csv` or `flight.01.headers.csv`, `flight.02.headers.csv`, etc. - Complete header information
+
+**Flight Number Suffixes:**
+- Single flight: No suffix (e.g., `flight.csv`)
+- Multiple flights: Zero-padded 2-digit suffix (e.g., `flight.01.csv`, `flight.02.csv`, `flight.03.csv`)
 
 ### GPX Export
 
 Export GPS data to GPX format for mapping applications:
 
 ```rust
-use bbl_parser::{parse_bbl_file, export_to_gpx, ExportOptions};
+use bbl_parser::{parse_bbl_file_all_logs, export_to_gpx, ExportOptions};
 use std::path::Path;
 
 fn main() -> anyhow::Result<()> {
@@ -128,10 +181,11 @@ fn main() -> anyhow::Result<()> {
         force_export: false,
     };
 
-    let log = parse_bbl_file(Path::new("flight.BBL"), export_opts.clone(), false)?;
+    let logs = parse_bbl_file_all_logs(Path::new("flight.BBL"), export_opts.clone(), false)?;
 
-    if !log.gps_coordinates.is_empty() {
-        export_to_gpx(
+    for log in logs {
+        if !log.gps_coordinates.is_empty() {
+            export_to_gpx(
             Path::new("flight.BBL"),
             0,  // log index
             log.total_logs,
@@ -216,14 +270,75 @@ fn main() -> anyhow::Result<()> {
 }
 ```
 
+## Flight Numbering
+
+Understanding how the crate handles flight numbers is critical for proper export handling:
+
+### What Causes Multiple Flights?
+
+A single BBL file contains multiple flights when the flight controller logs multiple sessions without restarting, typically separated by `LOG_END` events. Examples:
+- Same drone, multiple flights in one session
+- Interrupted logging (pause and resume)
+- Extended flight with logging that resets internal counters
+
+### Flight Number Behavior
+
+| Scenario | Log Number | Total Logs | Output File | Notes |
+|----------|-----------|-----------|------------|-------|
+| Single flight | 1 | 1 | `flight.csv` | No suffix when only one log |
+| 3 flights in file, export 1st | 1 | 3 | `flight.csv` | Using `parse_bbl_file()` only |
+| 3 flights in file, export all | 1, 2, 3 | 3 | `flight.01.csv`, `flight.02.csv`, `flight.03.csv` | Using `parse_bbl_file_all_logs()` |
+
+### Accessing Flight Information
+
+```rust
+use bbl_parser::{parse_bbl_file_all_logs, ExportOptions};
+use std::path::Path;
+
+fn main() -> anyhow::Result<()> {
+    let logs = parse_bbl_file_all_logs(
+        Path::new("flight.BBL"), 
+        ExportOptions::default(), 
+        false
+    )?;
+    
+    for log in logs {
+        println!("Flight {}/{}", log.log_number, log.total_logs);
+        println!("  Frames: {}", log.stats.total_frames);
+        println!("  Firmware: {}", log.header.firmware_revision);
+        
+        // The export_to_csv function automatically adds the proper suffix
+        // based on log.log_number and log.total_logs
+    }
+    Ok(())
+}
+```
+
+### Suffix Rules
+
+- **No suffix** if `total_logs == 1` (e.g., `flight.csv`)
+- **Suffix** if `total_logs > 1` (e.g., `flight.01.csv`, `flight.02.csv`)
+- **Format**: Zero-padded 2-digit number (`.01`, `.02`, ... `.99`)
+- **Automatic**: The `export_to_csv()`, `export_to_gpx()`, and `export_to_event()` functions handle suffixing automatically
+
 For runnable examples with complete code and output, see [examples/README.md](./examples/README.md).
 
 ## Examples
 
-Run the crate example that demonstrates multi-firmware support and PID extraction:
+### Quick Start Examples
+
+**Export single flight (or first flight only):**
+```bash
+cargo run --example csv_export -- flight.BBL ./output
+```
+
+**Export all flights with proper numbering:**
+```bash
+cargo run --example multi_flight_export -- flight.BBL ./output
+```
 
+**Complete parsing and data access:**
 ```bash
-cargo build --example bbl_crate_test
 cargo run --example bbl_crate_test -- flight.BBL
 ```
 
@@ -234,3 +349,4 @@ More details: [examples/README.md](./examples/README.md)
 - API is evolving while the project is WIP; names and structures may change.
 - CSV field order and naming follow blackbox-tools to maximize compatibility.
 - For CLI usage and high-level overview, see the main [README](./README.md).
+- **Always use `parse_bbl_file_all_logs()` in production code** to ensure all flights are processed correctly.