move top-level modules into a real package

plans/17-exit-code-conventions.md

@@ -0,0 +1,32 @@
+# 17. Add Exit Code Conventions
+
+## Summary
+
+Document and implement consistent exit codes so scripts can distinguish success from expected user errors.
+
+## Implementation Steps
+
+- Define named constants or an enum for exit codes.
+- Use `0` for success.
+- Use `1` for expected user-facing errors initially.
+- Optionally reserve distinct documented codes for validation errors, missing collections, and file errors if the CLI needs them.
+- Update error handling to return constants instead of literal integers.
+- Document exit code behavior in README.
+
+## Public Interface Changes
+
+- Existing successful commands still exit `0`.
+- Existing handled errors may continue to exit `1` unless distinct codes are explicitly adopted.
+- README documents the convention.
+
+## Test Plan
+
+- Test success returns `0`.
+- Test expected user errors return the documented code.
+- Test unexpected exceptions still propagate to the runtime.
+- Manually verify shell exit status for representative commands.
+
+## Assumptions
+
+- Start with `0` and `1` unless there is a clear automation need for more granular codes.
+- This plan should follow the exception cleanup plan so errors are categorized at the app level.