docs: add composing-by-nesting section, fix stale claims

[mandarini]

A docs-emphasis change, plus accuracy fixes found while verifying it. No behavior changes.

Composing by nesting (new README section)

Every middleware takes the next handler directly, as withFoo(config, handler), so composition works without pipeline. FetchHandler is a type, so a consumer composing only middleware from packages that re-export it imports nothing from @supabase/middleware and never lists it in package.json. The README never said this. #21 (shipped in 0.3.0) removed the last technical reason to keep nesting quiet.

pipeline stays the lead composition story. The lede and all existing examples are untouched. skills/supabase-middleware/SKILL.md now names both forms and tells agents not to rewrite one into the other.

Accuracy fixes

Found by checking doc claims in the touched areas against source and tests:

• Authoring guide: two pre-fix: satisfies FetchHandler fails typecheck in consumer handlers if nesting depth >2 #21 sentences said the anchor is what makes the handler see upstream keys. Since fix: satisfies FetchHandler fails typecheck in consumer handlers if nesting depth >2 #21, ctx accumulates unannotated at any depth (pinned by the unannotated: test in src/core/define-middleware.test.ts); the anchor buys collision detection and the fetch-export check. The §4 sample manifest depended on ^0.1.0, a range matching no published version; now ^0.3.0. Softened "the prerequisite can never become a lie": an untyped export default { fetch: … } is unchecked, so it compiles and throws on first request.
• Core README: req.formData() is buffered like every other reader; only the raw req.body stream bypasses the cache. Added pipeline / Entry to the root-exports list.
• create-supabase-middleware skill: only path-labeled code blocks in the guide are complete files. Unlabeled blocks are { ... } fragments and must not be written to disk verbatim.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@supabase/middleware@26

commit: 0990ba3

[johnstonmatt]

awesome! the recommendation to re-export the FetchHandler type was a nice touch 🔥