docs: add contract-oriented docstrings across core, html, and pdf layers

- docs(core): document Content and ContentType canonical models
- docs(core): define BaseParser contract and parsing semantics
- docs(core): define BaseScraper contract and acquisition semantics
- docs(html): document HTML package purpose and scope
- docs(html): add HTMLParser base with DOM helpers and contracts
- docs(html): add HTTP-based HTMLScraper with content-type enforcement
- docs(pdf): document PDF package structure and public pipeline
- docs(pdf): add BasePDFClient abstraction and filesystem implementation
- docs(pdf): add PDFParser base contract for binary parsing
- docs(pdf): add PDFScraper coordinating client and Content normalization
- docs(api): expand top-level omniread module with install instructions and examples

omniread/html/__init__.py

@@ -1,3 +1,23 @@
+"""
+HTML format implementation for OmniRead.
+
+This package provides **HTML-specific implementations** of the core OmniRead
+contracts defined in `omniread.core`.
+
+It includes:
+- HTML parsers that interpret HTML content
+- HTML scrapers that retrieve HTML documents
+
+This package:
+- Implements, but does not redefine, core contracts
+- May contain HTML-specific behavior and edge-case handling
+- Produces canonical content models defined in `omniread.core.content`
+
+Consumers should depend on `omniread.core` interfaces wherever possible and
+use this package only when HTML-specific behavior is required.
+"""
+
+
 from .scraper import HTMLScraper
 from .parser import HTMLParser