Save this content to: AGENTS.md

# Agent Guide

<!-- Generated by seed-golden-context | Last updated: 2026-05-11 -->

Read this file first. It tells you where to find context in this repo.

## Quick Reference

| What you need | Where to look |
|---|---|
| How this repo is structured | [ARCHITECTURE.md](./ARCHITECTURE.md) |
| How to build/test/run | [CONTRIBUTING.md](./CONTRIBUTING.md) |
| Why decisions were made | [docs/ADRs/](./docs/ADRs/) |
| What this repo does | [README.md](./README.md) |
| PR review rules | [.bito/guidelines/](./.bito/guidelines/) |
| Active specs/work | [docs/specs/](./docs/specs/) |

## Sharp Edges & Invariants

- **This package has one job**: register `Contentful\Delivery\Client` as a deferred Laravel singleton and expose it via the `ContentfulDelivery` facade. Do not add CDA logic, query helpers, or content model abstractions here — those belong in the upstream `contentful/contentful` SDK.
- **No breaking changes without a major version bump.** This follows semver strictly. Any change to the public API (service provider interface, facade accessor, config key names, PHP/Laravel version floor) requires a major version bump and CHANGELOG entry.
- **Config keys are part of the public API.** The `contentful.delivery.*` config namespace is documented and used by downstream Laravel apps. Do not rename or restructure config keys in a minor or patch release.
- **The `delivery.options` config key expects a callable or empty array.** Do not change its type signature without a major bump.
- **Always call `$client->useIntegration($this)` after constructing the Client singleton.** This is required for telemetry tagging via `IntegrationInterface`. Removing this call will silently break SDK usage reporting.
- **Tests use the public Contentful example space.** The `cfexampleapi` space + `b4c0n73n7fu1` token in `phpunit.xml.dist` are intentionally public and safe to commit. Do not replace them with real credentials.
- **No `composer.lock` is committed.** This is a library — the lock file is intentionally absent so consumers resolve their own dependency tree. Never commit `composer.lock`.
- **Package auto-discovery is enabled.** The `extra.laravel` block in `composer.json` registers the provider and facade alias automatically. If you add new providers or aliases, update that block.

## Key Conventions

- **Commit format:** Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, etc.)
- **Branch strategy:** `master` mainline + feature/fix branches; PRs target `master`
- **Test location:** `tests/Unit/` mirroring source structure; base `TestCase` in `tests/TestCase.php`
- **Autoload:** PSR-4 — `Contentful\Laravel\` → `src/`, `Contentful\Tests\Laravel\` → `tests/`
- **Static analysis:** PHPStan at level 5 (`composer lint-static-analysis`)
- **No build step:** pure PHP library, no compilation required

## Integration Points

**Upstream (this repo consumes):**
- `contentful/contentful` ^7.0.1 — PHP Delivery SDK; all CDA calls delegated here
- `contentful/core` ^4.0 — `IntegrationInterface`, HTTP/exception infrastructure
- `laravel/framework` ^8.0–^13.0 — host framework

**Downstream (consumes this repo):**
- Any Laravel application requiring `contentful/laravel` — gets CDA client via DI or `ContentfulDelivery` facade

## Build & Quality

```bash
# Install
composer install

# Quick verification loop
composer test-quick-fail && composer lint-static-analysis

# Full test with coverage
composer test
```