Developer debugging tooling: web profiler, GraphiQL in dev, and a ready-made HTTP collection

[Kravalg]

Description

As a maintainer of php-service-template, I want first-class developer debugging tooling in the dev environment — the Symfony web profiler toolbar, an interactive GraphiQL explorer, and a ready-made HTTP client collection — so that developers can inspect requests, explore the GraphQL schema, and exercise endpoints without hand-crafting curl commands or relying solely on Swagger UI.

Today GraphiQL is explicitly disabled even for dev (config/packages/api_platform.yaml sets graphiql.enabled: false), symfony/web-profiler-bundle (and symfony/debug-bundle) are not in require-dev, so there is no profiler/debug toolbar or dump server, and there is no HTTP client collection (.http files or Postman) covering the health-check and example resource endpoints. Xdebug is already well integrated (Dockerfile, docker-compose.override.yml, infrastructure/docker/php/conf.d/app.dev.ini), but there is no step-debugging documentation beyond ini comments.

Affected quality attributes

This issue is part of the enterprise quality audit (report: docs/audit/enterprise-quality-audit-2026-07.md on branch claude/enterprise-quality-audit-bc8jch).

• interactivity — current 3/5, GraphiQL disabled globally and no profiler toolbar or HTTP client collection for dev — target 5/5.
• debuggability — current 3/5, no web-profiler/debug-bundle/var-dumper in require-dev and no step-debugging docs — target 5/5.
• usability — current 4/5, no interactive GraphQL explorer or dev profiler in the first-run experience — target 5/5.
• inspectability — current 3/5, limited dev-time surfaces for inspecting request/response internals — target 5/5.

Tasks

• Enable GraphiQL for the dev environment only via a when@dev override in config/packages/api_platform.yaml (keep it disabled for prod).
• Add symfony/web-profiler-bundle to require-dev in composer.json, register it in config/bundles.php for dev, and add when@dev configuration under config/packages/ plus the profiler routes under config/routes/.
• Add symfony/debug-bundle to require-dev with when@dev config so the dump server and var-dumper integration are available in dev.
• Ship an HTTP client collection (e.g. .http files or a Postman collection under docs/ or a top-level http/ directory) covering at least the health-check endpoint (/api/health) and the example resource endpoints (REST + GraphQL).
• Document the dev debugging surfaces (profiler toolbar URL, GraphiQL URL, how to use the .http collection) and a short step-debugging section on attaching Xdebug from popular IDEs via XDEBUG_MODE=debug (README and/or .claude/skills/testing-workflow).
• Update .claude/skills/ and AGENTS.md references if these new dev tools change agent-facing workflows (see Synchronize AI agent support surfaces from user-service #171 for the broader AI-agent docs sync effort — do not duplicate its tasks here).

Acceptance Criteria

• GraphiQL is reachable in the dev environment and remains disabled outside dev.
• The Symfony profiler toolbar renders on dev responses and the /_profiler UI is accessible in dev only; prod builds contain no profiler routes or bundles.
• composer.json lists symfony/web-profiler-bundle and symfony/debug-bundle under require-dev only, and make install succeeds.
• The shipped HTTP collection executes successfully against a freshly started stack (make start + make install) for health-check and example resource requests.
• Documentation explains how to use the profiler, GraphiQL, the HTTP collection, and Xdebug step-debugging.
• All existing quality gates still pass (make ci).
• The linked PR passes GitHub CI checks and CodeRabbit review feedback is addressed.

Never propose lowering existing quality gates — thresholds may only be added or raised.