Release 1.3.0

.claude/agents/filter-provider-reviewer.md

@@ -0,0 +1,38 @@
+---
+name: filter-provider-reviewer
+description: Review changes to Elasticsearch filters and state providers for query-DSL correctness and index-contract alignment. Use after editing anything under src/Api/Filter/ElasticSearch/ or src/Api/State/.
+---
+
+You review the riskiest code in this repo: the custom Elasticsearch filters (`src/Api/Filter/ElasticSearch/`) and
+the state providers (`src/Api/State/`) that assemble them. Unlike stock API Platform filters, these emit **raw
+Elasticsearch query DSL** rather than mutating a Doctrine query builder, and the document mappings they target are
+owned by `event-database-imports` — so a generic code reviewer misses the failure modes that matter here.
+
+Focus your review on:
+
+1. **Query-DSL correctness.** `apply()` returns ES query fragments, not query-builder mutations. Check the emitted
+   DSL is well-formed for its intent (`term`/`terms` vs `match`, `range` bounds, `bool` `must`/`should`/`filter`
+   nesting) and that clauses compose rather than overwrite when multiple filters apply to one request.
+
+2. **Filter vs sort separation.** `AbstractProvider::getFilters()` splits filter clauses from sort clauses via the
+   `SortFilterInterface` marker. A new sorting filter must implement that marker or it will be treated as a query
+   clause; a query filter must not.
+
+3. **Index-contract alignment — check the MAPPED field type, not assumed behaviour.** Field names/types referenced
+   in the DSL must match what `event-database-imports` writes. The production-parity mappings are copied in
+   `tests/resources/mappings/*.json` — consult them. Matching semantics depend on the mapped type: a `keyword` field
+   (e.g. `tags`, `slug`, `vocabulary`, `postalCode`) matches **exact, case-sensitive, whole-value** (no tokenisation);
+   a `text` field (e.g. `title`, `name`, `description`) is **tokenised** (word match). Do not assume dynamic-mapping
+   behaviour. A typo'd/renamed field, or a filter that assumes token matching on a `keyword` field, yields
+   empty/incorrect results silently — not an error. Confirm against `tests/resources/mappings/<index>.json` or a live
+   mapping (`docker compose exec -T phpfpm curl -s http://elasticsearch:9200/<index>/_mapping`).
+
+4. **Pagination & limits.** `paginationMaximumItemsPerPage` on the DTO and `AbstractProvider::MAX_PAGE_SIZE_FALLBACK`
+   (20) bound page size — check a new provider respects them and returns `SearchResults` for collections / a single
+   array for items.
+
+5. **Filter registration.** Filters are attached via `#[ApiFilter(...)]` on the DTO and picked up through
+   `api_platform.filter_locator`. Confirm a new filter is actually reachable that way, not just defined.
+
+Report concrete, file:line findings ranked by severity. Prefer verifying a claim against the code or a live ES
+query over speculating. Do not restate what is correct at length — surface what is wrong or unverifiable.

.claude/agents/pr-readiness.md

@@ -0,0 +1,31 @@
+---
+name: pr-readiness
+description: Run all CI-equivalent checks locally before creating a PR
+model: haiku
+---
+
+Mirror what `.github/workflows/*.yaml` runs on a PR. Every step executes inside Docker (the project
+ships only its `phpfpm` / `prettier` / `markdownlint` services — there is no `node` service and no
+JS/CSS to lint). Stop early if a critical check fails.
+
+## Checks
+
+1. **Composer validate**: `docker compose exec -T phpfpm composer validate --strict`
+2. **Composer normalize (dry-run)**: `docker compose exec -T phpfpm composer normalize --dry-run`
+3. **PHP coding standards**: `task coding-standards:php:check`
+4. **Twig coding standards**: `task coding-standards:twig:check`
+5. **YAML coding standards**: `task coding-standards:yaml:check`
+6. **Markdown coding standards**: `task coding-standards:markdown:check`
+7. **PHPStan (level 8)**: `task code-analysis:phpstan`
+8. **Rector (dry-run)**: `task code-analysis:rector` — the `Rector` gate fails on any suggested change; run `task code-analysis:rector:apply` to fix.
+9. **Test fixtures + API tests**: `task fixtures:load:test --yes && task api:test`. Tests hit a real Elasticsearch, so fixtures must be loaded first. If the load fails with "No alive nodes", run `docker compose up --detach --wait` and retry — see the `reload-fixtures` agent for the full recovery dance.
+10. **API spec up to date** (mirrors `.github/workflows/api-spec.yml`):
+
+- `task api:spec:export`
+- `git diff --exit-code public/spec.yaml` — must be clean.
+
+1. **CHANGELOG updated**: `git diff develop -- CHANGELOG.md` should show at least one entry under `## [Unreleased]`.
+
+## Output
+
+Report a summary table with columns: Check Name, Status (pass/fail), and error output for failures.

