chore: prepare v0.1.0 release (PR 2.9)

- Add CHANGELOG.md documenting what shipped in 0.1.0 + the known
  limitations (it's lift-and-shift; spec compliance is Phase 4 work).
- Update README status banner from "Work in progress; do not depend on
  it" to "Pre-1.0".
- Add a real usage example to the README (HttpDocumentLoader + Guzzle).
- Refresh the v1.0 scope checklist: DocumentLoader is done, Expansion
  is present-but-not-spec-compliant, Compaction + toRdf still pending.

Tag v0.1.0 is created separately so this commit can be reviewed without
binding the tag prematurely.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: skydudie

.gitattributes

@@ -0,0 +1,25 @@
+# Force LF line endings for all text files. Overrides Windows checkout-time
+# CRLF conversion (core.autocrlf=true) so contributors on different platforms
+# see the same bytes regardless of local git config.
+* text=auto eol=lf
+
+# Binary file types — never touch line endings.
+*.png binary
+*.jpg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+
+# Files that don't need to ship in the composer dist tarball.
+# These cut the size of `composer require` downloads significantly,
+# especially the W3C submodule (tests/w3c/).
+/.editorconfig    export-ignore
+/.gitattributes   export-ignore
+/.gitignore       export-ignore
+/.gitmodules      export-ignore
+/.github          export-ignore
+/CHANGELOG.md     export-ignore
+/Pest.php         export-ignore
+/phpstan.neon.dist export-ignore
+/phpunit.xml      export-ignore
+/tests            export-ignore

CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to `accredifysg/php-json-ld` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-13
+
+Initial release. Extracts the JSON-LD context loader + expander out of
+[accredifysg/verifiable-credentials-php](https://github.com/accredifysg/verifiable-credentials-php)
+into a standalone package. Behaviourally identical to that repo's
+pre-extraction implementation — see the
+[characterization tests](tests/Algorithms/Characterization/) for the
+byte-equal proof.
+
+This release is **not spec-compliant with JSON-LD 1.1**. It is shipped
+so the VC repo can consume the package in Phase 3 without behaviour
+change. Spec-compliance work lands incrementally in Phase 4.
+
+### Added
+
+- `Accredify\JsonLd\JsonLdProcessor` — top-level processor, exposes `expand()`.
+- `Accredify\JsonLd\Contracts\Processor` — public interface.
+- `Accredify\JsonLd\Contracts\DocumentLoader` — pluggable `@context` URL resolver.
+- `Accredify\JsonLd\Loaders\HttpDocumentLoader` — default PSR-18 + PSR-17
+  loader. Throws `DocumentLoaderException` on fetch/parse failure.
+- `Accredify\JsonLd\Loaders\CachingDocumentLoader` — in-process cache
+  decorator.
+- `Accredify\JsonLd\Context\ContextProcessor` — flattens layered
+  `@context` declarations into a single term map.
+- `Accredify\JsonLd\Context\TermDefinitions` — term → definition value
+  object.
+- `Accredify\JsonLd\Algorithms\Expansion` — expansion routine (partial
+  JSON-LD 1.1; see characterization tests for current behaviour).
+- `Accredify\JsonLd\Documents\ExpandedDocument` — read-only wrapper for
+  expanded output.
+- `Accredify\JsonLd\Documents\RemoteDocument` — DTO for fetched documents.
+- `Accredify\JsonLd\Exceptions\JsonLdException` — base exception.
+- `Accredify\JsonLd\Exceptions\DocumentLoaderException` — loader failure.
+- `Accredify\JsonLd\Enums\Keyword`, `Accredify\JsonLd\Enums\ContainerType`
+  — JSON-LD 1.1 keyword + container enums.
+- W3C JSON-LD 1.1 test suite vendored as a git submodule under
+  `tests/w3c/`, with a Pest-driven harness at `tests/W3c/` that runs
+  every manifest as `composer test:w3c`. Currently 1098 tests skipped
+  (baseline); Phase 4 lifts that count.
+
+### Known limitations (see [the plan](https://github.com/accredifysg/php-json-ld) for the roadmap)
+
+- IRI expansion rejects valid IRIs like `did:`, `urn:`, blank node `_:`.
+- No container handling: `@list`, `@set`, `@language`, `@index`,
+  `@graph`, `@id`, `@type`, `@nest`, `@included`.
+- No `@reverse`, `@json`, language-tagged or direction-tagged strings.
+- No `@import`, `@propagate`, type-/property-scoped contexts.
+- `@base`, `@vocab` stored but not applied during IRI expansion.
+- `@protected` validated as boolean but not enforced.
+- Hardcoded xsd:string collapse.
+- Only `expand` is implemented; `compact` and `toRdf` land in Phase 4.
+
+[Unreleased]: https://github.com/accredifysg/php-json-ld/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/accredifysg/php-json-ld/releases/tag/v0.1.0

README.md

@@ -9,10 +9,12 @@
 
 A PHP implementation of the [JSON-LD 1.1](https://www.w3.org/TR/json-ld11/) specification.
 
-> **Status: Work in progress.** This package is being extracted from
-> [accredifysg/verifiable-credentials-php](https://github.com/accredifysg/verifiable-credentials-php)
-> and incrementally brought into conformance with the W3C JSON-LD 1.1 specification.
-> The public API is not yet stable; do not depend on it for production use until v1.0.
+> **Status: Pre-1.0.** v0.1.0 ships the JSON-LD code extracted from
+> [accredifysg/verifiable-credentials-php](https://github.com/accredifysg/verifiable-credentials-php).
+> It is functionally complete for VCv2 / Open Badges v3 expansion but is
+> **not yet spec-compliant** with JSON-LD 1.1 — see
+> [CHANGELOG](CHANGELOG.md) for known limitations. The public API may change
+> before v1.0.
 
 ## Goals
 
@@ -26,24 +28,46 @@ A PHP implementation of the [JSON-LD 1.1](https://www.w3.org/TR/json-ld11/) spec
 
 ## Planned scope (v1.0)
 
-- [ ] Expansion (§5.5)
+- [x] Custom `DocumentLoader` interface
+- [~] Expansion (§5.5) — present, not spec-compliant yet
 - [ ] Compaction (§5.6)
 - [ ] Serialize JSON-LD to RDF (§6 / `toRdf`)
-- [ ] Custom `DocumentLoader` interface
 
 Out of scope for v1.0: Flattening, Framing, RDF-to-JSON-LD (`fromRdf`).
 
 ## Installation
 
 ```bash
-composer require accredifysg/php-json-ld
+composer require accredifysg/php-json-ld:^0.1
 ```
 
-Requires PHP 8.1+.
+Requires PHP 8.1+. You also need a PSR-18 HTTP client + PSR-17 request
+factory if you use the bundled `HttpDocumentLoader` (e.g. `guzzlehttp/guzzle`
+and `guzzlehttp/psr7`), or you can implement `DocumentLoader` yourself to
+serve `@context` URLs from wherever you like.
 
 ## Usage
 
-> Usage examples land in a later PR once the public API stabilises.
+```php
+use Accredify\JsonLd\JsonLdProcessor;
+use Accredify\JsonLd\Loaders\CachingDocumentLoader;
+use Accredify\JsonLd\Loaders\HttpDocumentLoader;
+use GuzzleHttp\Client;
+use GuzzleHttp\Psr7\HttpFactory;
+
+$loader = new CachingDocumentLoader(
+    new HttpDocumentLoader(new Client, new HttpFactory),
+);
+
+$processor = new JsonLdProcessor($loader);
+$expanded = $processor->expand($yourDocument)->toArray();
+```
+
+If you want to serve known contexts from local files (recommended for
+verifiable credentials), implement `Accredify\JsonLd\Contracts\DocumentLoader`
+yourself. See
+[`tests/Algorithms/Characterization/Support/BundledContextLoader.php`](tests/Algorithms/Characterization/Support/BundledContextLoader.php)
+for an example.
 
 ## Compliance