Release v1.0.0

.github/workflows/ci.yml

@@ -3,12 +3,10 @@ name: CI
 on:
   push:
     branches:
-      - main
       - master
       - develop
   pull_request:
     branches:
-      - main
       - master
       - develop
 
@@ -47,8 +45,5 @@ jobs:
       - name: Install dependencies
         run: composer install --prefer-dist --no-interaction --no-progress
 
-      - name: Run lint suite
-        run: composer lint:all
-
-      - name: Run tests
-        run: composer test
+      - name: Run project checks
+        run: composer check

AGENTS.md

@@ -70,6 +70,27 @@ REST flow:
 - Token store, file handling, upload, OAuth signing, parser, and registry changes need focused edge tests.
 - Do not commit secrets, real access tokens, or snapshots containing credentials.
 
+## Performance Rules
+
+- Cache safety comes before cache features.
+- Never cache auth, OAuth, mutation, private authenticated, upload, replace, or upload ticket workflows.
+- Optional REST caching must stay limited to public cacheable GET calls and must be disabled by default unless a cache adapter is passed.
+- Do not add concurrency unless the current transport architecture clearly supports it and tests prove the behavior.
+- Prefer lazy pagination helpers over loading all pages into memory.
+- Upload and replace should stream files where possible and close file handles after transport handoff.
+- Benchmark only when it would produce meaningful evidence for a real performance decision.
+
+## Git Flow
+
+- Normal implementation work branches from the latest `develop`.
+- Open feature and fix PRs back into `develop`.
+- Release branches start from `develop` as `release/<version>`.
+- Release PRs target `master`; tags and GitHub releases are created from `master`.
+- After release or hotfix merges to `master`, merge `master` back into `develop`.
+- Do not commit directly to `master` or `develop`.
+- Do not delete unmerged branches silently.
+- Never delete protected branches: `master` and `develop`.
+
 ## Quality Commands
 
 ```bash

CHANGELOG.md

@@ -6,19 +6,31 @@ This project follows semantic versioning where practical.
 
 ## Unreleased
 
+## v1.0.0 - 2026-05-14
+
 ### Added
 
 - GitHub Actions CI workflow for Composer validation, linting, and tests.
 - Public `FakeFlickrTransport` for SDK consumer tests without real network calls.
 - Method registry verification tooling and maintenance docs.
 - Runnable examples for raw REST, search, photo info, OAuth, upload, replace, async tickets, mock transport, and custom cache usage.
 - Release readiness and repository metadata documentation.
+- Full registry and service-wrapper coverage for 224 official Flickr REST API methods.
+- OAuth 1.0a authentication, token storage, raw REST calls, upload, replace, and async ticket polling workflows.
+- DTO-first helpers for high-value photo, people, photoset, upload, replace, and response workflows.
+- Optional public GET caching through package cache contracts and PSR-16 adapter support.
+- Lazy `photos()->searchPages()` pagination helper.
+- AI contributor workflow, CI/CD, secret-handling, method-registry, and repository metadata docs.
 
 ### Changed
 
 - Composer lint scripts now run php-cs-fixer alongside Pint, PHPCS, PHPStan, and PHPMD.
 - Documentation index and root README now better describe SDK identity, testing, release readiness, and non-Laravel scope.
+- Cache metadata is conservative for auth, OAuth, upload ticket, authenticated, permissioned, and mutation methods.
+- Upload and replace multipart requests now close file stream handles after transport requests complete.
+- Test coverage was raised above the 95% statement coverage release target.
 
 ### Security
 
 - Examples read credentials from environment variables and avoid embedded secrets.
+- Normal test and CI paths keep real Flickr API calls opt-in behind `FLICKR_REAL_TESTS=true`.

README.md

@@ -47,6 +47,19 @@ $response = $flickr->photos()->search(SearchPhotosData::from([
 
 `flickr.photos.search` can run unauthenticated for public photos. Private and semi-private results require OAuth read permission.
 
+For lazy public search pagination, use `searchPages()`:
+
+```php
+use JOOservices\Flickr\DTO\Common\PaginationOptionsData;
+
+foreach ($flickr->photos()->searchPages(
+    SearchPhotosData::from(['text' => 'sunset']),
+    new PaginationOptionsData(maxPages: 3, perPage: 50),
+) as $page) {
+    // $page is ApiResponseData
+}
+```
+
 ## Raw API Fallback
 
 ```php
@@ -129,15 +142,26 @@ $result = $flickr->uploads()->replace(ReplacePhotoData::from([
 ]));
 ```
 
-Upload and replace require OAuth write permission. Delete requires delete permission.
+Upload and replace require OAuth write permission. Delete requires delete permission. The SDK builds multipart requests with a readable file stream and closes that handle after the transport request completes.
 
 ## Error Handling
 
 Normal API responses are mapped to `ApiResponseData`. Flickr `stat=fail` responses return `ok=false` with `ApiErrorData` unless request options set `throwOnApiError`. Malformed, empty, or structurally invalid responses throw `InvalidResponseException`. Transport failures throw `TransportException`.
 
 ## Cache
 
-V1 includes `NullCache`, `Psr16Cache`, and `CacheKeyResolver`, but raw HTTP caching is disabled by default. Mutation, auth, upload, replace, and authenticated private calls are never cached by default.
+V1 includes `NullCache`, `Psr16Cache`, and `CacheKeyResolver`. Runtime caching is disabled by default because `FlickrFactory` uses `NullCache` unless a cache adapter is passed.
+
+When a cache adapter is passed, only public cacheable GET REST calls can be cached. Mutation, auth, OAuth, upload, replace, upload ticket polling, authenticated options, auth-required methods, POST methods, and Flickr `stat=fail` responses are never cached by default.
+
+```php
+use JOOservices\Flickr\Cache\Psr16Cache;
+
+$flickr = FlickrFactory::make(
+    config: $config,
+    cache: new Psr16Cache($psr16Cache),
+);
+```
 
 ## XML Support
 

ai/skills/README.md

@@ -0,0 +1,15 @@
+# JOOservices Flickr AI Skills
+
+This repository keeps lightweight AI contributor guidance in `AGENTS.md` and `docs/04-development/08-ai-contributor-workflow.md`.
+
+Use this directory as the local entry point when an agent expects repo-level AI skill files. Keep it small unless the repository adopts the fuller `jooservices/dto` skill-pack structure.
+
+Current rules:
+
+- inspect actual source before non-trivial edits
+- keep the package framework-agnostic
+- use official Flickr docs for API behavior
+- keep upload and replace separate from REST calls
+- keep raw fallback support for unknown Flickr methods
+- follow `jooservices/dto` style for DTO/Data objects
+- run repository quality commands before claiming completion