dx: changelog, matching precedence fix, baseUrl normalization, README gaps, llms.txt

[sethlivingston]

Summary

DX improvements from a full usability assessment of the library for both human developers and AI agents.

Behavioral fixes

• Response matching precedence — changed from layer-first to specificity-first: req-exact → cli-exact → req-class → cli-class. Previously a client-level exact match (e.g. 200) could be beaten by a request-level class match (e.g. 2xx), which was counterintuitive.
• baseUrl trailing-slash normalization — buildEffectiveUrl now automatically appends a trailing / to baseUrl if absent. Removes a silent footgun where "https://api.example.com/v1" would drop /v1 from all constructed URLs.

Documentation

• README.md — added "Reusable handler fragments" section showing Partial<Matcher> spread + satisfies pattern (already designed in SPEC; just undocumented). Also documented Decode.optional() in the Decode Factories quickstart.
• docs/SPEC.md — updated matching precedence section and added baseUrl normalization note.

New files

• CHANGELOG.md — Keep-a-Changelog format. [0.9.0] = feature complete. [Unreleased] = this PR's changes.
• llms.txt — structured AI agent context file (API reference, common patterns, common mistakes). Added to package.json files so it ships with the npm package.

Tests

All 184 tests pass across Node, Chromium, Firefox, and WebKit.

[Copilot]

Pull request overview

DX-focused update that aligns runtime behavior and documentation with the library’s usability goals and docs/SPEC.md, specifically fixing response-matching precedence and removing a common baseUrl URL-resolution footgun.

Changes:

• Changed response matching to specificity-first (exact status beats class match regardless of layer), with updated unit tests + spec text.
• Normalized baseUrl to always end with / during URL construction to preserve versioned path prefixes (e.g. /v1), with new unit tests.
• Expanded documentation (README + SPEC) and added distributable project metadata files (CHANGELOG.md, llms.txt).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unit/send.test.ts	Adds unit coverage for baseUrl trailing-slash normalization behavior.
tests/unit/response-matching.test.ts	Updates/expands tests to assert specificity-first matching precedence.
src/send.ts	Normalizes baseUrl by appending a trailing / before new URL(path, baseUrl).
src/response-matching.ts	Reorders lookup logic to exact-tier first, then class-tier (request wins ties within each tier).
README.md	Documents reusable Send.match handler fragments and Decode.optional() usage.
package.json	Ships llms.txt in the published package via files.
llms.txt	Adds an AI-assistant-oriented API/patterns reference document.
docs/SPEC.md	Updates matching precedence rules and documents baseUrl normalization semantics.
CHANGELOG.md	Introduces Keep-a-Changelog formatted changelog capturing these fixes/additions.