docs: document the public API as TSDoc (generated from type declarations)

[lucas-tortora]

Document the public API as TSDoc

Adds TSDoc — @param / @returns / @throws tags plus member descriptions — to the shipped .d.ts. Everything is derived from the existing type declarations and this module's own index.js/lib source.

The README's ## API section links to the generated reference instead of inlining it, per the pattern settled on in bare-fs #44. Comments are wrapped to keep every line within 100 columns.

Reviewed against source; happy to adjust wording, scope, or split as you prefer.

🤖 Generated with Claude Code

[lucas-tortora]

A quick note for reviewers on CI status:

• The chore: … Prettier … commit here is formatting-only — it aligns the generated README.md ## API block and the shipped .d.ts with prettier --check .. The repo pins Prettier ^3.x, so CI resolves the latest 3.x, which formats a little differently from older 3.x; these updates were needed for the Prettier step to pass.
• The remaining Lint failure is pre-existing and unrelated to this change: lunte reports Identifier '<name>' has already been declared for the declare class X + declare namespace X merges in lib/{build,generate,install,test}.d.ts, plus pre-existing require-await warnings in .js files this PR does not touch. It reproduces on the base branch with no TSDoc applied (verified by running lunte on the pre-PR file), so it isn't introduced here. Out of scope for a docs-only PR, but happy to help address it separately if useful.

Generated by the pear-docs bare-refgen tooling.