diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..b000550
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,45 @@
+# Copilot Instructions for json-api PHP Library
+
+## Overview
+This library implements the [JSON API](http://jsonapi.org) specification in PHP 7, focusing on strict validity and immutability of produced documents. The codebase is organized to mirror JSON API concepts directly in PHP classes, making it easy to construct, validate, and test JSON API-compliant payloads.
+
+## Architecture & Key Components
+- **src/**: Core library code. Each file represents a JSON API concept (e.g., `ResourceObject`, `DataDocument`, `Error`, `Meta`, etc.).
+    - Subfolders like `Error/`, `Internal/`, and `Link/` contain specialized classes for error handling, internal data structures, and link objects.
+- **examples/**: Runnable PHP scripts demonstrating typical usage. Start with `simple_doc.php` and `compound_doc.php`.
+- **test/**: Comprehensive PHPUnit test suite. Each test file targets a specific document type or feature. Use these as references for correct usage and edge cases.
+
+## Developer Workflows
+- **Install dependencies**: `composer install`
+- **Run tests**: `vendor\bin\phpunit` (or use `phpunit.xml.dist` for config)
+- **Debugging**: Use the examples and tests to validate document structure. All objects are immutable; modify by creating new instances.
+
+## Project Conventions
+- **Immutability**: All core objects are immutable. Never mutate state; always instantiate new objects for changes.
+- **Strict JSON API compliance**: The library enforces the spec rigorously. Invalid structures will throw exceptions early.
+- **Constructor-based composition**: Build documents by composing objects via constructors, not setters.
+- **Type safety**: Use explicit types for resource objects, identifiers, attributes, and relationships.
+- **Error handling**: Use classes in `src/Error/` for structured error documents.
+
+## Integration & Patterns
+- **No external API calls**: The library is self-contained; integration is via PHP object composition.
+- **Links and relationships**: Use classes in `src/Link/` and relationship objects (`ToOne`, `ToMany`, etc.) to model connections between resources.
+- **Meta and pagination**: Use `Meta`, `MetaDocument`, and `Pagination` classes for additional document metadata and pagination links.
+
+## Examples
+- See `examples/simple_doc.php` for a minimal document.
+- See `test/DataDocument/SingleResourceObjectTest.php` for a test-driven example of primary data construction.
+
+## References
+- [README.md](../README.md): Contains installation, usage, and links to examples/tests.
+- [JSON API Spec](https://jsonapi.org/format/): Reference for document structure and rules.
+
+---
+
+**For AI agents:**
+- Always prefer constructor-based composition and immutability.
+- Reference tests for edge cases and correct usage.
+- Document structure errors are surfaced early; validate inputs before composing objects.
+- Use explicit class names and types as shown in examples/tests.
+
+If any section is unclear or missing, please provide feedback for further refinement.