docs: update documentation to reflect v0.4 namespace reorganization

Update README and MIGRATION guide to align with the namespace
refactoring that moved classes to dedicated namespaces (Query, Entity,
Services, Registry). Add comprehensive sections on architecture,
security, troubleshooting, and FAQ to improve developer experience.

Changes:
- Update all version references from v1.0 to v0.4
- Update migration guide from v0.x to v0.3 → v0.4
- Add new sections: What's New, Project Structure, Architecture,
  Security, Troubleshooting, FAQ
- Fix all namespace imports in code examples
- Update PHP requirement from 8.1 to 8.2
- Remove non-existent endsWith() method from FilterBuilder docs
- Remove broken examples/ directory reference
- Add comprehensive namespace quick reference table

Author: stmh

MIGRATION.md

@@ -1,12 +1,12 @@
-# Migration Guide: v0.x → v1.0
+# Migration Guide: v0.3 → v0.4
 
-This guide helps you migrate from Twenty CRM PHP Client v0.x (hardcoded entities) to v1.0 (dynamic entity system with code generation).
+This guide helps you migrate from Twenty CRM PHP Client v0.3 and earlier (hardcoded entities) to v0.4 (dynamic entity system with code generation).
 
 ## Overview of Changes
 
-### What Changed in v1.0
+### What Changed in v0.4
 
-**v1.0 introduces a fundamental architectural shift:**
+**v0.4 introduces a fundamental architectural shift:**
 
 - **Removed**: Hardcoded `Contact`, `Company` DTOs and their services
 - **Added**: Dynamic entity system that works with ANY Twenty CRM entity
@@ -29,7 +29,7 @@ The following classes and methods have been **removed**:
 #### Removed Classes
 
 ```php
-// ❌ REMOVED in v1.0
+// ❌ REMOVED in v0.4
 use Factorial\TwentyCrm\DTO\Contact;
 use Factorial\TwentyCrm\DTO\ContactCollection;
 use Factorial\TwentyCrm\DTO\ContactSearchFilter;
@@ -46,17 +46,17 @@ use Factorial\TwentyCrm\Services\CompanyServiceInterface;
 #### Removed Client Methods
 
 ```php
-// ❌ REMOVED in v1.0
+// ❌ REMOVED in v0.4
 $client->contacts();  // ContactService
 $client->companies(); // CompanyService
 ```
 
 ### Kept Classes
 
-These helper classes are **still available** in v1.0:
+These helper classes are **still available** in v0.4:
 
 ```php
-// ✅ KEPT in v1.0 (used by field handlers)
+// ✅ KEPT in v0.4 (used by field handlers)
 use Factorial\TwentyCrm\DTO\Phone;
 use Factorial\TwentyCrm\DTO\PhoneCollection;
 use Factorial\TwentyCrm\DTO\Link;
@@ -71,7 +71,7 @@ use Factorial\TwentyCrm\DTO\CustomFilter;
 
 ## Migration Paths
 
-You have **two options** for migrating to v1.0:
+You have **two options** for migrating to v0.4:
 
 ### Option 1: Use Code Generation (Recommended)
 
@@ -80,13 +80,13 @@ Generate typed entities for your specific Twenty CRM instance.
 **Advantages:**
 - ✅ Full IDE autocomplete support
 - ✅ Type safety with PHPStan/Psalm
-- ✅ Familiar API similar to v0.x
+- ✅ Familiar API similar to v0.3 and earlier
 - ✅ Commit generated code to your repository
 - ✅ Works with custom entities and custom fields
 
 **Steps:**
 
-1. **Install v1.0**:
+1. **Install v0.4**:
    ```bash
    composer require factorial-io/twenty-crm-php-client:^1.0
    ```
@@ -98,7 +98,7 @@ Generate typed entities for your specific Twenty CRM instance.
    api_url: https://your-twenty.example.com/rest/
    api_token: ${TWENTY_API_TOKEN}
    entities:
-     - person    # Was "contact" in v0.x
+     - person    # Was "contact" in v0.3 and earlier
      - company
    options:
      overwrite: true
@@ -111,7 +111,7 @@ Generate typed entities for your specific Twenty CRM instance.
 
 4. **Update your code**:
 
-   **Before (v0.x):**
+   **Before (v0.3):**
    ```php
    use Factorial\TwentyCrm\DTO\Contact;
    use Factorial\TwentyCrm\DTO\ContactSearchFilter;
@@ -124,7 +124,7 @@ Generate typed entities for your specific Twenty CRM instance.
    }
    ```
 
-   **After (v1.0 with generated code):**
+   **After (v0.4 with generated code):**
    ```php
    use MyApp\TwentyCrm\Entities\Person;
    use MyApp\TwentyCrm\Entities\PersonService;
@@ -147,7 +147,7 @@ Generate typed entities for your specific Twenty CRM instance.
 5. **Commit generated code**:
    ```bash
    git add src/TwentyCrm/Entities/