.claude/agents/reload-fixtures.md

@@ -0,0 +1,25 @@
+---
+name: reload-fixtures
+description: Reload Elasticsearch fixtures and recover from a not-ready cluster
+model: haiku
+---
+
+This project's "data layer" is Elasticsearch — there is no Doctrine database to migrate. After changing
+API resources, filters, or anything that affects search behavior you generally want to reload fixtures
+so subsequent manual / test runs see a consistent dataset.
+
+Two flavours of fixtures exist (see `src/Model/IndexName.php` for the seven index names):
+
+- **Dev fixtures** — pulled from the `event-database-imports` repo on GitHub: `task fixtures:load`
+- **Test fixtures** — read from `tests/resources/*.json` and used by the PHPUnit suite: `task fixtures:load:test --yes`
+
+## Steps
+
+1. Confirm with the user (or take it from their prompt) whether to load **dev** or **test** fixtures.
+2. Make sure the stack is up: `docker compose up --detach --wait`. The `--wait` is important — Elasticsearch is slow to become ready and the fixture loader fails fast with "No alive nodes" otherwise.
+3. Run the load command (`task fixtures:load` or `task fixtures:load:test --yes`). The Taskfile prompts for confirmation unless `--yes` is passed.
+4. If the command fails with "No alive nodes" or any Elasticsearch connection error:
+   - Poll the cluster health endpoint until it returns HTTP 200:
+     `docker compose exec elasticsearch curl 'http://localhost:9200/_cluster/health?wait_for_status=yellow&timeout=5s' --verbose`
+   - Re-run the fixture load command.
+5. Report which indices were loaded and any non-fatal warnings.

