Relation/aggregate/event fixes + Concerns namespaces + Query\Grammar extraction

.gitattributes

@@ -3,5 +3,6 @@
 
 /.vscode       export-ignore
 lefthook.yml export-ignore
+.php-cs-fixer.php export-ignore
 .gitattributes export-ignore
 .gitignore export-ignore

.gitignore

@@ -2,4 +2,7 @@ vendor/
 .php-cs-fixer.cache
 tests.config.php
 .phpunit.result.cache
+.phpunit.cache/
+phpunit.phar
 composer.lock
+.superpowers/

README.md

@@ -1,22 +1,47 @@
-### WPKit/Database
+# wp-database
 
----
+A small ActiveRecord ORM with a fluent query and schema builder on top of
+WordPress' `$wpdb`.
 
-# usage
+## Install
 
-1. Add this repository in composer.json
+```jsonc
+// composer.json
+"repositories": [
+  { "type": "vcs", "url": "https://github.com/Bit-Apps-Pro/wp-database" }
+]
+```
 
+```bash
+composer require bitapps/wp-database:dev-main
 ```
-"repositories": [
+
+## Quick start
+
+```php
+use BitApps\WPDatabase\Model;
+
+class Contact extends Model
+{
+    protected $fillable = ['name', 'email'];
+
+    public function deals()
     {
-      "type": "vcs",
-      "url": "https://github.com/Bit-Apps-Pro/wp-database"
+        return $this->hasMany(Deal::class, 'contact_id', 'id');
     }
-  ]
-```
+}
 
-2. Then install the package
+Contact::insert(['name' => 'Ada', 'email' => 'ada@x.com']);
 
+$active = Contact::where('is_active', 1)
+    ->withCount('deals')
+    ->orderBy('name')->asc()
+    ->get();                       // Collection of Contact models
 ```
-composer require bitapps/wp-database:dev-main
-```
+
+## Documentation
+
+- **[Usage guide](docs/usage.md)** — models, query builder, relationships,
+  casts, events, transactions, and more.
+- **[Schema builder](docs/schema.md)** — table creation, columns, indexes, and migrations.
+- **[Breaking changes](docs/breaking-changes.md)** — upgrade notes.