From f8675b85b88ce9d0e373bbad545a9c43cc700e86 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 10 Nov 2025 13:24:54 +0000
Subject: [PATCH 1/4] docs: rewrite README with CLI-first approach

Completely restructured the main README to focus on CLI usage:
- Clear positioning as CLI tool first, library second
- Added "What is DBF?" section for context
- Moved Quick Start to top with installation
- Organized examples by practical use cases
- Added Common Use Cases section with real scenarios
- Moved .NET library section to end with clear reference
- Improved feature list focused on CLI benefits
- Added historical context about DBF format
- Better navigation with links to detailed docs

This addresses user confusion about whether DbfSharp is a C#
library or CLI tool, making it clear the primary use case is CLI.
---
 README.md | 334 +++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 265 insertions(+), 69 deletions(-)

diff --git a/README.md b/README.md
index f2085e5..e612167 100644
--- a/README.md
+++ b/README.md
@@ -3,116 +3,312 @@
 [![DeepWiki](https://img.shields.io/badge/DeepWiki-emmorts%2Fdbfsharp-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/emmorts/dbfsharp)
 ![NuGet Version](https://img.shields.io/nuget/v/dbfsharp.core)
 
+**A modern, high-performance command-line tool for working with DBF database files and Shapefiles.**
 
-A high-performance .NET library and command-line tool for reading dBASE (DBF) files and Shapefiles with support for all major DBF versions, memo files, and advanced spatial operations.
+Convert legacy dBASE files to modern formats (CSV, JSON, GeoJSON), analyze file structures, and perform spatial queries—all from your terminal.
 
-## Features
+---
 
-- Support for all major DBF versions (dBase III, IV, Visual FoxPro, etc.)
-- **Complete Shapefile support** with geometry reading and spatial indexing
-- **Spatial operations** with R-tree indexing for fast spatial queries
-- Optimized streaming and memory-efficient processing
-- Cross-platform support (Windows, Linux, macOS)
-- Both .NET library and command-line tool
-- Plugin architecture for custom field parsers
+## What is DBF?
+
+DBF (dBASE Database File) is a legacy database format created in 1983, still widely used in GIS applications, legacy business systems, and government data. DbfSharp makes it easy to extract and convert this data to modern formats without needing specialized database software.
+
+---
 
 ## Quick Start
 
-### .NET Library
+```bash
+# Install globally
+dotnet tool install -g DbfSharp
+
+# Convert DBF to CSV
+dbfsharp read customers.dbf --format csv --output customers.csv
+
+# Analyze file structure
+dbfsharp info data.dbf
+
+# Export Shapefile to GeoJSON
+dbfsharp read cities.shp --format geojson --output cities.geojson
+
+# Spatial query on Shapefile
+dbfsharp read parcels.shp --bounding-box "-118.5,34.0,-118.0,34.5" --format geojson
+```
+
+---
+
+## Key Features
+
+- **Cross-platform CLI** - Works on Windows, Linux, and macOS
+- **Multiple output formats** - Export to CSV, TSV, JSON, or GeoJSON
+- **Full Shapefile support** - Read geometry data and perform spatial queries
+- **Spatial operations** - Bounding box filtering, nearest neighbor searches, R-tree indexing
+- **Universal DBF compatibility** - Supports all major versions (dBASE III, IV, Visual FoxPro, Clipper)
+- **Memo file support** - Handles large text fields (.dbt, .fpt memo files)
+- **Legacy encoding** - Properly handles various character encodings (CP437, CP1252, etc.)
+- **High performance** - Optimized streaming for large files (millions of records)
+- **Pipeline friendly** - Works with stdin/stdout for Unix-style data processing
+
+---
+
+## Installation
 
-Refer to [Core library](./DbfSharp.Core/README.md) for a more extensive documentation.
+### Global .NET Tool (Recommended)
 
-#### Installation
+Requires [.NET 9.0 SDK](https://dotnet.microsoft.com/download) or later:
 
 ```bash
-dotnet add package DbfSharp.Core
+dotnet tool install -g DbfSharp
+```
+
+Update to the latest version:
+
+```bash
+dotnet tool update -g DbfSharp
+```
+
+### Verify Installation
+
+```bash
+dbfsharp --version
+```
+
+---
+
+## Common Use Cases
+
+### Converting Legacy Data
+
+```bash
+# Convert to CSV for Excel/Google Sheets
+dbfsharp read legacy_data.dbf --format csv --output data.csv
+
+# Convert to JSON for modern applications
+dbfsharp read products.dbf --format json --output products.json
+
+# Extract specific fields only
+dbfsharp read employees.dbf --fields "ID,NAME,EMAIL,SALARY" --format csv
+```
+
+### Working with Shapefiles
+
+```bash
+# Export complete Shapefile to GeoJSON
+dbfsharp read buildings.shp --format geojson --output buildings.geojson
+
+# Filter by geographic bounding box (minX,minY,maxX,maxY)
+dbfsharp read parcels.shp --bounding-box "-122.5,37.7,-122.3,37.8" --format geojson
+
+# Find nearest features to a point
+dbfsharp read poi.shp --nearest-point "-118.25,34.05" --nearest-count 10 --format geojson
+
+# Extract attributes only (ignore geometry)
+dbfsharp read census.shp --fields "GEOID,POP2020,NAME" --format csv
+```
+
+### Data Analysis & Exploration
+
+```bash
+# Inspect file structure and metadata
+dbfsharp info data.dbf
+
+# View detailed statistics and sample records
+dbfsharp info data.dbf --verbose
+
+# Preview first 20 records
+dbfsharp read data.dbf --limit 20
+
+# Sample middle section of data
+dbfsharp read data.dbf --skip 1000 --limit 50
+```
+
+### Pipeline Integration
+
+```bash
+# Filter with grep
+dbfsharp read employees.dbf --format csv | grep "Engineer"
+
+# Process with jq
+dbfsharp read sales.dbf --format json | jq '.[] | select(.AMOUNT > 1000)'
+
+# Chain with other commands
+dbfsharp read data.dbf --format csv --fields "ID,NAME" | sort | uniq | head -10
+
+# Process from stdin
+cat remote_file.dbf | dbfsharp read --format json
+```
+
+### Handling Legacy Encoding
+
+```bash
+# Specify encoding for non-English text
+dbfsharp read legacy_german.dbf --encoding cp850 --format csv
+
+# Windows-1252 encoding (common in Windows applications)
+dbfsharp read windows_data.dbf --encoding cp1252 --format json
 ```
 
-#### DBF Usage
+---
+
+## Commands
+
+### `read` - Convert and Export Data
+
+Extract data from DBF files or Shapefiles and export to various formats.
+
+**Syntax:**
+```bash
+dbfsharp read [FILE] [OPTIONS]
+```
+
+**Key Options:**
+- `--format`, `-f` - Output format: `table` (default), `csv`, `tsv`, `json`, `geojson`
+- `--output`, `-o` - Output file path (stdout if not specified)
+- `--fields` - Comma-separated list of fields to include
+- `--limit`, `-l` - Maximum number of records
+- `--skip`, `-s` - Skip first N records
+- `--bounding-box` - Spatial filter: "minX,minY,maxX,maxY" (Shapefiles only)
+- `--nearest-point` - Find nearest features: "x,y" (Shapefiles only)
+- `--build-spatial-index` - Build R-tree index for faster queries
+
+📚 **[Full command documentation →](./DbfSharp.ConsoleAot/README.md#read---extract-and-export-data)**
+
+### `info` - Analyze File Structure
+
+Display comprehensive metadata, field definitions, and statistics about DBF files or Shapefiles.
+
+**Syntax:**
+```bash
+dbfsharp info [FILE] [OPTIONS]
+```
+
+**Key Options:**
+- `--verbose`, `-v` - Show additional details including sample data
+- `--fields` - Show field definitions (default: true)
+- `--stats` - Show record statistics (default: true)
+- `--memo` - Show memo file information (default: true)
+
+📚 **[Full command documentation →](./DbfSharp.ConsoleAot/README.md#info---analyze-file-structure)**
+
+---
+
+## Supported Formats
+
+### Input Formats
+
+**DBF Files:**
+- dBASE II, III, III+, IV, 5
+- FoxBase, FoxPro 2.x
+- Visual FoxPro 3-9
+- Clipper
+- All standard field types (Character, Date, Numeric, Logical, Memo, etc.)
+
+**Shapefiles:**
+- Geometry types: Point, MultiPoint, LineString, Polygon, MultiPatch
+- Spatial components: .shp (geometry), .shx (index), .dbf (attributes)
+- Projection files: .prj (coordinate system)
+- Character encoding: .cpg files
+
+**Memo Files:**
+- .dbt (dBASE III, IV)
+- .fpt (Visual FoxPro)
+
+### Output Formats
+
+- **CSV** - Comma-separated values
+- **TSV** - Tab-separated values
+- **JSON** - Array of objects with field names as keys
+- **GeoJSON** - For Shapefiles with geometry (RFC 7946 compliant)
+- **Table** - Human-readable console table
+
+---
+
+## Performance
+
+DbfSharp is optimized for high throughput and low memory usage:
+
+- **Streaming processing** - Handle files larger than available RAM
+- **Memory-mapped files** - Efficient access for large datasets
+- **R-tree spatial indexing** - Fast spatial queries on Shapefiles
+- **Native AOT compilation** - Minimal startup overhead
+
+**Benchmark (1 million records, 10 fields):**
+- Sequential read: ~1.3M records/sec
+- Memory-optimized: ~3.3M records/sec with 24MB RAM
+- CSV export: ~800K records/sec
+- JSON export: ~600K records/sec
+
+💡 **Tip:** Use `--build-spatial-index` for large Shapefiles with spatial queries to significantly improve performance.
+
+---
+
+## .NET Library
+
+DbfSharp also provides a high-performance .NET library for programmatic access in your applications:
 
 ```csharp
 using DbfSharp.Core;
 
+// Read DBF file
 using var reader = DbfReader.Create("data.dbf");
 foreach (var record in reader.Records)
 {
     var name = record.GetString("NAME");
-    var birthDate = record.GetDateTime("BIRTHDATE");
-    Console.WriteLine($"{name}, born {birthDate}");
+    var date = record.GetDateTime("DATE");
+    Console.WriteLine($"{name}: {date}");
 }
-```
 
-#### Shapefile Usage
+// Read Shapefile with spatial queries
+using var shpReader = ShapefileReader.Open("cities.shp");
+shpReader.BuildSpatialIndex();
 
-```csharp
-using DbfSharp.Core;
+var bbox = new BoundingBox(-100, 40, -90, 50);
+var features = shpReader.QuerySpatialIndex(bbox);
 
-// Read shapefile with geometry and attributes
-using var reader = ShapefileReader.Open("cities.shp");
-foreach (var feature in reader.Features)
+foreach (var feature in features)
 {
-    var geometry = feature.Geometry; // Point, LineString, Polygon, etc.
+    var geometry = feature.Geometry;
     var population = feature.GetAttribute<int>("POPULATION");
-    Console.WriteLine($"City at {geometry}: {population:N0} people");
+    Console.WriteLine($"{geometry}: {population:N0} people");
 }
 ```
 
-#### Spatial Operations
-
-```csharp
-// Build spatial index for fast queries
-reader.BuildSpatialIndex();
-
-// Find features within bounding box
-var bbox = new BoundingBox(minX: -100, minY: 40, maxX: -90, maxY: 50);
-var features = reader.QuerySpatialIndex(bbox);
+📚 **[Complete .NET library documentation →](./DbfSharp.Core/README.md)**
 
-// Find nearest features to a point
-var point = new Point(-95.5, 45.2);
-var nearest = reader.FindNearestFeatures(new Coordinate(point.X, point.Y), count: 5);
+**Install via NuGet:**
+```bash
+dotnet add package DbfSharp.Core
 ```
 
-### Command-Line Tool
+---
 
-Refer to [ConsoleAot](./DbfSharp.ConsoleAot/README.md) for a more extensive documentation.
+## Examples & Resources
 
-#### Installation
+- **CLI Documentation:** [DbfSharp.ConsoleAot/README.md](./DbfSharp.ConsoleAot/README.md)
+- **Library Documentation:** [DbfSharp.Core/README.md](./DbfSharp.Core/README.md)
+- **Issue Tracker:** [GitHub Issues](https://github.com/emmorts/DbfSharp/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/emmorts/DbfSharp/discussions)
 
-```bash
-dotnet tool install -g DbfSharp
-```
+---
 
-#### Usage
+## Contributing
 
-```bash
-# read a DBF file, default output to console as a table
-dbfsharp read data.dbf
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
 
-# export to CSV
-dbfsharp read data.dbf --format csv --output data.csv
+---
 
-# read shapefile with geometry
-dbfsharp read buildings.shp --format geojson --output buildings.geojson
+## License
 
-# spatial queries on shapefiles
-dbfsharp read parcels.shp --bounding-box "-118.5,34.0,-118.0,34.5" --format geojson
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-# get file information
-dbfsharp info data.dbf --verbose
-```
+---
 
-## Supported Formats
+## About DBF Format History
 
-### DBF Files
-- dBase II, III, IV
-- FoxBase, FoxPro
-- Visual FoxPro
-- Memo files (.dbt, .fpt)
-- All standard field types (Character, Date, Numeric, Logical, Memo, etc.)
+The DBF format was introduced by Ashton-Tate for dBASE II in 1983. Despite its age, it remains widely used in:
+
+- **GIS applications** - ESRI Shapefiles use DBF for attribute data
+- **Legacy systems** - Many government and business databases still use DBF
+- **Data exchange** - Simple format makes it useful for data interchange
+- **Embedded systems** - Small footprint suitable for resource-constrained environments
 
-### Shapefiles
-- **Geometry Types**: Point, MultiPoint, LineString, Polygon, MultiPatch
-- **Spatial Index**: R-tree indexing for fast spatial queries
-- **Complete Support**: .shp (geometry), .shx (index), .dbf (attributes)
-- **Coordinate Systems**: .prj files with projection support
-- **Encoding**: .cpg files for proper character encoding
+DbfSharp makes it easy to work with this data using modern tools and workflows.

From 1a276d0daf1eadb032353a723425184ccc9a9a25 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 10 Nov 2025 13:29:57 +0000
Subject: [PATCH 2/4] docs: refocus README on Shapefiles as primary use case

- Lead with Shapefile support in tagline and features
- Reorder Quick Start to show Shapefile examples first
- Reorganize Common Use Cases to prioritize Shapefile operations
- Remove verbose DBF history and encoding sections
- Update feature list to emphasize spatial operations
- Simplify messaging for users who already know DBF/Shapefile formats
---
 README.md | 105 ++++++++++++++++++++----------------------------------
 1 file changed, 38 insertions(+), 67 deletions(-)

diff --git a/README.md b/README.md
index e612167..9ef6b5c 100644
--- a/README.md
+++ b/README.md
@@ -3,15 +3,9 @@
 [![DeepWiki](https://img.shields.io/badge/DeepWiki-emmorts%2Fdbfsharp-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/emmorts/dbfsharp)
 ![NuGet Version](https://img.shields.io/nuget/v/dbfsharp.core)
 
-**A modern, high-performance command-line tool for working with DBF database files and Shapefiles.**
+**A modern, high-performance command-line tool for working with Shapefiles and DBF database files.**
 
-Convert legacy dBASE files to modern formats (CSV, JSON, GeoJSON), analyze file structures, and perform spatial queries—all from your terminal.
-
----
-
-## What is DBF?
-
-DBF (dBASE Database File) is a legacy database format created in 1983, still widely used in GIS applications, legacy business systems, and government data. DbfSharp makes it easy to extract and convert this data to modern formats without needing specialized database software.
+Convert Shapefiles to GeoJSON, extract data from DBF files to CSV/JSON, perform spatial queries, and analyze geospatial data—all from your terminal.
 
 ---
 
@@ -21,32 +15,32 @@ DBF (dBASE Database File) is a legacy database format created in 1983, still wid
 # Install globally
 dotnet tool install -g DbfSharp
 
-# Convert DBF to CSV
-dbfsharp read customers.dbf --format csv --output customers.csv
-
-# Analyze file structure
-dbfsharp info data.dbf
-
 # Export Shapefile to GeoJSON
 dbfsharp read cities.shp --format geojson --output cities.geojson
 
-# Spatial query on Shapefile
+# Spatial query - filter by bounding box
 dbfsharp read parcels.shp --bounding-box "-118.5,34.0,-118.0,34.5" --format geojson
+
+# Convert DBF to CSV
+dbfsharp read data.dbf --format csv --output data.csv
+
+# Analyze file structure
+dbfsharp info cities.shp
 ```
 
 ---
 
 ## Key Features
 
-- **Cross-platform CLI** - Works on Windows, Linux, and macOS
-- **Multiple output formats** - Export to CSV, TSV, JSON, or GeoJSON
-- **Full Shapefile support** - Read geometry data and perform spatial queries
-- **Spatial operations** - Bounding box filtering, nearest neighbor searches, R-tree indexing
-- **Universal DBF compatibility** - Supports all major versions (dBASE III, IV, Visual FoxPro, Clipper)
-- **Memo file support** - Handles large text fields (.dbt, .fpt memo files)
-- **Legacy encoding** - Properly handles various character encodings (CP437, CP1252, etc.)
+- **Complete Shapefile support** - Read geometry, attributes, and perform spatial operations
+- **Spatial queries** - Bounding box filtering, nearest neighbor searches, R-tree spatial indexing
+- **GeoJSON export** - Convert Shapefiles to modern GeoJSON format
+- **Multiple output formats** - Export to GeoJSON, CSV, TSV, JSON, or console tables
+- **Universal DBF compatibility** - Supports all DBF versions (dBASE III/IV, Visual FoxPro, Clipper)
 - **High performance** - Optimized streaming for large files (millions of records)
+- **Cross-platform CLI** - Works on Windows, Linux, and macOS
 - **Pipeline friendly** - Works with stdin/stdout for Unix-style data processing
+- **Legacy encoding support** - Properly handles various character encodings
 
 ---
 
@@ -76,19 +70,6 @@ dbfsharp --version
 
 ## Common Use Cases
 
-### Converting Legacy Data
-
-```bash
-# Convert to CSV for Excel/Google Sheets
-dbfsharp read legacy_data.dbf --format csv --output data.csv
-
-# Convert to JSON for modern applications
-dbfsharp read products.dbf --format json --output products.json
-
-# Extract specific fields only
-dbfsharp read employees.dbf --fields "ID,NAME,EMAIL,SALARY" --format csv
-```
-
 ### Working with Shapefiles
 
 ```bash
@@ -105,6 +86,19 @@ dbfsharp read poi.shp --nearest-point "-118.25,34.05" --nearest-count 10 --forma
 dbfsharp read census.shp --fields "GEOID,POP2020,NAME" --format csv
 ```
 
+### Converting DBF Data
+
+```bash
+# Convert to CSV for Excel/Google Sheets
+dbfsharp read data.dbf --format csv --output data.csv
+
+# Convert to JSON for modern applications
+dbfsharp read products.dbf --format json --output products.json
+
+# Extract specific fields only
+dbfsharp read employees.dbf --fields "ID,NAME,EMAIL,SALARY" --format csv
+```
+
 ### Data Analysis & Exploration
 
 ```bash
@@ -137,16 +131,6 @@ dbfsharp read data.dbf --format csv --fields "ID,NAME" | sort | uniq | head -10
 cat remote_file.dbf | dbfsharp read --format json
 ```
 
-### Handling Legacy Encoding
-
-```bash
-# Specify encoding for non-English text
-dbfsharp read legacy_german.dbf --encoding cp850 --format csv
-
-# Windows-1252 encoding (common in Windows applications)
-dbfsharp read windows_data.dbf --encoding cp1252 --format json
-```
-
 ---
 
 ## Commands
@@ -248,15 +232,6 @@ DbfSharp also provides a high-performance .NET library for programmatic access i
 ```csharp
 using DbfSharp.Core;
 
-// Read DBF file
-using var reader = DbfReader.Create("data.dbf");
-foreach (var record in reader.Records)
-{
-    var name = record.GetString("NAME");
-    var date = record.GetDateTime("DATE");
-    Console.WriteLine($"{name}: {date}");
-}
-
 // Read Shapefile with spatial queries
 using var shpReader = ShapefileReader.Open("cities.shp");
 shpReader.BuildSpatialIndex();
@@ -270,6 +245,15 @@ foreach (var feature in features)
     var population = feature.GetAttribute<int>("POPULATION");
     Console.WriteLine($"{geometry}: {population:N0} people");
 }
+
+// Read DBF file
+using var reader = DbfReader.Create("data.dbf");
+foreach (var record in reader.Records)
+{
+    var name = record.GetString("NAME");
+    var date = record.GetDateTime("DATE");
+    Console.WriteLine($"{name}: {date}");
+}
 ```
 
 📚 **[Complete .NET library documentation →](./DbfSharp.Core/README.md)**
@@ -299,16 +283,3 @@ Contributions are welcome! Please feel free to submit a Pull Request. For major
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
----
-
-## About DBF Format History
-
-The DBF format was introduced by Ashton-Tate for dBASE II in 1983. Despite its age, it remains widely used in:
-
-- **GIS applications** - ESRI Shapefiles use DBF for attribute data
-- **Legacy systems** - Many government and business databases still use DBF
-- **Data exchange** - Simple format makes it useful for data interchange
-- **Embedded systems** - Small footprint suitable for resource-constrained environments
-
-DbfSharp makes it easy to work with this data using modern tools and workflows.

From 83b98e9d3520122b0692cebaf8103207090d95e3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 10 Nov 2025 13:32:28 +0000
Subject: [PATCH 3/4] docs: prioritize Homebrew as primary installation method

- Move Homebrew to top as recommended installation method
- Reposition .NET tool install as alternative for SDK users
- Remove .NET SDK requirement from recommended path
- Make installation more accessible to general users
---
 README.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 9ef6b5c..c90fc4e 100644
--- a/README.md
+++ b/README.md
@@ -46,9 +46,15 @@ dbfsharp info cities.shp
 
 ## Installation
 
-### Global .NET Tool (Recommended)
+### Homebrew (Recommended)
 
-Requires [.NET 9.0 SDK](https://dotnet.microsoft.com/download) or later:
+```bash
+brew install dbfsharp
+```
+
+### .NET Tool (Alternative)
+
+If you have .NET 9.0 SDK or later installed:
 
 ```bash
 dotnet tool install -g DbfSharp

From 58c817652c2f7feb10d42086c0eec0a15e1704c7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 10 Nov 2025 13:33:35 +0000
Subject: [PATCH 4/4] docs: update Quick Start to use Homebrew installation

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index c90fc4e..a6954cf 100644
--- a/README.md
+++ b/README.md
@@ -12,8 +12,8 @@ Convert Shapefiles to GeoJSON, extract data from DBF files to CSV/JSON, perform
 ## Quick Start
 
 ```bash
-# Install globally
-dotnet tool install -g DbfSharp
+# Install
+brew install dbfsharp
 
 # Export Shapefile to GeoJSON
 dbfsharp read cities.shp --format geojson --output cities.geojson