.claude/settings.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "env": {
+    "COMPOSE_USER": "deploy"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(cat:*)",
+      "Bash(diff:*)",
+      "Bash(echo:*)",
+      "Bash(find:*)",
+      "Bash(gh:*)",
+      "Bash(git:*)",
+      "Bash(grep:*)",
+      "Bash(head:*)",
+      "Bash(ls:*)",
+      "Bash(pwd)",
+      "Bash(tail:*)",
+      "Bash(task:*)",
+      "Bash(tree:*)",
+      "Bash(wc:*)",
+      "Bash(which:*)",
+      "Bash(docker compose exec:*)",
+      "Bash(docker compose run:*)",
+      "Bash(docker compose up:*)",
+      "Bash(docker compose ps:*)",
+      "Bash(docker compose logs:*)",
+      "Bash(docker compose top:*)",
+      "Bash(docker compose config:*)",
+      "Bash(docker compose pull:*)",
+      "Bash(docker compose images:*)",
+      "Bash(docker network:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(gh issue delete:*)",
+      "Bash(gh release delete:*)",
+      "Bash(gh repo delete:*)",
+      "Bash(gh label delete:*)",
+      "Read(./.env.local)",
+      "Read(./.env.local.*)",
+      "Read(./config/secrets/*)"
+    ],
+    "ask": [
+      "Bash(docker compose down:*)",
+      "Bash(docker compose stop:*)",
+      "Bash(docker compose rm:*)",
+      "Bash(docker compose restart:*)",
+      "Bash(gh issue create:*)",
+      "Bash(gh issue close:*)",
+      "Bash(gh issue edit:*)",
+      "Bash(gh issue comment:*)",
+      "Bash(gh pr create:*)",
+      "Bash(gh pr close:*)",
+      "Bash(gh pr merge:*)",
+      "Bash(gh pr edit:*)",
+      "Bash(gh pr comment:*)",
+      "Bash(gh pr review:*)",
+      "Bash(gh release create:*)",
+      "Bash(gh release edit:*)",
+      "Bash(gh repo create:*)",
+      "Bash(gh label create:*)",
+      "Bash(gh label edit:*)",
+      "Bash(git push:*)",
+      "Bash(git branch -d:*)",
+      "Bash(git branch -D:*)",
+      "Bash(git tag -d:*)",
+      "Bash(git tag -a:*)",
+      "Bash(git tag :*)",
+      "Bash(git reset:*)",
+      "Bash(git rebase:*)",
+      "Bash(git merge:*)",
+      "Bash(git stash drop:*)",
+      "Bash(git clean:*)",
+      "Bash(git checkout -- :*)",
+      "Bash(git restore:*)",
+      "Bash(git commit:*)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "docker compose up --detach --quiet-pull 2>/dev/null || true",
+            "timeout": 60,
+            "statusMessage": "Starting Docker services..."
+          }
+        ]
+      },
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "command -v jq >/dev/null 2>&1 || { echo '⚠️  jq is not installed on the host — the Edit/Write formatting hooks read the edited file path from the tool payload via jq and will silently no-op until you install it (brew install jq).' >&2; exit 2; }",
+            "timeout": 10,
+            "statusMessage": "Checking host prerequisites..."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in */composer.lock|*/symfony.lock|*/.env.local|*/.env.*.local|*/config/reference.php|*/vendor/*|*/node_modules/*|*/var/cache/*) echo 'BLOCKED: this path is generated, locked, or operator-only — edit the source instead' >&2; exit 2 ;; esac"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|MultiEdit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "f=$(jq -r '.tool_input.file_path // empty'); REL_PATH=\"${f#\"$CLAUDE_PROJECT_DIR\"/}\"; case \"$REL_PATH\" in src/*.php|tests/*.php) docker compose exec -T phpfpm vendor/bin/rector process --no-progress-bar \"$REL_PATH\" >/dev/null 2>&1 || true ;; esac",
+            "timeout": 60
+          },
+          {
+            "type": "command",
+            "command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in *.php) REL_PATH=\"${f#\"$CLAUDE_PROJECT_DIR\"/}\"; docker compose exec -T phpfpm vendor/bin/php-cs-fixer fix --quiet \"$REL_PATH\" 2>/dev/null || true ;; esac",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in *.php) REL_PATH=\"${f#\"$CLAUDE_PROJECT_DIR\"/}\"; docker compose exec -T phpfpm vendor/bin/phpstan analyse --no-progress --error-format=raw \"$REL_PATH\" 2>/dev/null || true ;; esac",
+            "timeout": 45
+          },
+          {
+            "type": "command",
+            "command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in *.twig) REL_PATH=\"${f#\"$CLAUDE_PROJECT_DIR\"/}\"; docker compose exec -T phpfpm vendor/bin/twig-cs-fixer lint --fix \"$REL_PATH\" 2>/dev/null || true ;; esac",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in */composer.json) docker compose exec -T phpfpm composer normalize --quiet 2>/dev/null || true ;; esac",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in *.yaml|*.yml|*.js|*.css) REL_PATH=\"${f#\"$CLAUDE_PROJECT_DIR\"/}\"; docker compose run --rm -T prettier \"$REL_PATH\" --write 2>/dev/null || true ;; esac",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in *.md) REL_PATH=\"${f#\"$CLAUDE_PROJECT_DIR\"/}\"; docker compose run --rm -T markdownlint markdownlint --fix \"$REL_PATH\" 2>/dev/null || true ;; esac",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "docker compose exec -T phpfpm bin/console lint:container 2>/dev/null || true",
+            "timeout": 30,
+            "statusMessage": "Validating Symfony DI container..."
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PROJECT_DIR/scripts/claude-hook-check-index-contract.sh\" || true",
+            "timeout": 10,
+            "statusMessage": "Checking Elasticsearch index contract..."
+          },
+          {
+            "type": "command",
+            "command": "sh \"$CLAUDE_PROJECT_DIR/scripts/claude-hook-check-spec-drift.sh\" || true",
+            "timeout": 10,
+            "statusMessage": "Checking OpenAPI spec is up to date..."
+          }
+        ]
+      }
+    ]
+  },
+  "enabledPlugins": {
+    "php-lsp@claude-plugins-official": true,
+    "code-simplifier@claude-plugins-official": true,
+    "context7@claude-plugins-official": true,
+    "code-review@claude-plugins-official": true,
+    "security-guidance@claude-plugins-official": true,
+    "playwright@claude-plugins-official": true,
+    "feature-dev@claude-plugins-official": true,
+    "itkdev-skills@itkdev-marketplace": true
+  },
+  "enabledMcpjsonServers": [
+    "context7"
+  ],
+  "enableAllProjectMcpServers": true
+}

