Refactor lib for better readability

**Problem**
When working with validation, the error messages could be more descriptive.

**Suggestion**
Improve error handling and add detailed error messages.

**Context**
This would help with debugging and maintenance.

The issue names no files, tests, or entry points. Start by locating validation and error-handling code in lib, then identify existing tests or command paths covering validation. Done means validation failures produce more descriptive messages without regressing existing checks.

Written by the indexing model from the issue text.