docs: major README.md and CONTRIBUTING.md simplification and compliance

[nerdCopter]

• README.md: CLI-focused, crate usage moved to CRATE_USAGE.md, TOC and links updated, event export clarified as CLI-only
• CONTRIBUTING.md: pre-commit hook setup instructions added
• MASSIVE reduction of cruft.

Complies with GLOBAL-COPILOT and MARKDOWN instructions for brevity, TOC, and doc structure.

Summary by CodeRabbit

• Documentation

  • Restructured README for clearer navigation and concise usage
  • Added CRATE_USAGE and expanded OVERVIEW with CLI-focused export guidance and example flags/outputs
  • Reorganized docs for better discoverability and simplified feature/API exposition
  • Added contributor guidance to enable pre-commit formatting hooks

• New Features

  • Clarified CSV/GPX/Event export behavior and per-session output patterns in CLI usage notes

• Chores

  • Whitelisted CRATE_USAGE.md in .gitignore

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation reorganized and expanded: CONTRIBUTING.md adds pre-commit hook setup; README.md and OVERVIEW.md were condensed and refocused on CLI exports; a new CRATE_USAGE.md was added; .gitignore updated to whitelist the new doc. No code or public API changes.

Changes

Cohort / File(s)	Change Summary
Contribution guidelines CONTRIBUTING.md	Added Coding Standards guidance recommending enabling the pre-commit formatting hook with commands to copy and make the hook executable (same guidance appears duplicated elsewhere in the file).
Top-level documentation README.md	Restructured README: simplified navigation and overview, removed lengthy API/examples, added links to supporting docs (CRATE_USAGE.md, FRAMES.md, OVERVIEW.md), and condensed license/acknowledgments.
Project overview & public-surface notes OVERVIEW.md	Rewritten to emphasize CLI-first export behavior, document export artifacts/patterns, and describe new/expanded public types and parser entry points (new module/type mentions and re-export layout).
Crate usage guide (new) CRATE_USAGE.md	New crate usage documentation covering installation, cargo features, parsing entry points (parse_bbl_file, parse_bbl_bytes, parse_bbl_file_all_logs), examples, and notes on exporting.
Repository metadata .gitignore	Added whitelist entry !CRATE_USAGE.md so the new documentation file is not ignored.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Verify OVERVIEW.md claims (module names, exported types, export implementation status) match actual code and module layout.
• Confirm CRATE_USAGE.md sample function names and cargo feature descriptions align with the crate's public API.
• Check README cross-links resolve correctly.
• Validate duplicated CONTRIBUTING.md pre-commit instructions are intentional and consistent.

Possibly related PRs

• docs: implement AGPL-3.0 with dual licensing option #2 — Overlapping documentation edits to CONTRIBUTING.md and .gitignore (related contributor guidance and whitelist changes).

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title Check	⚠️ Warning	The pull request title states "docs: major README.md and CONTRIBUTING.md simplification and compliance" and accurately describes changes to those two files. However, the raw summary reveals that OVERVIEW.md underwent significant substantive changes including reworked export descriptions, expanded public API surface documentation, and reorganized data model information. Additionally, a new documentation file CRATE_USAGE.md was added. While the title correctly captures changes to the mentioned files, it fails to represent the full scope of major documentation updates in the PR, particularly the substantial modifications to OVERVIEW.md.	Consider revising the title to more comprehensively capture all major documentation changes, such as "docs: simplify README and add CRATE_USAGE, update OVERVIEW and CONTRIBUTING" or using a more general descriptor like "docs: documentation restructuring and compliance updates" to accurately represent the breadth of changes across multiple documentation files.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch 20251028_docs_fix_and_TOC

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5ed9bf1 and 3c197e6.

📒 Files selected for processing (3)

• CONTRIBUTING.md (1 hunks)
• OVERVIEW.md (4 hunks)
• README.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

OVERVIEW.md