.claude/skills/changelog-entry/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: changelog-entry
+description: Add or fix this repo's CHANGELOG.md entry for the current PR, in the exact house format. Use before opening a PR or when resolving a CHANGELOG merge conflict.
+disable-model-invocation: true
+---
+
+Add a changelog line for the current work to `CHANGELOG.md`, following this repo's convention exactly (getting it wrong causes the `changelog` CI check in `.github/workflows/changelog.yaml` to fail and creates repeated merge conflicts).
+
+## Format
+
+Under the `## [Unreleased]` heading, entries are a **two-line wrapped** list item:
+
+```
+- [PR-N](https://github.com/itk-dev/event-database-api/pull/N)
+  Short imperative description of the change
+```
+
+Rules:
+
+- One entry per PR. Ordered by **descending PR number** (newest on top).
+- The URL is always the `event-database-api` repo (not `event-database-imports`).
+- **Keep it short and terse — match the surrounding entries.** The description is a single concise noun or
+  imperative phrase naming *what* changed, not a sentence (or paragraph) explaining *how*. It fits on one wrapped
+  line and almost always well under the 120-char limit (markdownlint MD013). If you're tempted to list mechanisms,
+  reasons, or multiple clauses, cut them — that detail belongs in the PR description, not the changelog.
+  - Good (real entries): `Symfony 7.3 and PHP 8.4` · `Re-lint YAML files` ·
+    `Add Claude Code project setup (CLAUDE.md, agents, skills)`
+  - Too long: `Adapt Claude Code setup from event-database-imports: fix the Edit/Write hook mechanism (read the
+    file path from the tool payload via jq instead of the unset CLAUDE_FILE_PATH), guard the …`
+- Some historical entries are plain bullets without a PR link (e.g. dependency bumps) — that's fine for changes
+  without a PR, but PR-based work always gets the `[PR-N]` form.
+
+## Two-step PR number
+
+The PR number isn't known until the PR exists. So:
+
+1. Add the entry now with a `PR-XX` placeholder and `pull/XX` URL.
+2. After the PR is opened (`gh pr view --json number`), replace `XX` with the real number in a follow-up commit (`docs: set PR number in CHANGELOG entry`).
+
+## Steps
+
+1. `git fetch origin develop` and read the current `[Unreleased]` block so you insert in the right order and don't duplicate.
+2. Insert the entry at the correct descending-number position.
+3. Lint: `docker compose run --rm markdownlint markdownlint CHANGELOG.md`.
+4. If a PR already exists, set the real number; otherwise leave `XX` and remind the user of step 2.

