docs: adding comprehensive documentation for usage (#21)

Author: xBlaz3kx

README.md

@@ -56,6 +56,8 @@ Available Commands:
 Flags:
   -d, --debug            Enable debug mode
   -h, --help             help for chargeflow
+  -m, --model string     Charging-station model for vendor/model-specific schema selection
+  -V, --vendor string    Charging-station vendor for vendor/model-specific schema selection
   -v, --version string   OCPP version to use (1.6, 2.0.1 or 2.1) (default "1.6")
 ```
 
@@ -72,6 +74,12 @@ Additionally, you can specify a custom path to vendor-specific OCPP schemas usin
 > You can also validate multiple OCPP messages from a file using the `-f` flag.
 > The file should be a newline-separated list of JSON strings.
 
+For more detailed usage, see the documentation:
+
+- [Validating messages from a file](docs/validate-from-file.md)
+- [Custom and vendor-specific schemas](docs/custom-schemas.md)
+- [Remote schema registry](docs/remote-registry.md)
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.

docs/custom-schemas.md

@@ -0,0 +1,50 @@
+# Custom and vendor-specific schemas
+
+ChargeFlow ships with built-in schemas for all supported OCPP versions. You can extend or override
+these with your own JSON schemas to handle vendor-specific extensions or non-standard field
+constraints.
+
+## Vendor- and model-specific validation
+
+Pass `--vendor` (`-V`) and/or `--model` (`-m`) to select schemas scoped to a specific charging
+station. When both flags are provided, ChargeFlow looks for schemas registered under that
+vendor/model combination before falling back to the standard built-in schemas.
+
+```bash
+chargeflow --vendor Acme --model FastCharger validate \
+  '[2, "1", "BootNotification", {"chargePointVendor": "Acme", "chargePointModel": "FastCharger"}]'
+```
+
+## Loading schemas from a local directory
+
+Use `--schemas` (`-a`) on the `validate` command to point ChargeFlow at a folder of custom JSON
+schema files. File names must match the OCPP action name they cover, e.g.
+`BootNotificationRequest.json`. Custom schemas **replace** the built-in schemas for the actions
+they cover.
+
+```bash
+chargeflow validate --schemas ./vendor-schemas \
+  '[2, "1", "BootNotification", {"chargePointVendor": "Acme", "chargePointModel": "FastCharger"}]'
+```
+
+Combining vendor/model flags with a custom schema folder is the typical pattern for validating
+messages from a specific charging station:
+
+```bash
+chargeflow --vendor Acme --model FastCharger \
+  validate --schemas ./vendor-schemas -f messages.txt -o report.json
+```
+
+## Schema file naming convention
+
+Schema files must be named after the OCPP action with a `.json` extension:
+
+```
+BootNotificationRequest.json
+BootNotificationResponse.json
+DataTransfer.json
+...
+```
+
+ChargeFlow strips the `.json` suffix and uses the remaining string as the action name when
+registering the schema internally.

docs/remote-registry.md

@@ -0,0 +1,130 @@
+# Remote schema registry
+
+ChargeFlow can push schemas to and remove schemas from a Kafka-compatible schema registry such as
+[Confluent Schema Registry](https://docs.confluent.io/platform/current/schema-registry/index.html)
+or [Redpanda Schema Registry](https://docs.redpanda.com/current/manage/schema-reg/).
+
+All `schema` subcommands share a set of common flags for the registry URL and authentication.
+
+## Common flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--url` | Remote schema registry URL (required) | — |
+| `--auth-type` | Authentication type: `basic`, `bearer`, `api-key`, or omit for none | — |
+| `--username` | Username for basic authentication | — |
+| `--password` | Password for basic authentication | — |
+| `--bearer-token` | Bearer token | — |
+| `--api-key` | API key value | — |
+| `--api-key-header` | Header name for the API key | `X-API-Key` |
+| `--custom-header` | Custom header name | — |
+| `--custom-value` | Custom header value | — |
+| `--timeout` | Request timeout | `5s` |
+
+## Registering schemas
+
+Use `schema register` to upload JSON schemas to the registry.
+
+### Register a single schema file
+
+`--action` is required when registering a single file.
+
+```bash
+chargeflow schema --url http://localhost:8081 \
+  register --file BootNotificationRequest.json --action BootNotificationRequest
+```
+
+### Register all schemas from a directory
+
+ChargeFlow reads every `.json` file in the directory and derives the action name from the file name.
+
+```bash
+chargeflow schema --url http://localhost:8081 --version 2.0.1 \
+  register --dir ./schemas
+```
+
+### Register vendor-specific schemas
+
+Supply `--vendor` and `--model` on the root command to scope the schemas to a specific charging
+station make and model.
+
+```bash
+chargeflow --vendor Acme --model FastCharger \
+  schema --url http://localhost:8081 \
+  register --dir ./vendor-schemas
+```
+
+## Deleting schemas
+
+Use `schema remove` to delete schemas from the registry. Exactly one of `--action`, `--file`, or
+`--dir` must be specified.
+
+### Delete by action name
+
+```bash
+chargeflow schema --url http://localhost:8081 \
+  remove --action BootNotificationRequest
+```
+
+### Derive the action from a file name
+
+ChargeFlow strips the `.json` suffix and uses the result as the action name.
+
+```bash
+chargeflow schema --url http://localhost:8081 \
+  remove --file BootNotificationRequest.json
+```
+
+### Delete all schemas matching a directory
+
+Removes every schema whose action name matches a `.json` file found in the directory.
+
+```bash
+chargeflow schema --url http://localhost:8081 \
+  remove --dir ./schemas
+```
+
+### Delete vendor-specific schemas
+
+```bash
+chargeflow --vendor Acme --model FastCharger \
+  schema --url http://localhost:8081 \
+  remove --action DataTransfer
+```
+
+## Authentication examples
+
+### Basic authentication
+
+```bash
+chargeflow schema --url http://registry:8081 \
+  --auth-type basic --username admin --password secret \
+  register --dir ./schemas
+```
+
+### Bearer token
+
+```bash
+chargeflow schema --url https://registry.example.com \
+  --auth-type bearer --bearer-token eyJ... \
+  register --file MySchema.json --action MyAction
+```
+
+### API key
+
+The default header is `X-API-Key`. Override it with `--api-key-header` if your registry uses a
+different header name.
+
+```bash
+chargeflow schema --url https://registry.example.com \
+  --auth-type api-key --api-key abc123 \
+  register --dir ./schemas
+```
+
+### Custom header
+
+```bash
+chargeflow schema --url https://registry.example.com \
+  --custom-header X-Registry-Auth --custom-value my-secret \
+  register --dir ./schemas
+```

docs/validate-from-file.md

@@ -0,0 +1,39 @@
+# Validating messages from a file
+
+Use the `-f` flag to read OCPP messages from a file instead of passing them as a command-line
+argument. Each line must be a single, complete OCPP JSON string; blank lines are ignored.
+
+```bash
+chargeflow validate -f messages.txt
+```
+
+Example `messages.txt`:
+
+```
+[2, "1", "BootNotification", {"chargePointVendor": "TestVendor", "chargePointModel": "TestModel"}]
+[2, "2", "Heartbeat", {}]
+[3, "1", {"status": "Accepted", "currentTime": "2024-01-01T00:00:00Z", "interval": 300}]
+```
+
+> [!NOTE]
+> Response messages (type `3`) require the `--response-type` flag so ChargeFlow knows which schema
+> to validate against, e.g. `--response-type BootNotificationResponse`.
+
+## Saving the report to a file
+
+Use `-o` to write the validation report to a file instead of stdout. Supported extensions are
+`.json`, `.csv`, and `.txt`.
+
+```bash
+chargeflow validate -f messages.txt -o report.json
+chargeflow validate -f messages.txt -o report.csv
+chargeflow validate -f messages.txt -o report.txt
+```
+
+## Specifying the OCPP version
+
+The default version is `1.6`. Use `--version` (`-v`) to change it.
+
+```bash
+chargeflow --version 2.0.1 validate -f messages.txt -o report.json
+```