📄 CodeRabbit inference engine (AGENTS.md)

Maintain a proper OVERVIEW.md

Files:

• OVERVIEW.md

{src/**/*.rs,Cargo.*,README.md,OVERVIEW.md,.gitignore,.github/**}

📄 CodeRabbit inference engine (AGENTS.md)

Only commit changes to src/**/*.rs, Cargo.*, README.md, OVERVIEW.md, .gitignore, and .github/**; never use git add . or git add -A

Files:

• OVERVIEW.md
• README.md

README.md

📄 CodeRabbit inference engine (AGENTS.md)

Maintain a proper README.md

Files:

• README.md

🧠 Learnings (2)

📓 Common learnings

Learnt from: nerdCopter
PR: nerdCopter/bbl_parser#2
File: LICENSE_COMMERCIAL:1-4
Timestamp: 2025-08-29T19:52:05.099Z
Learning: nerdCopter prefers to avoid publishing personal information in license files for privacy and security reasons, as they are an individual maintainer rather than a company.

📚 Learning: 2025-10-08T18:00:17.944Z

Learnt from: CR
PR: nerdCopter/bbl_parser#0
File: AGENTS.md:0-0
Timestamp: 2025-10-08T18:00:17.944Z
Learning: Applies to .github/pre-commit-hook.sh : Use `.github/pre-commit-hook.sh` to automatically format code before commits

Applied to files:

• CONTRIBUTING.md

🪛 LanguageTool

OVERVIEW.md

[uncategorized] ~263-~263: The official name of this software platform is spelled with a capital “H”.
Context: ...it hooks for automatic code formatting (.github/pre-commit-hook.sh) - Development envi...

(GITHUB)

---

[uncategorized] ~264-~264: The official name of this software platform is spelled with a capital “H”.
Context: ...- Development environment setup script (.github/setup-dev.sh) --- ## 🏆 **Current St...

(GITHUB)

README.md

[grammar] ~19-~19: Ensure spelling is correct
Context: ...iew BBL Parser reads flight controller blackbox logs and provides a command-line interf...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.18.1)

CONTRIBUTING.md

37-37: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

OVERVIEW.md

90-90: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (9)

OVERVIEW.md (3)

80-84: Export functionality status clearly documented.

The clarification that CSV/GPX/Event exports are CLI-functional with crate-level stubs pending migration is valuable context for users. Sets proper expectations about API maturity.

---

92-110: Module structure accurately reflects documented implementation.

The updated taxonomy with conversion.rs, gps.rs, and clarified parser submodules provides clear guidance on codebase organization. Notation about export.rs stubs aligns with the export status clarification.

---

178-202: CLI examples are comprehensive and show key workflows.

The examples include the new --force-export flag and demonstrate multi-file patterns, output-dir, and all export types. Clear and actionable for users.

README.md (6)

1-23: README effectively restructured for CLI-first audience.

The simplified header and overview immediately establish that this is a command-line tool with an optional crate API. Clear pointer to CRATE_USAGE.md separates concerns and reduces cognitive load for users looking for different types of documentation.

---

7-15: Table of contents provides clear navigation and matches all section headers.

Well-structured TOC supports users in finding relevant sections quickly. Anchors align with section headings.

---

36-51: Quick start examples are focused and practical.

The CLI examples cover the essential workflows: basic analysis, export formats, custom output directory, and force-export. Bash code block is properly formatted with language identifier.

---

53-68: Output formats and smart filtering sections are clear and actionable.

Explicitly listing output file naming conventions (with and without multi-log numbers) and filtering thresholds helps users understand what to expect and when to use --force-export.

---

70-76: Documentation section guides users to appropriate resources by use case.

Clear separation between README (quick start), OVERVIEW.md (architecture), CRATE_USAGE.md (library usage), and examples/ supports users navigating based on their needs.

Confirm that cross-referenced documentation files (CRATE_USAGE.md, FRAMES.md, GOALS.md, examples/README.md) are included in this PR or exist in the repository.

---

78-86: License and acknowledgments sections appropriately condensed.

The dual-license structure (AGPL + commercial) is clearly presented with links. Acknowledgments credits original projects without excessive verbosity.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3c197e6 and 29d9554.

📒 Files selected for processing (4)

• .gitignore (1 hunks)
• CONTRIBUTING.md (1 hunks)
• CRATE_USAGE.md (1 hunks)
• OVERVIEW.md (4 hunks)

✅ Files skipped from review due to trivial changes (2)

• CRATE_USAGE.md
• .gitignore

🧰 Additional context used

📓 Path-based instructions (2)

OVERVIEW.md

📄 CodeRabbit inference engine (AGENTS.md)

Maintain a proper OVERVIEW.md

Files:

• OVERVIEW.md

{src/**/*.rs,Cargo.*,README.md,OVERVIEW.md,.gitignore,.github/**}

📄 CodeRabbit inference engine (AGENTS.md)

Only commit changes to src/**/*.rs, Cargo.*, README.md, OVERVIEW.md, .gitignore, and .github/**; never use git add . or git add -A

Files:

• OVERVIEW.md

🧠 Learnings (2)

📓 Common learnings

Learnt from: nerdCopter
PR: nerdCopter/bbl_parser#2
File: LICENSE_COMMERCIAL:1-4
Timestamp: 2025-08-29T19:52:05.099Z
Learning: nerdCopter prefers to avoid publishing personal information in license files for privacy and security reasons, as they are an individual maintainer rather than a company.

📚 Learning: 2025-10-08T18:00:17.944Z

Learnt from: CR
PR: nerdCopter/bbl_parser#0
File: AGENTS.md:0-0
Timestamp: 2025-10-08T18:00:17.944Z
Learning: Applies to .github/pre-commit-hook.sh : Use `.github/pre-commit-hook.sh` to automatically format code before commits

Applied to files:

• CONTRIBUTING.md

🪛 LanguageTool

OVERVIEW.md

[uncategorized] ~263-~263: The official name of this software platform is spelled with a capital “H”.
Context: ...it hooks for automatic code formatting (.github/pre-commit-hook.sh) - Development envi...

(GITHUB)

---

[uncategorized] ~264-~264: The official name of this software platform is spelled with a capital “H”.
Context: ...- Development environment setup script (.github/setup-dev.sh) --- ## 🏆 **Current St...

(GITHUB)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Build Release Binaries (ubuntu-latest, bbl_parser-linux, target/release/bbl_parser)
• GitHub Check: Build Release Binaries (macos-latest, bbl_parser-macos, target/release/bbl_parser)
• GitHub Check: Build Release Binaries (windows-latest, bbl_parser-windows, target/release/bbl_parser.exe)

🔇 Additional comments (4)

CONTRIBUTING.md (1)

35-40: Pre-commit setup instructions correctly formatted.

The bash language identifier has been added to the code block, resolving the prior linting issue. The hook setup instructions align with the project's formatting workflow as documented in learnings.

OVERVIEW.md (3)

90-111: Language identifier added to code block.

The ```text fence has been added to the project structure code block, resolving the prior MD040 linting issue. Code block is now properly formatted for syntax highlighting compliance.

---

261-264: Align with coding guidelines on file paths.

Per coding guidelines, ensure only the following paths are committed: src/**/*.rs, Cargo.*, README.md, OVERVIEW.md, .gitignore, and .github/**. References to .github/pre-commit-hook.sh and .github/setup-dev.sh in this section are within allowed paths and acceptable. No action required here, but verify the commit scope adheres to guidelines across all files in this PR.

---

253-254: CRATE_USAGE.md has been added to the PR and is properly referenced.

The file exists in the repository root and contains appropriate documentation for the bbl_parser Rust crate, matching the description in OVERVIEW.md. The reference at line 254 is accurate and should remain.