-   git commit -m "Add generated Twenty CRM entities for v1.0"
+   git commit -m "Add generated Twenty CRM entities for v0.4"
    ```
 
 ### Option 2: Use DynamicEntity (Flexible)
@@ -167,7 +167,7 @@ Use the dynamic entity system without code generation.
 
 **Example:**
 
-**Before (v0.x):**
+**Before (v0.3):**
 ```php
 use Factorial\TwentyCrm\DTO\Contact;
 
@@ -178,7 +178,7 @@ $contact->setLastName('Doe');
 $created = $client->contacts()->create($contact);
 ```
 
-**After (v1.0 with DynamicEntity):**
+**After (v0.4 with DynamicEntity):**
 ```php
 use Factorial\TwentyCrm\DTO\DynamicEntity;
 use Factorial\TwentyCrm\DTO\Name;
@@ -196,7 +196,7 @@ $created = $client->entity('person')->create($person);
 
 Twenty CRM's default entity is **"person"**, not "contact". Here's how fields map:
 
-| v0.x (Contact) | v1.0 (Person) | Type | Notes |
+| v0.3 and earlier (Contact) | v0.4 (Person) | Type | Notes |
 |----------------|---------------|------|-------|
 | `getEmail()` | `getEmail()` | `string` | Primary email extracted from `emails` object |
 | `getFirstName()` | `getName()->firstName` | `string` | Part of `name` object |
@@ -211,12 +211,12 @@ Twenty CRM's default entity is **"person"**, not "contact". Here's how fields ma
 
 #### Emails (Simplified)
 
-**v0.x:**
+**v0.3 and earlier:**
 ```php
 $email = $contact->getEmail(); // Direct string
 ```
 
-**v1.0:**
+**v0.4:**
 ```php
 // Option 1: Field handler extracts primary email
 $email = $person->getEmail(); // string
@@ -227,13 +227,13 @@ $emails = $person->get('emails'); // ['primaryEmail' => '[email protected]', ...]
 
 #### Name (Structured)
 
-**v0.x:**
+**v0.3 and earlier:**
 ```php
 $firstName = $contact->getFirstName();
 $lastName = $contact->getLastName();
 ```
 
-**v1.0:**
+**v0.4:**
 ```php
 use Factorial\TwentyCrm\DTO\Name;
 
@@ -251,29 +251,29 @@ $fullName = $name->getFullName();
 
 #### Phones (Collection)
 
-**v0.x:**
+**v0.3 and earlier:**
 ```php
 $phones = $contact->getPhones(); // PhoneCollection
 $primary = $phones->getPrimaryNumber();
 ```
 
-**v1.0:**
+**v0.4:**
 ```php
 $phones = $person->getPhones(); // PhoneCollection (same!)
 $primary = $phones->getPrimaryNumber();
 ```
 
 ## Entity Relations
 
-Relations work differently in v1.0:
+Relations work differently in v0.4:
 
-**v0.x (hardcoded):**
+**v0.3 and earlier (hardcoded):**
 ```php
 // Relations were not explicitly supported
 $companyId = $contact->getCompanyId();
 ```
 
-**v1.0 (with RelationLoader):**
+**v0.4 (with RelationLoader):**
 ```php
 // Lazy loading
 $company = $person->loadRelation('company');
@@ -292,7 +292,7 @@ foreach ($persons as $person) {
 
 ### ContactSearchFilter → CustomFilter
 
-**v0.x:**
+**v0.3 and earlier:**
 ```php
 use Factorial\TwentyCrm\DTO\ContactSearchFilter;
 
@@ -302,7 +302,7 @@ $filter = new ContactSearchFilter(
 );
 ```
 
-**v1.0:**
+**v0.4:**
 ```php
 use Factorial\TwentyCrm\DTO\CustomFilter;
 