.claude/skills/new-resource/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: new-resource
+description: Scaffold a new read-only API resource backed by an Elasticsearch index, following this repo's DTO + provider + filter pattern. Use when exposing a new index (or a new shape of an existing one) under /api/v2.
+disable-model-invocation: true
+---
+
+Add a new API Platform resource. This repo's resources are **DTOs backed by Elasticsearch**, never Doctrine
+entities — every resource follows the same three-part shape, with `Event` as the canonical template. Read
+`src/Api/Dto/Event.php`, `src/Api/State/EventRepresentationProvider.php`, and `tests/ApiPlatform/EventsTest.php`
+before starting, and mirror them.
+
+## Steps
+
+1. **Confirm the index.** The seven indices live in `src/Model/IndexName.php`. If the resource maps to an existing
+   index, reuse that enum case. If it's a genuinely new index, add a case — and remember the mapping is owned by
+   `event-database-imports` (see CLAUDE.md → "Works with event-database-imports"); coordinate the contract there.
+
+2. **DTO** — `src/Api/Dto/<Resource>.php`: an `#[ApiResource]` class declaring operations, pagination
+   (`paginationMaximumItemsPerPage`), and `#[ApiFilter(...)]` attributes. The `$id` property is identifier-only
+   (PHPStan "unused" errors on it are intentionally ignored); real fields are filled by the provider. Attach
+   filters from `src/Api/Filter/ElasticSearch/` (`MatchFilter`, `IdFilter`, `BooleanFilter`, `DateRangeFilter`,
+   `DateFilter`, `TagFilter`) — do not invent a Doctrine filter.
+
+3. **Provider** — `src/Api/State/<Resource>RepresentationProvider.php`: implement `ProviderInterface` by extending
+   `AbstractProvider`. Use `getFilters()` to compile the declared `#[ApiFilter]` attributes into ES query
+   fragments, call `IndexInterface::search()`, and return a `SearchResults` (collection op) or a single array
+   (item op). Wire the DTO's `provider:` to this class. Providers are autoconfigured — only touch
+   `config/services.yaml` if you need explicit arguments.
+
+4. **Test** — `tests/ApiPlatform/<Resource>Test.php`: extend `AbstractApiTestCase`, `use` `GetEntitiesTestTrait`
+   and `GetItemTestTrait`, and set the static props (`$requestPath`, `$resourceClass`, `$itemId`,
+   `$unknownItemId`). Add resource-specific filter assertions in a `<Resource>FilterTest.php`. Add fixture rows to
+   `tests/resources/<index>.json` so `$itemId` resolves (see `tests/resources/README.md`).
+
+5. **Regenerate the OpenAPI spec** — run the `/update-api-spec` skill (or `task api:spec:export`). CI
+   (`.github/workflows/api-spec.yml`) fails if `public/spec.yaml` is stale.
+
+6. **Verify** — `task fixtures:load:test --yes` then `task api:test -- --filter <Resource>`. Run
+   `task coding-standards:check` and `task code-analysis` before opening the PR.

.claude/skills/update-api-spec/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: update-api-spec
+description: Regenerate and stage the OpenAPI spec after API resource changes
+user-invocable: true
+---
+
+The committed OpenAPI spec lives at `public/spec.yaml` (single YAML file — there is no separate JSON
+export). `.github/workflows/api-spec.yml` fails the PR if it drifts from the resources defined under
+`src/Api/`, and additionally diffs the spec against the base branch to flag breaking changes.
+
+After touching anything under `src/Api/Dto/`, `src/Api/State/`, or `src/Api/Filter/`:
+
+1. Regenerate the spec: `task api:spec:export`
+   (This is shorthand for `bin/console api:openapi:export --yaml --output=public/spec.yaml --no-interaction`.)
+2. Inspect changes: `git diff public/spec.yaml`
+3. If the diff is non-empty, stage the file: `git add public/spec.yaml`
+4. Summarise what changed — new/removed operations, modified parameters, schema diffs — so the human
+   reviewer can sanity-check for unintended breaking changes before pushing.