Centralise references on Reference::, and let Response::ref() be the fluent form

[tymondesigns]

Stacked on #22 — review that one first.

Two changes that turned out to be the same change.

1. Every reference is built through Reference::

The X::ref() shortcuts covered nine of the ten component registries, and could never cover the tenth. Schemas are referenced with Reference::schema() because Schema belongs to cortexphp/json-schema, which knows nothing about #/components. So the family advertised a uniform convention while omitting the registry that gets used most — which is what makes Schema::ref('User') look reasonable when it cannot exist.

The numbers backed it up before the change: across docs, tests, and the README there were 25 X::ref() call sites against 97 Reference:: ones, and 61 of those 97 were Reference::schema(). All nine shortcuts were one-line delegations, so nothing is lost:

Response::ref('NotFound')     →  Reference::response('NotFound')
Parameter::ref('PetId')       →  Reference::parameter('PetId')
RequestBody::ref('Create')    →  Reference::requestBody('Create')
Header::ref('RateLimit')      →  Reference::header('RateLimit')
Example::ref('AdminUser')     →  Reference::example('AdminUser')
Link::ref('GetPet')           →  Reference::link('GetPet')
Callback::ref('OnEvent')      →  Reference::callback('OnEvent')
PathItem::ref('LegacyPets')   →  Reference::pathItem('LegacyPets')
SecurityScheme::ref('OAuth2') →  Reference::securityScheme('OAuth2')

Breaking, hence the ! on the commit. At 0.3.0 this seemed better done now than carried past 1.0. The nine per-class tests that covered the shortcuts are dropped rather than rewritten, because ReferenceTest already asserts all ten registries.

2. responses() accepts a referenced response

Operation::responses() keys each entry from getStatusCode(), and a bare Reference has none, so a referenced response could not go in:

Operation::get()->responses(
    Response::ok()->json(Reference::schema('User')),
    Reference::response('NotFound'),   // TypeError — no status to key on
);

This is the only place in the package with the problem: Operation::parameters() and PathItem::parameters() take Parameter|Reference happily, because they build a list and derive no key.

Response::ref() sets the reference on the response itself, so the status still comes from the named constructor:

Operation::get()->responses(
    Response::ok()->json(Reference::schema('User')),
    Response::notFound()->ref('NotFound'),
    Response::unauthorized()->ref('Unauthorized'),
);

{
  "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } },
  "404": { "$ref": "#/components/responses/NotFound" },
  "401": { "$ref": "#/components/responses/Unauthorized" }
}

Removing the static is what frees the name: an earlier revision of this branch had to call it refTo(), since PHP will not let a static and an instance method share one. Output is byte-identical to ->response(404, Reference::response('NotFound')), asserted in a test rather than eyeballed, and ->response() is still there for a status code with no named constructor.

A referenced response drops the fields set on it — Response::notFound()->json(...)->ref('NotFound') emits the $ref alone, because a Reference Object has nowhere to put them. That is last-call-wins, matching responses() and content(), so it does not throw; a test pins the behaviour.

Docs

The quickstart's "Working with References" section is now the single place references are taught, with the one exception called out and linked. Responses, Components, Paths & Operations, Request Bodies, and Webhooks are updated to match.

Verification

193 tests (down 9 with the duplicated shortcut tests removed), PHPStan level 10, ECS and Rector clean, 100% type coverage, mutation score 83.97%. Reflection confirms no static ref() survives on any of the nine classes, every sample on the touched pages was executed, and a document using the fluent form validates against the 3.1 meta-schema.