Add configuration and usage guide for CLI and MCP

[PrzemyslawKlys]

Summary

• add a dedicated configuration and usage guide for Mailozaurr profiles, providers, CLI storage, and MCP usage
• link the new guide from the README architecture and documentation entry points
• document practical recipes for IMAP, SMTP, Graph, and Gmail profile setup

Notes

• docs only
• no code changes

[claude]

Claude finished @PrzemyslawKlys's task —— View job

---

PR Review: Documentation Updates

Review Checklist:

• Read repository guidelines (CLAUDE.md) - No specific guidelines found
• Review new Configuration-and-Usage.md file
• Review README.MD modifications
• Check for security concerns in configuration examples
• Assess documentation quality and structure
• Provide comprehensive feedback

Overall Assessment

This is a well-structured documentation update that significantly improves the project's usability. The new Configuration-and-Usage.md provides comprehensive guidance for the CLI and MCP surfaces, which was clearly needed given the complexity of the profile system.

Strengths

Documentation Quality

• Excellent structure: Logical flow from core concepts → supported providers → usage examples
• Comprehensive coverage: Covers all major providers (IMAP, POP3, SMTP, Graph, Gmail, SendGrid, etc.)
• Practical examples: Real CLI commands that users can copy and adapt
• Clear capability matrix: Table at Docs/Configuration-and-Usage.md:55-64 clearly shows what each provider supports

Content Organization

• Profile-centric approach: Correctly emphasizes the reusable profile model as the foundation
• Provider-specific guidance: Minimal configuration requirements for each provider type
• Recipe format: Practical examples show both profile creation and secret management

Integration with Existing Docs

• Good cross-references: Links to relevant source files and other documentation
• README enhancements: Adds 112 lines of CLI/MCP usage examples that fill a major gap

Security Considerations

⚠️ Security Concerns Found

1. Hardcoded secrets in examples (Docs/Configuration-and-Usage.md:206, 221, 232, 245):

   --setting userName=user@example.com `
   --secret password --value "secret" --json  # ← Avoid showing actual secret values

   Recommendation: Use placeholder values like --value "<your-password-here>" or reference environment variables

2. Command history exposure (Multiple locations):

   • CLI examples show secrets passed as command-line arguments
   • These could be exposed in shell history, process lists, or logs
     Recommendation: Document secure alternatives like reading from stdin or files:

   # Better approach
   mailozaurr profile set-secret --profile work-imap --name password --stdin
   # Or from file
   mailozaurr profile set-secret --profile work-imap --name password --from-file secrets.txt

3. Missing security guidance:

   • No mention of profile storage security
   • No guidance on secret rotation or expiration
     Recommendation: Add a security section covering profile protection and secret management best practices

Technical Issues

Path References

• Windows-specific paths (Docs/Configuration-and-Usage.md:29-32, 314-317):

  [MailProfile.cs](C:\Support\GitHub\Mailozaurr\Sources\...)
  

  Issue: Absolute Windows paths won't work for other users
  Fix: Use relative paths: [MailProfile.cs](Sources/Mailozaurr.Application/MailProfile.cs)

Content Gaps

1. Missing error handling guidance: No examples of what to do when commands fail
2. No troubleshooting section: Common issues and solutions would be helpful
3. Limited MCP client examples: Only shows basic JSON configuration

Minor Issues

Formatting

• Inconsistent code block languages: Mix of powershell and no language specification
• Long lines in examples: Some commands exceed readable width

Cross-references

• Dead link potential: References to C:\Support\GitHub\... paths that may not exist for other contributors

Recommendations

High Priority (Security)

1. Replace hardcoded secret values with placeholders
2. Document secure secret management practices
3. Add warnings about command-line argument exposure

Medium Priority (Usability)

1. Convert absolute paths to relative repository paths
2. Add troubleshooting section with common issues
3. Expand MCP client configuration examples

Low Priority (Polish)

1. Standardize code block language specifications
2. Add table of contents to the new document
3. Consider breaking very long CLI examples into multiple steps

Conclusion

This is a valuable addition that significantly improves the project's documentation. The security concerns around secret handling should be addressed before merging, but the overall structure and content quality are excellent. The documentation will greatly help users understand and adopt the CLI and MCP surfaces.

Recommendation: Approve after addressing the security concerns around hardcoded secrets and command-line exposure.

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: be2a6e4b40

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Replace host-specific file links with repo-relative paths

The new guide uses absolute local Windows paths in Markdown links (for example C:\Support\GitHub\Mailozaurr\...), which do not resolve in GitHub, docs renderers, or on contributors’ machines, so readers cannot follow the references to source files. This makes key navigation in the new documentation unreliable in every non-author environment; these links should be changed to repository-relative paths (e.g., Sources/... or Docs/...).

Useful? React with 👍 / 👎.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 51.11%. Comparing base (d13f487) to head (30479a1).
⚠️ Report is 3 commits behind head on v2-speedygonzales.

Additional details and impacted files

@@                  Coverage Diff                  @@
##           v2-speedygonzales     #602      +/-   ##
=====================================================
- Coverage              51.13%   51.11%   -0.02%     
=====================================================
  Files                    473      473              
  Lines                  31170    31170              
  Branches                5359     5359              
=====================================================
- Hits                   15938    15934       -4     
- Misses                 13268    13271       +3     
- Partials                1964     1965       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[PrzemyslawKlys]

Addressed the docs review in 30479a1 by converting the new guide's local absolute file links to repo-relative Markdown links so they work correctly on GitHub and for other contributors.

[claude]

Claude finished @PrzemyslawKlys's task —— View job

---

PR Review: Configuration and Usage Documentation

Review Checklist:

• Read repository guidelines (CLAUDE.md) - No specific guidelines found
• Review new Configuration-and-Usage.md file
• Review README.MD modifications
• Check for security concerns in configuration examples
• Assess documentation quality and structure
• Provide comprehensive feedback on code quality, bugs, performance, security, and test coverage

Overall Assessment

This is a well-structured documentation update that significantly improves the project's usability. The new Configuration-and-Usage.md provides comprehensive guidance for the CLI and MCP surfaces, which was clearly needed given the complexity of the profile system.

Strengths

Documentation Quality

• Excellent structure: Logical flow from core concepts → supported providers → usage examples
• Comprehensive coverage: Covers all major providers (IMAP, POP3, SMTP, Graph, Gmail, SendGrid, etc.)
• Practical examples: Real CLI commands that users can copy and adapt
• Clear capability matrix: Table at Docs/Configuration-and-Usage.md:55-64 clearly shows what each provider supports

Content Organization

• Profile-centric approach: Correctly emphasizes the reusable profile model as the foundation
• Provider-specific guidance: Minimal configuration requirements for each provider type
• Recipe format: Practical examples show both profile creation and secret management

Integration with Existing Docs

• Good cross-references: Links to relevant source files and other documentation
• README enhancements: Adds 112 lines of CLI/MCP usage examples that fill a major gap

Security Considerations

⚠️ Security Concerns Found

1. Hardcoded secrets in examples (Docs/Configuration-and-Usage.md:206, 221, 232, 245):

   --setting userName=user@example.com `
   --secret password --value "secret" --json  # ← Avoid showing actual secret values

   Recommendation: Use placeholder values like --value "<your-password-here>" or reference environment variables

