docs: add comprehensive ORM docs

[davebarnwell]

Summary

The package had a solid README and example file, but there was no single comprehensive documentation path for users who need more than a quick start. Important behavior such as strict field handling, dynamic finder edge cases, schema metadata refresh, custom primary keys, zero-like primary key handling, and connection isolation was either lightly covered or only discoverable by reading the source and tests.

This change adds a proper documentation set for the ORM and makes the README a clearer entry point. Users now have a guided usage document for everyday development and a separate API reference for exact method behavior.

Problem and user impact

Before this change, developers had to piece together the ORM's behavior from multiple places. The README explained the happy path, EXAMPLE.md showed a handful of flows, and the rest of the contract lived in src/Model/Model.php plus the test suite. That made the library harder to adopt confidently, especially for behavior that matters in production but is not obvious from the quick start.

The practical effect was that users could miss real behavior differences such as:

• when save() inserts versus updates
• what strict field mode changes
• how empty-array dynamic finders behave
• how runtime schema changes interact with cached metadata
• how custom primary keys and explicit primary key inserts work
• which exceptions are raised for common failure modes

Root cause

The project had good implementation coverage and reasonable top-level docs, but it did not yet have a dedicated comprehensive guide or a method-level reference that tracked the actual public API.

Fix

This PR adds two new docs files and updates the README navigation:

• docs/guide.md provides a full usage guide covering setup, model definition, lifecycle operations, query helpers, dynamic finders, raw SQL, validation hooks, strict fields, metadata refresh, multiple connections, timestamps, exceptions, and driver-specific notes.
• docs/api-reference.md documents the public API of Freshsauce\Model\Model method by method, including signatures, return behavior, and notable edge cases.
• README.md now points readers to the new docs from both the main flow and the Learn more section.

The new docs were written against the implementation and tests so the documented behavior matches the code rather than describing intended behavior loosely.

Validation

I ran the PHPUnit suite locally:

vendor/bin/phpunit -c phpunit.xml.dist

Result: passed with 37 tests and 1 skipped test.

[Copilot]

Pull request overview

Adds a comprehensive documentation set for the Freshsauce\Model\Model ORM so users have a clear guide for day-to-day usage plus a method-level reference, with the README updated to point into the new docs.

Changes:

• Adds a full usage guide covering setup, CRUD, query helpers, dynamic methods, strict fields, metadata refresh, multiple connections, timestamps, and exceptions.
• Adds a method-by-method API reference for Freshsauce\Model\Model.
• Updates README.md to link to the new documentation entry points.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/guide.md	New end-to-end usage guide documenting ORM behavior and patterns.
docs/api-reference.md	New API reference describing Model methods, signatures, and edge cases.
README.md	Adds prominent links to the new guide and API reference.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.