@@ -335,28 +335,28 @@ $options = new SearchOptions(
 
 ### Pattern 1: Finding Contacts/Persons
 
-**Before (v0.x):**
+**Before (v0.3):**
 ```php
 $filter = new ContactSearchFilter(email: '[email protected]');
 $contacts = $client->contacts()->find($filter);
 ```
 
-**After (v1.0 - Generated):**
+**After (v0.4 - Generated):**
 ```php
 $filter = new CustomFilter('emails.primaryEmail eq "[email protected]"');
 $options = new SearchOptions(limit: 50);
 $persons = $personService->find($filter, $options);
 ```
 
-**After (v1.0 - Dynamic):**
+**After (v0.4 - Dynamic):**
 ```php
 $filter = new CustomFilter('emails.primaryEmail eq "[email protected]"');
 $persons = $client->entity('person')->find($filter);
 ```
 
 ### Pattern 2: Creating Contacts/Persons
 
-**Before (v0.x):**
+**Before (v0.3):**
 ```php
 $contact = new Contact();
 $contact->setEmail('[email protected]');
@@ -365,7 +365,7 @@ $contact->setLastName('Smith');
 $created = $client->contacts()->create($contact);
 ```
 
-**After (v1.0 - Generated):**
+**After (v0.4 - Generated):**
 ```php
 use MyApp\TwentyCrm\Entities\Person;
 use Factorial\TwentyCrm\DTO\Name;
@@ -376,7 +376,7 @@ $person->setName(new Name('Jane', 'Smith'));
 $created = $personService->create($person);
 ```
 
-**After (v1.0 - Dynamic):**
+**After (v0.4 - Dynamic):**
 ```php
 $person = new DynamicEntity($definition, [
     'emails' => ['primaryEmail' => '[email protected]'],
@@ -387,14 +387,14 @@ $created = $client->entity('person')->create($person);
 
 ### Pattern 3: Updating Contacts/Persons
 
-**Before (v0.x):**
+**Before (v0.3):**
 ```php
 $contact = $client->contacts()->getById($id);
 $contact->setEmail('[email protected]');
 $client->contacts()->update($contact);
 ```
 
-**After (v1.0):**
+**After (v0.4):**
 ```php
 $person = $personService->getById($id);
 $person->setEmail('[email protected]');
@@ -403,13 +403,13 @@ $personService->update($person);
 
 ### Pattern 4: Batch Operations
 
-**Before (v0.x):**
+**Before (v0.3):**
 ```php
 $contacts = [$contact1, $contact2, $contact3];
 $client->contacts()->batchUpsert($contacts);
 ```
 
-**After (v1.0):**
+**After (v0.4):**
 ```php
 $persons = [$person1, $person2, $person3];
 $personService->batchUpsert($persons);
@@ -419,11 +419,11 @@ $personService->batchUpsert($persons);
 
 ### Q: Why was Contact renamed to Person?
 
-**A:** Twenty CRM's default entity is "person", not "contact". The v0.x library used "contact" for familiarity, but v1.0 follows Twenty CRM's actual schema.
+**A:** Twenty CRM's default entity is "person", not "contact". The v0.3 and earlier library used "contact" for familiarity, but v0.4 follows Twenty CRM's actual schema.
 
 ### Q: Can I still use the old Contact class?
 
-**A:** No. Contact, Company, and their services have been removed in v1.0. This is a breaking change requiring migration.
+**A:** No. Contact, Company, and their services have been removed in v0.4. This is a breaking change requiring migration.
 
 ### Q: Do I have to use code generation?
 
@@ -435,9 +435,9 @@ $personService->batchUpsert($persons);
 
 ### Q: How do I work with custom entities (like Campaign)?
 
-**v0.x:** Not possible without library code changes.
+**v0.3 and earlier:** Not possible without library code changes.
 
-**v1.0:** Works immediately:
+**v0.4:** Works immediately:
 
 ```php
 // With code generation
@@ -453,9 +453,9 @@ $client->entity('campaign')->create($campaign);
 
 ### Q: What if my Twenty instance has custom fields on Person/Company?
 
-**v0.x:** Custom fields were accessible but not type-safe.
+**v0.3 and earlier:** Custom fields were accessible but not type-safe.
 
-**v1.0:** Generated code includes ALL fields (standard + custom) with proper types.
+**v0.4:** Generated code includes ALL fields (standard + custom) with proper types.
 
 ```bash
 # Generate entities matching YOUR exact schema
@@ -473,14 +473,14 @@ use Factorial\TwentyCrm\Exception\ApiException;
 try {
     $person = $personService->getById($id);
 } catch (ApiException $e) {
-    // Same exception hierarchy as v0.x
+    // Same exception hierarchy as v0.3 and earlier
     error_log('API error: ' . $e->getMessage());
 }
 ```
 
 ### Q: Is there a performance difference?
 
-No significant performance difference. The dynamic entity system uses the same HTTP client and request patterns as v0.x.
+No significant performance difference. The dynamic entity system uses the same HTTP client and request patterns as v0.3 and earlier.
 
 Code generation may be slightly faster due to static property access vs array lookups, but the difference is negligible in real-world usage.
 
@@ -521,7 +521,7 @@ Code generation may be slightly faster due to static property access vs array lo
 
 Here's a complete before/after example:
 
-### Before (v0.x)
+### Before (v0.3)
 
 ```php
 <?php
@@ -552,7 +552,7 @@ $contact->setEmail('[email protected]');
 $client->contacts()->update($contact);
 ```
 
-### After (v1.0 with Generated Code)
+### After (v0.4 with Generated Code)
 
 ```php
 <?php
@@ -590,7 +590,7 @@ $person->setEmail('[email protected]');
 $personService->update($person);
 ```
 
-### After (v1.0 with DynamicEntity)
+### After (v0.4 with DynamicEntity)
 
 ```php
 <?php
@@ -624,6 +624,6 @@ $client->entity('person')->update($person);
 
 ---
 
-**Version:** 1.0
+**Version:** 0.4
 **Last Updated:** 2025-10-12
-**Target Audience:** Users migrating from v0.x to v1.0
+**Target Audience:** Users migrating from v0.3 and earlier to v0.4