2. Command history exposure (Multiple locations):

   • CLI examples show secrets passed as command-line arguments
   • These could be exposed in shell history, process lists, or logs
     Recommendation: Document secure alternatives like reading from stdin or files:

   # Better approach
   mailozaurr profile set-secret --profile work-imap --name password --stdin
   # Or from file
   mailozaurr profile set-secret --profile work-imap --name password --from-file secrets.txt

3. Missing security guidance:

   • No mention of profile storage security
   • No guidance on secret rotation or expiration
     Recommendation: Add a security section covering profile protection and secret management best practices

Technical Issues

Path References ✅ FIXED

• Previously: Windows-specific paths like C:\Support\GitHub\Mailozaurr\...
• Now Fixed: Correctly uses relative paths like ../Sources/Mailozaurr.Application/...
• Status: Author addressed this issue in commit 30479a1

Content Quality

Strengths

• Comprehensive provider coverage: Each major provider has clear setup instructions
• Practical CLI recipes: Examples cover common workflows from basic setup to advanced operations
• Clear capability documentation: Users understand what each provider supports
• Storage location guidance: Documents where profiles and secrets are stored with override options

Minor Gaps

1. Error handling guidance: No examples of what to do when commands fail
2. Troubleshooting section: Common issues and solutions would be helpful
3. Limited MCP client examples: Only shows basic JSON configuration

Code Quality Assessment

Since this is documentation-only:

• No code changes: This PR contains no executable code to review for bugs or performance issues
• Test coverage: Documentation changes don't affect test coverage
• Best practices: The documentation follows good practices for technical writing

Recommendations

High Priority (Security)

1. Replace hardcoded secret values with placeholders in examples
2. Document secure secret management practices
3. Add warnings about command-line argument exposure in shell history

Medium Priority (Usability)

1. ✅ Fixed: Path references now use relative repository paths
2. Add troubleshooting section with common issues
3. Expand MCP client configuration examples

Low Priority (Polish)

1. Standardize code block language specifications (some use powershell, others have no language)
2. Add table of contents to the new document
3. Consider breaking very long CLI examples into multiple steps

Conclusion

This is a valuable addition that significantly improves the project's documentation. The security concerns around secret handling should be addressed before merging, but the overall structure and content quality are excellent. The documentation will greatly help users understand and adopt the CLI and MCP surfaces.

Recommendation: Approve after addressing the security concerns around hardcoded secrets and command-line exposure.

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 30479a1fda

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Stop listing POP3 mailbox operations as currently supported

This row documents POP3 read/search/delete workflows as available, but the runtime used by CLI/MCP does not register any POP3 read handler (only IMAP/Graph/Gmail are wired in MailApplicationBuilder), so POP3 mail ... operations fail with No read handler is registered for profile kind 'Pop3' from RoutedMailReadService. As written, the guide tells users to set up a workflow that cannot run.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Remove SendGrid/Mailgun/SES send claims from current guide

The guide currently presents these kinds as send-capable profiles in the active CLI/MCP model, but only Graph/Gmail/SMTP send handlers are registered in MailApplicationBuilder; routed sends for these kinds hit No send handler is registered for profile kind ... in RoutedMailSendService. This mismatch will cause users following the provider guidance to create profiles that cannot send.

Useful? React with 👍 / 👎.