docs(readme) Improve and update README.md for clarity and flexibility

CLAUDE.md

@@ -2,7 +2,7 @@
 - **Always read `PLANNING.md`** at the start of a new conversation to understand the project's architecture, goals, style, and constraints.
 - **Check `TASK.md`** before starting a new task. If the task isn’t listed, add it with a brief description and today's date.
 - **Use consistent naming conventions, file structure, and architecture patterns** as described in `PLANNING.md`.
-- **Use venv_linux** (the virtual environment) whenever executing Python commands, including for unit tests.
+- **Activate `venv_linux`**, the designated virtual environment, before executing any Python commands, including unit tests.
 
 ### 🧱 Code Structure & Modularity
 - **Never create a file longer than 500 lines of code.** If a file approaches this limit, refactor by splitting it into modules or helper files.
@@ -11,22 +11,21 @@
     - `agent.py` - Main agent definition and execution logic 
     - `tools.py` - Tool functions used by the agent 
     - `prompts.py` - System prompts
-- **Use clear, consistent imports** (prefer relative imports within packages).
-- **Use clear, consistent imports** (prefer relative imports within packages).
+- **Use clear, consistent imports**, preferring relative imports within packages.
 - **Use python_dotenv and load_env()** for environment variables.
 
 ### 🧪 Testing & Reliability
 - **Always create Pytest unit tests for new features** (functions, classes, routes, etc).
 - **After updating any logic**, check whether existing unit tests need to be updated. If so, do it.
-- **Tests should live in a `/tests` folder** mirroring the main app structure.
+- **Place all tests in a `/tests` folder**, mirroring the main app’s directory structure.
   - Include at least:
     - 1 test for expected use
     - 1 edge case
     - 1 failure case
 
 ### ✅ Task Completion
 - **Mark completed tasks in `TASK.md`** immediately after finishing them.
-- Add new sub-tasks or TODOs discovered during development to `TASK.md` under a “Discovered During Work” section.
+- Log any newly discovered sub-tasks or TODOs in `TASK.md`, under a “Discovered During Work” section.
 
 ### 📎 Style & Conventions
 - **Use Python** as the primary language.
@@ -54,6 +53,6 @@
 
 ### 🧠 AI Behavior Rules
 - **Never assume missing context. Ask questions if uncertain.**
-- **Never hallucinate libraries or functions** – only use known, verified Python packages.
+- **Never hallucinate libraries or functions** — always rely on known, verified Python packages.
 - **Always confirm file paths and module names** exist before referencing them in code or tests.
 - **Never delete or overwrite existing code** unless explicitly instructed to or if part of a task from `TASK.md`.

INITIAL.md

@@ -4,12 +4,12 @@
 
 ## EXAMPLES:
 
-[Provide and explain examples that you have in the `examples/` folder]
+[Provide and explain the examples located in the `examples/` folder]
 
 ## DOCUMENTATION:
 
-[List out any documentation (web pages, sources for an MCP server like Crawl4AI RAG, etc.) that will need to be referenced during development]
+[List any relevant documentation (web pages, MCP server sources like Crawl4AI RAG, etc.) that should be referenced during development]
 
 ## OTHER CONSIDERATIONS:
 
-[Any other considerations or specific requirements - great place to include gotchas that you see AI coding assistants miss with your projects a lot]
+[Any other considerations or specific requirements — this is a great place to highlight common pitfalls that AI coding assistants tend to miss in your projects]

INITIAL_EXAMPLE.md

@@ -1,26 +1,26 @@
 ## FEATURE:
 
-- Pydantic AI agent that has another Pydantic AI agent as a tool.
-- Research Agent for the primary agent and then an email draft Agent for the subagent.
-- CLI to interact with the agent.
-- Gmail for the email draft agent, Brave API for the research agent.
+- Create a Pydantic-based AI agent that uses another Pydantic agent as a tool.
+- The primary agent is a Research Agent; the sub-agent is responsible for drafting emails.
+- Provide a CLI interface to interact with the agents.
+- Use Gmail integration for the email draft agent, and the Brave API for the research agent.
 
 ## EXAMPLES:
 
-In the `examples/` folder, there is a README for you to read to understand what the example is all about and also how to structure your own README when you create documentation for the above feature.
+The `examples/` folder includes a `README.md` that explains the context of the provided examples and offers a template for structuring your own documentation.
 
-- `examples/cli.py` - use this as a template to create the CLI
-- `examples/agent/` - read through all of the files here to understand best practices for creating Pydantic AI agents that support different providers and LLMs, handling agent dependencies, and adding tools to the agent.
+- `examples/cli.py` – use this as a reference for implementing the CLI.
+- `examples/agent/` – review all files in this directory to understand best practices for building Pydantic AI agents that support multiple providers and LLMs, manage agent dependencies, and register tools.
 
-Don't copy any of these examples directly, it is for a different project entirely. But use this as inspiration and for best practices.
+Note: These examples belong to a different project. Do not reuse them directly, but use them as inspiration and to guide best practices.
 
 ## DOCUMENTATION:
 
-Pydantic AI documentation: https://ai.pydantic.dev/
+- [Pydantic AI Documentation](https://ai.pydantic.dev/)
 
 ## OTHER CONSIDERATIONS:
 
-- Include a .env.example, README with instructions for setup including how to configure Gmail and Brave.
-- Include the project structure in the README.
-- Virtual environment has already been set up with the necessary dependencies.
-- Use python_dotenv and load_env() for environment variables
+- Provide a `.env.example` file and a `README.md` with setup instructions, including configuration for Gmail and Brave.
+- Document the project structure in the `README.md`.
+- The virtual environment has already been configured with the necessary dependencies.
+- Use the `python-dotenv` library and `load_env()` to manage environment variables.