Improve README and add CLAUDE.md

[gmr]

Summary

• Rewrote README with clearer structure: installation, sync/async/skip_dns usage examples, and a normalization rules table replacing the plain provider list
• Added CLAUDE.md with project overview, build commands, architecture notes, and code style guidance

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

Summary by CodeRabbit

• Documentation
  • Expanded documentation with comprehensive installation and usage guidance for both synchronous and asynchronous workflows
  • Introduced skip_dns mode documentation describing offline normalization without DNS lookups
  • Reorganized and enhanced documentation structure with improved clarity and links to full reference materials

[coderabbitai]

Warning

Rate limit exceeded

@gmr has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 18 minutes and 40 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 946901b9-0052-432a-ae31-7cf9a5afea33

📥 Commits

Reviewing files that changed from the base of the PR and between 446d613 and 9625d25.

📒 Files selected for processing (1)

• README.md

📝 Walkthrough

Walkthrough

Documentation expansion adding a new Claude.md guidance file and restructuring README.md with installation instructions, usage examples for both synchronous and asynchronous workflows, skip_dns mode description, and normalization rules overview.

Changes

Cohort / File(s)	Summary
Documentation CLAUDE.md, README.md	Added new CLAUDE.md file documenting project overview, async MX resolution workflow, architecture, and code style conventions. Updated README.md with Installation and Usage sections including sync/async examples, skip_dns mode explanation, and normalization rules.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 Ears perked with glee, I hop through the docs,
New guides and examples, removing the blocks,
Async and sync paths now clearly unfold,
A tale of normalization, beautifully told! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the two main changes: improving the README and adding a new CLAUDE.md documentation file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/improve-readme-add-claude-md

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Around line 35-40: The README's example calls await at top-level which will
fail in a normal Python script; wrap the async call in an async entrypoint and
run it with asyncio.run. Change the snippet to define an async def main() that
creates email_normalize.Normalizer(), awaits normalizer.normalize(...), and
prints the result, then invoke asyncio.run(main()) so Normalizer and its
normalize coroutine are executed correctly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c64fdbce-c618-4aa0-a39e-f408b0753702

📥 Commits

Reviewing files that changed from the base of the PR and between d704dc5 and 446d613.

📒 Files selected for processing (2)

• CLAUDE.md
• README.md