docs: update README.md

[olivermeyer]

Summary

Adds comprehensive configuration reference documentation to README.md, making it easier for users to understand all available environment variables and settings.

Changes

• Restructured "Usage" section with clearer Quickstart guide
• Added "Configuration reference" section documenting all env vars
• Documented env file search order and priority
• Improved testing pattern documentation
• Updated version to 0.12.0 in ATTRIBUTIONS.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

[claude]

Claude finished @olivermeyer's task in 2m 42s —— View job

---

Code Review: PR #50

Post-merge review of documentation improvements.

Tasks

• Read project standards (CLAUDE.md)
• Analyze git diff for all changes
• Review documentation quality and accuracy
• Check for security, performance, and breaking changes
• Verify conventional commit compliance
• Provide review feedback

---

Review Summary

Overall Assessment: ✅ Excellent - This PR significantly improves the README with comprehensive configuration documentation. All CI checks passed, and the changes align with project standards.

Strengths

1. Well-Structured Documentation

   • Clear hierarchical organization with ### (Quickstart) and #### (subsections)
   • Logical flow from basic usage to detailed configuration
   • Consistent formatting throughout

2. Comprehensive Configuration Reference ⭐

   • Documents all environment variables across all settings classes
   • Includes defaults, descriptions, and requirements
   • Tables are well-formatted and easy to scan
   • Accurately reflects the actual code implementation

3. Improved User Experience

   • Env file search order is now explicit and prioritized
   • Testing pattern is better explained
   • Clearer explanation of FoundryContext as "single source of truth"
   • Better examples with actual expected output

4. Code Accuracy Verification ✅

   • Verified all documented settings against source code:
     • LogSettings (log.py:76-223) - all fields match
     • SentrySettings (sentry.py:118-223) - all fields match
     • DatabaseSettings (database.py:29-115) - all fields match
     • AuthSettings (api/auth.py:33-50) - all fields match
     • FoundryContext.from_package() env vars (foundry.py:152-200) - all match

5. Conventional Commits Compliance ✅

   • Commit message: "docs: update README.md" follows conventional commits perfectly
   • Type: docs (documentation changes)
   • Scope: implicit (README)
   • Description: clear and concise

6. Quality Gates ✅

   • SonarQube: Quality gate passed, 0 new issues
   • Codecov: All lines covered, all tests successful
   • No security, performance, or breaking changes introduced

Suggestions for Future Improvements

While this PR is excellent, here are some optional enhancements for future consideration:

1. Add Links to Code Examples (Nice-to-have)

   See [`src/aignostics_foundry_core/foundry.py`](src/aignostics_foundry_core/foundry.py) for implementation details.

2. Consider Adding Validation Rules (Nice-to-have)
   For settings like {PREFIX}SENTRY_DSN, you could mention:

   | `{PREFIX}SENTRY_DSN` | unset | Sentry DSN (must be HTTPS URL with valid `ingest.*.sentry.io` domain). |

   The current description is good, but explicitly calling out the validation might help users avoid configuration errors.

3. Version Full Format Example (Minor clarification)
   README:235:76 - The example 1.2.3+main-abc1234---run.12345---build.42 is excellent. Consider adding a note that the --- delimiters are literal (not placeholders) to avoid confusion.

4. Removed Content (Informational)
   The old "Health API" section (showing Health and HealthStatus usage) was removed. This is likely intentional to keep README focused on core usage, since health checks are well-documented in FOUNDRY_README.md. Just noting this for awareness.

Security Review ✅

• No hardcoded secrets or credentials
• All sensitive values properly documented as SecretStr types
• DSN validation requirements explicitly mentioned
• No security concerns introduced

Breaking Changes ✅

• None - Documentation-only changes
• All existing functionality remains unchanged
• No API changes, no behavior changes

Documentation Quality ✅

• ✅ Clear and concise language
• ✅ Consistent formatting
• ✅ Accurate technical details
• ✅ Follows project documentation standards (CLAUDE.md)
• ✅ Tables are properly formatted
• ✅ Code blocks have proper syntax highlighting

Testing Coverage ✅

• This is a documentation PR - no code changes
• ATTRIBUTIONS.md version bump (0.11.0 → 0.12.0) is auto-generated
• All existing tests continue to pass

---

Verdict

Approved ✅ (Post-merge)

This PR represents a significant improvement in documentation quality. The comprehensive configuration reference will greatly help users understand and correctly configure the library. All documented settings are accurate, and the restructuring makes the README much more user-friendly.

The commit message follows conventional commits, all CI checks passed, and there are no security or breaking change concerns. Excellent work!

---

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud