Update README.md for clarity and organization; enhance CLI examples and instructions

Author: EricLott

README.md

@@ -1,76 +1,169 @@
-# Dataverse Wrapper Generator
+# Dataverse Plugin Wrapper Generator
 
-A C# console application that generates strongly typed entity classes and option set enums from a Dataverse solution zip (`customizations.xml`).
+Generate strongly typed C# wrappers and option set enums from a Dataverse solution zip (`customizations.xml`).
 
-## Features
+This tool reads Dataverse metadata and writes:
+- `OptionSets/OptionValueSets.cs` with global option set enums and state enums
+- `Entities/*.cs` wrapper classes with CRUD helpers (`Create`, `Retrieve`, `Update`, `Delete`)
 
-- Parses `customizations.xml` from a Dataverse solution zip.
-- Generates option set enums in `OptionSets/OptionValueSets.cs`.
-- Generates entity wrapper classes with `Create`, `Retrieve`, `Update`, and `Delete` methods.
-- Supports overwrite prompts (or `--yes` to skip prompts).
-- Supports entity filtering with `--filter`.
+## What This Project Is
 
-## Getting Started
+- A .NET console app (`DataversePluginWrapper`) that parses Dataverse solution metadata.
+- A code generator only. It does not deploy to Dataverse.
+- Supports both:
+  - CLI mode (arguments)
+  - Interactive mode (no arguments)
 
-### 1. Clone and build
+## Prerequisites
+
+- .NET 6 SDK or later installed
+- A Dataverse solution zip containing `customizations.xml`
+
+Check SDK:
+
+```sh
+dotnet --version
+```
+
+## Build
 
 ```sh
-git clone https://github.com/EricLott/DataversePluginWrapper.git
-cd DataversePluginWrapper
+dotnet restore
 dotnet build
 ```
 
-### 2. Run
+## Run
+
+### Interactive mode (recommended for first-time use)
+
+Run with no arguments:
 
 ```sh
-dotnet run -- -z path/to/your/solution.zip -o ./Generated
+dotnet run --
 ```
 
-## Usage
+You will be prompted for:
+- solution zip path
+- output directory
+- optional entity-name filter
+- verbose logging toggle
+- overwrite behavior
+- final confirmation
 
-```text
-DataverseWrapper -z <path_to_solution_zip> [options]
-DataverseWrapper                         (interactive mode)
+### CLI mode
 
-Options:
-  -z, --zip <path>         Path to Dataverse solution zip (required)
-  -o, --out <dir>          Output directory (default: ./GeneratedClasses_{timestamp})
-  -f, --filter <text>      Only generate for entities whose display name contains text
-  -v, --verbose            Verbose logging
-  -y, --yes                Overwrite existing files without prompt
-  -h, --help               Show help
+```sh
+dotnet run -- -z <path_to_solution_zip> [options]
 ```
 
-If you run the executable with no arguments, it starts a guided interactive flow and prompts for zip path, output folder, optional filter, and overwrite behavior.
+Options:
+
+- `-z, --zip <path>`: path to Dataverse solution zip (required)
+- `-o, --out <dir>`: output directory (default: `./GeneratedClasses_{timestamp}`)
+- `-f, --filter <text>`: generate only entities whose display name contains text
+- `-v, --verbose`: verbose logging
+- `-y, --yes`: overwrite existing files without prompt
+- `-h, --help`: show help
 
-### Examples
+### CLI examples
 
-Generate all:
+Generate everything:
 
 ```sh
 dotnet run -- -z ./MySolution.zip
 ```
 
-Generate entities containing "Contact":
+Generate only entities containing `Contact`:
 
 ```sh
 dotnet run -- -z ./MySolution.zip -f Contact
 ```
 
-Overwrite without prompts:
+Write to a fixed folder and overwrite existing files:
 
 ```sh
-dotnet run -- -z ./MySolution.zip -o ./OutDir -y
+dotnet run -- -z ./MySolution.zip -o ./Generated -y
 ```
 
-## Output Structure
+## Publish an EXE
+
+Windows x64 example:
+
+```sh
+dotnet publish -c Release -r win-x64 --self-contained false
+```
+
+Output executable will be under:
+
+`bin/Release/net6.0/win-x64/publish/`
+
+Run the EXE directly:
+- no args -> interactive mode
+- with args -> CLI mode
+
+## Output Layout
 
 ```text
-GeneratedClasses_20250919/
+GeneratedClasses_20260221_153000/
 |-- OptionSets/
 |   `-- OptionValueSets.cs
 `-- Entities/
     |-- Account.cs
     |-- Contact.cs
     `-- ...
 ```
+
+## Generated Code Notes
+
+- Generated entity wrappers use Dataverse SDK types (`IOrganizationService`, `Entity`, `EntityReference`, `OptionSetValue`, etc.).
+- Option set/state values are mapped to enums where possible.
+- Status reason is generated as numeric backing (`int?`) with enum helper behavior.
+- Lookups/owners/customers are generated as `EntityReference`.
+
+## Consuming Generated Files
+
+In the project where you use generated files, ensure Dataverse SDK references are available (for example, `Microsoft.Xrm.Sdk`).
+
+If your consuming project does not reference SDK assemblies, generated files will not compile.
+
+## Exit Codes
+
+- `0`: success
+- `1`: unexpected error
+- `2`: argument/path error
+- `3`: XML parsing error
+- `4`: invalid data shape
+- `130`: user canceled (Ctrl+C or interactive cancel)
+
+## Troubleshooting
+
+### "customizations.xml not found in zip"
+
+- Ensure the zip is a Dataverse solution export.
+- Verify the archive includes `customizations.xml`.
+
+### No entities generated
+
+- Check whether `--filter` excluded all entities.
+- Run without filter to validate metadata extraction.
+
+### Existing files are skipped
+
+- Use `-y`/`--yes`, or answer `y` at overwrite prompts.
+
+### Build succeeds but generated code fails in another project
+
+- Add Dataverse SDK references to the consuming project.
+- Validate that generated namespace/import placement matches your project conventions.
+
+## Development
+
+Local project files:
+- `Program.cs`: generator implementation
+- `DataversePluginWrapper.csproj`: project configuration
+
+Build locally before committing:
+
+```sh
+dotnet build
+```