brewdoc 0.2.0__tar.gz

brewdoc-0.2.0/.gitattributes

@@ -0,0 +1 @@
+tests/fixtures/** -text

brewdoc-0.2.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

brewdoc-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-26, windows-2025]
+        python: ["3.12"]
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          version: "0.12.13"
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --group dev
+      - run: uv run --locked pytest -q --strict-markers -m "not corpus"

brewdoc-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          version: "0.12.13"
+          python-version: "3.12"
+      - name: tag must equal v + project.version
+        run: |
+          VERSION=$(uv run --no-project python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          [ "$GITHUB_REF_NAME" = "v$VERSION" ] || { echo "tag $GITHUB_REF_NAME != v$VERSION"; exit 1; }
+      - run: uv lock --check
+      - run: uv build
+      - uses: actions/upload-artifact@v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: dist
+          path: dist/
+      # trusted publishing: OIDC token exchange, no stored PyPI token
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+
+  github-release:
+    needs: [build, publish]
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v3.0.3
+        with:
+          files: dist/*

brewdoc-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/

brewdoc-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

brewdoc-0.2.0/FORMATS.md

@@ -0,0 +1,189 @@
+# Formats
+
+What brewdoc reads today, what is planned, what is deferred and what it will never do. Base runtime
+dependencies are `pdfplumber` and `python-calamine`. Static HTML adds one conditional native parser;
+other formats retain the two-dependency policy.
+
+## Supported
+
+| in | reader | mechanism |
+|---|---|---|
+| `.pdf` | pdfplumber | text layer required; anchored page units; each region routed by its own ruling |
+| `.docx` | stdlib `zipfile` + `xml.etree` | paragraphs and tables in reading order; anchored chapters retain duplicate and empty headings |
+| `.pptx` | stdlib `zipfile` + `xml.etree` | slides in declared order; text, tables, speaker notes and picture metadata placeholders |
+| `.xlsx` `.xlsm` `.xls` `.xlsb` `.ods` | python-calamine | exact sheet selection in caller order with full-source ordinal keys; cached values in Markdown |
+| `.html` | selectolax Lexbor | local static body or fragment in DOM order; one anchored chapter; CPython 3.12-3.14 only |
+
+All supported routes emit `brewdoc.markdown/2`: quoted source title, deterministic metadata,
+artifact inventory, known omissions, linked contents, then anchored content units. Empty physical
+PDF pages, selected empty sheets, heading-created empty DOCX chapters, and declared empty or hidden
+PPTX slides remain navigable.
+
+Every receipt line uses `brewdoc.receipt/1`, which names the route (`pdf`, `doc`, `presentation`,
+`sheet`, `html`), its unit kind (`page`, `chapter`, `slide`, `sheet`) and how many units were rendered. The
+unit kind decides the content keys: `page/000001`, `chapter/000001`, `slide/000001`,
+`sheet/000001`. A suffix brewdoc does not read is refused with route `none` and unit kind `none`;
+every other refusal keeps its route's own name and unit kind, with zero units.
+
+## Static HTML
+
+HTML requires CPython 3.12-3.14 and this exact marked dependency:
+
+```text
+selectolax==0.4.13; python_version < '3.15' and platform_python_implementation == 'CPython'
+```
+
+Brewdoc's overall Python requirement remains `>=3.12`. The `.html` suffix and `render_html`
+API remain registered on other runtimes and explicitly refuse with route `html`, kind `chapter`,
+zero units, empty Markdown and no output writes. Self-check verifies this refusal and all old
+formats. A missing or broken native parser on supported CPython is an environment failure:
+HTML refuses and self-check exits 1. There is no alternate parser.
+
+Read the full recovered body or fragment, including navigation, main content, sidebars and footer.
+The first nonempty recovered head title labels `chapter/000001`; otherwise use `Untitled`.
+Only `.html` is accepted. Input must be strict UTF-8, optionally prefixed by a UTF-8 BOM.
+Charset declarations in the first 1,024 bytes after the BOM must name `utf-8` or `utf8`;
+malformed, unknown, conflicting or non-UTF-8 declarations refuse. Invalid bytes are not repaired.
+HTML preserves meaningful Unicode and emits UTF-8 without BOM, with LF newlines. Other routes
+retain ASCII output. HTML has no artifacts.
+
+Headings, prose, lists and emphasis retain recovered DOM order. Preformatted code preserves
+literal angle brackets, ampersands, newlines, tabs and repeated spaces in a fence longer than
+any source backtick run. Inline code outside tables uses the same fenced-block fallback at its
+reading-order position, omitting inline layout. Table-cell code uses `Code: text="..."` with
+escaped literal data, omitting monospace layout. Literal LF, tab and CR in cell code and quoted
+control metadata become `&#10;`, `&#9;` and `&#13;` after escaping source ampersands.
+Emphasis and safe links balance separately around each nonempty text segment across a fence.
+Code-only emphasis adds no delimiter paragraphs. A safe anchor enclosing only literal code or
+image placeholders retains its destination once as `[Link target](destination)` after that content.
+Ordinary text links and existing cell links around code/images get no duplicate fallback.
+Safe anchors consumed inside code/pre retain labelled records after the literal representation:
+`[Link target](destination); text="..."`. Records keep recovered source order in body paragraphs
+or the same table cell. Labels preserve Unicode, repeated spaces and decoded characters with
+the quoted literal escaping above, including escaped source quotes. Retained literal whitespace
+is data; an anchor without retained characters is empty. Hidden/excluded, unsafe/missing-target
+or empty anchors add no record.
+Each body target paragraph counts once in `text_regions`; cell target fragments add no regions
+or tables. Each consumed source anchor adds one record; separate anchors with identical URLs
+stay distinct. Nested code/pre do not duplicate those records.
+Quotes use matching `Quote (level N):` and `End quote (level N).` paragraphs around their
+children, preserving nested scopes and order without Markdown blockquote layout.
+
+Plain list items emit their marker once; later paragraphs use blank lines and continuation
+indentation. Items containing a standalone fence, table/caption, control record, image placeholder
+or quote use `List item (level N, marker "-"):` and `End list item (level N).` boundaries.
+Ordered markers retain their number. Affected ancestor items use the same scopes so all child
+blocks stay enclosed in DOM order. Plain nested items inside a labelled scope use indentation
+relative to that scope; unaffected lists keep normal Markdown layout. Each emitted paragraph,
+literal block, control or link-target record counts once, including list continuations.
+List/quote boundary labels and empty or delimiter-only fragments add no text regions.
+
+Tables keep captions and recovered row/cell order across head, body and foot sections. Spans
+expand into a rectangular grid with origin content once and empty continuations. Nested tables
+stay inside their parent cell as labelled row/column records with origin coordinates and spans.
+Controls preserve source-declared fields, values and boolean attribute presence in fixed-order
+records. Forms, labels, fieldsets, buttons, inputs, textarea/output, every select option and
+datalist suggestion, progress/meter and details/summary stay in source order. Closed details,
+unselected options and disabled controls remain present. Missing attributes are `unspecified`;
+supplied empty strings remain empty. Browser defaults and current user values are not inferred.
+Supplied password/file input values are redacted; hidden inputs are omitted explicitly.
+
+Only HTTP, HTTPS, mailto, relative and fragment link targets become links after normalized scheme
+checks. Other targets are inert text; form actions and overrides always remain inert metadata.
+Images preserve supplied alt/title and source category in a placeholder without pixels or fetching.
+Data, unsupported and missing image targets are omitted. Source Markdown/HTML is escaped;
+source IDs never become output anchors.
+
+Comments, head content, scripts, styles, templates and active embeds are excluded. Direct `hidden`,
+`aria-hidden="true"`, effective inline `display:none` or `visibility:hidden` exclude whole
+subtrees. Inline declarations respect supported values, order and `!important`; external and
+embedded stylesheets are not evaluated. Unknown nonexcluded elements retain useful children.
+SVG title/description/text, canvas fallback and body noscript text remain available. Omissions
+name graphical SVG, canvas pixels, MathML semantics, active media and dynamic browser content.
+This is static source conversion, not browser-complete extraction.
+
+Limits are inclusive; exceeding one refuses before writing output. MiB is 1,048,576 bytes:
+8 MiB raw input, depth 256 (recovered root at 1), 200,000 recovered elements including excluded
+subtrees, 1 MiB UTF-8 per decoded attribute, 32 MiB included decoded text before whitespace
+reduction, 100,000 total span-expanded table positions including nested tables, and 64 MiB final
+UTF-8 Markdown including the envelope. Postparse checks do not guarantee native-parser memory safety.
+
+## Container documents
+
+DOCX accepts Transitional and Strict WordprocessingML. Main-story paragraphs and tables stay in
+document order. `Title` and `Heading1` through `Heading9` start chapters. Tabs become spaces and
+line breaks are retained. Nested table text is flattened into its parent cell, and invalid or
+non-positive table spans fall back to one column. Images, headers, footers, footnotes, comments,
+tracked-change reconstruction, list formatting, style inheritance and vertical merge reconstruction
+are omitted.
+
+PPTX follows the presentation relationships and declared slide list instead of ZIP member names.
+It reads every declared slide, including hidden and empty slides. Title placeholders label units;
+slides without one use `Untitled`. Headings are `## Slide N: "<title>"`, with ordered keys such as
+`slide/000001`. The public `render_presentation` tally reports `slides`; there is no Slides metadata
+row. Shape and grouped-shape XML order controls reading order. Text keeps paragraph and run order,
+DrawingML tables keep row and cell order, and merge continuation cells stay empty. Body speaker
+notes follow slide content. Other notes placeholders are omitted.
+
+PPTX pictures use this exact metadata placeholder and never include pixels:
+
+```text
+Image: name="<name>"; size=<cx>x<cy> EMU; alt="<descr|none>"; caption="<title|none>"; source=<embedded|external>; bytes=<n|unknown>
+```
+
+Embedded picture byte counts come from the related package member. External pictures are never
+fetched. Charts, SmartArt, audio, video, embedded objects, animations, transitions,
+layout/master-only text, styling and visual positioning are omitted. Required package, presentation
+and slide relationships or XML must resolve inside the archive; malformed or missing required parts
+refuse the document. A slide may have no picture or notes relationship, but a referenced part must
+be valid. PPTX is the only supported container that promises image placeholders. DOCX images
+remain omitted.
+
+## Workbook artifacts
+
+| input | formulas | VBA project | limit |
+|---|---|---|---|
+| `.xlsx` | `brewdoc.formulas/1` JSON per selected formula-bearing sheet | unavailable | formulas are copied without evaluation, rewriting, or dependency inference |
+| `.xlsm` | same as `.xlsx` | one related `vbaProject.bin`, when present | exact opaque bytes only |
+| `.xlsb` | unavailable through the pinned Python binding | one related `vbaProject.bin`, when present | exact opaque bytes only |
+| `.xls` `.ods` | unavailable through the pinned Python binding | unavailable | cached values still render |
+
+Readable VBA source modules are unavailable for every format. Module and script counts are unknown,
+and brewdoc never executes a project. Generic formula and VBA artifact output uses explicit stable
+keys; the typed Python formula API can also enumerate selected formula sheets. Artifact requests do
+not change Markdown bytes.
+
+## Planned
+
+Planned means not readable today: every suffix below is refused by name, and the receipt says so.
+No further parser dependency is planned. Each format requires its own acceptance task.
+Order = implementation order, by value for agents.
+
+| # | in | mechanism | output |
+|---|---|---|---|
+| 1 | `.csv` `.tsv` | `csv` | one Markdown table |
+| 2 | `.odt` `.odp` | `zipfile` + `content.xml` | paragraphs, tables; one chapter per slide for `.odp` |
+| 3 | `.epub` | `zipfile` + XHTML chapters; parser reuse requires separate acceptance | one chapter per spine item |
+| 4 | `.md` `.txt` | pass-through | bytes unchanged, receipt still emitted |
+| 5 | `.eml` | `email` | headers, text body, attachment names |
+
+Image behavior for planned containers is not accepted yet. Never OCR.
+
+Eight planned suffixes share five adapter modules: `.csv` with `.tsv`, `.odt` with `.odp`, and
+`.md` with `.txt` each pair into one module, the other two rows take one each. Eleven source
+modules including HTML, sixteen at all planned formats. Each format is its own task and follows the ordered
+checklist in [`docs/architecture.md`](docs/architecture.md); a new source module needs explicit
+user approval.
+
+## Deferred
+
+Not in any current plan.
+
+| in | reason |
+|---|---|
+| `.doc` `.ppt` (legacy binary) | OLE2 container, Word 97 piece table; needs `olefile` or an own CFB reader; text only, tables lossy |
+| `.rtf` | own parser required |
+
+## Never
+
+OCR, ML layout models, network. A page without a text layer is reported in the receipt, not guessed.

brewdoc-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksim Kochetkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brewdoc-0.2.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: brewdoc
+Version: 0.2.0
+Summary: Brew any document into LLM-ready Markdown: PDF tables, spreadsheets, docx - no ML, deterministic, with a JSON receipt
+Project-URL: Homepage, https://github.com/kochetkov-ma/brewdoc
+Project-URL: Repository, https://github.com/kochetkov-ma/brewdoc
+Project-URL: Issues, https://github.com/kochetkov-ma/brewdoc/issues
+Author-email: Maksim Kochetkov <apmatypa88@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: docx,llm,markdown,pdf,rag,table-extraction,xlsx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.12
+Requires-Dist: pdfplumber==0.11.10
+Requires-Dist: python-calamine==0.8.2
+Requires-Dist: selectolax==0.4.13; python_version < '3.15' and platform_python_implementation == 'CPython'
+Description-Content-Type: text/markdown
+
+# brewdoc
+
+Document to Markdown for agent systems: PDF, Word, PPTX presentations, spreadsheets and static
+HTML in, one Markdown file plus a JSON receipt out. No models, no OCR, no network,
+deterministic (same file, same bytes). The receipt says what was rendered,
+what was dropped and what the route structurally cannot carry, so an agent never mistakes a
+silent gap for "the document does not say so".
+
+## Install
+
+| channel | command |
+|---|---|
+| pip | `pip install brewdoc==0.2.0` |
+| uvx | `uvx brewdoc==0.2.0 file.pdf` |
+| uv tool | `uv tool install brewdoc==0.2.0` |
+| Docker | `RUN pip install brewdoc==0.2.0` |
+
+Alternative, straight from git (no PyPI round-trip):
+
+```
+uvx --from git+https://github.com/kochetkov-ma/brewdoc@v0.2.0 brewdoc file.pdf
+```
+
+Requires Python >= 3.12. Base runtime dependencies: `pdfplumber` (pulls pypdfium2, Pillow,
+cryptography) and `python-calamine`. HTML requires CPython 3.12-3.14 and the native Lexbor
+parser from this exact conditional dependency:
+
+```text
+selectolax==0.4.13; python_version < '3.15' and platform_python_implementation == 'CPython'
+```
+
+Other runtimes retain the `.html` route and Python API but explicitly refuse HTML. On supported
+CPython, a missing or broken parser is an environment failure and `--self-check` exits 1.
+On an unsupported HTML runtime, self-check verifies HTML refusal and checks all other formats.
+
+## Usage
+
+```
+brewdoc file.pdf --out file.md
+brewdoc slides.pptx --out slides.md
+brewdoc page.html --out page.md
+brewdoc file.xlsx                # no --out: receipt line, then the Markdown, on stdout
+brewdoc file.xlsx --sheet Calc --sheet Inputs
+brewdoc file.xlsm --artifact formula/sheet/000002=formulas.json
+brewdoc file.xlsm --artifact vba/project/000001=vbaProject.bin
+brewdoc --self-check             # renders synthetic fixtures twice, compares sha256, exit 0 when green
+```
+
+`--sheet` is repeatable. Names are exact and case-sensitive. Output follows caller order while
+keeping each sheet's full-workbook ordinal. `--artifact` is also repeatable. Use keys listed in the
+Markdown artifact table. Both options are workbook-only. brewdoc validates every request and
+output collision before writing.
+
+Every successful document uses `brewdoc.markdown/2`. A quoted source title is followed by Metadata,
+Artifacts, Known omissions, Contents, then anchored content units. PDF keys are `page/000001`,
+workbook keys are `sheet/000001`, DOCX keys are `chapter/000001`, PPTX keys are `slide/000001`,
+and HTML has one `chapter/000001`.
+Metadata contains deterministic source identity, selection, content hashes, conversion tallies, and
+artifact capabilities. It excludes paths, timestamps, permissions, host data, and unsupported author
+metadata.
+
+One JSON receipt line always goes to stdout first (wrapped here, `unit_keys` omitted):
+
+```json
+{"artifacts": [], "broken_ligature_words": 0, "columns_split": 1,
+ "dropped": {"cid_survivors": 0, "control_chars": 0, "ligatures": 0, "nbsp": 0,
+             "non_ascii_replaced": 0, "page_numbers": 3, "pua_glyphs": 0,
+             "running_heads": 0, "soft_hyphens": 0},
+ "file_ok": true, "markdown_schema": "brewdoc.markdown/2",
+ "not_carried": ["images, figures and the text drawn inside them",
+                 "a table that spans a page break",
+                 "text rotated out of the horizontal reading order"],
+ "out": "file.md",
+ "reason": "pdf rendered: 7 pages, 1 tables, 26 text regions, 1 column splits",
+ "receipt_schema": "brewdoc.receipt/1",
+ "route": "pdf", "source": "nist-sp800-145.pdf", "tables": 1,
+ "text_regions": 26, "unit_kind": "page", "units": 7}
+```
+
+| key | meaning |
+|---|---|
+| `file_ok`, `reason` | `false` when the file was refused (no text layer, unreadable, unsupported suffix); `reason` names why, or summarises what was rendered |
+| `route` | which reader ran: `pdf`, `doc`, `presentation`, `sheet` or `html` |
+| `source` | the input file name, without its directory |
+| `unit_kind`, `units` | the route's content unit and how many were rendered; one pair for every format. `page` for PDF, `chapter` for DOCX and HTML, `slide` for PPTX, `sheet` for a workbook, and `none` on a suffix brewdoc does not read |
+| `tables`, `text_regions`, `columns_split` | what else was rendered |
+| `receipt_schema` | the receipt key contract; `brewdoc.receipt/1` replaced the per-format `pages` and `sheets` counters |
+| `broken_ligature_words` | words with a ligature the font mapped to a stray code point, folded to ASCII, not repaired |
+| `dropped` | sanitised items removed on purpose, counted by kind (running heads, page numbers, ...) |
+| `not_carried` | what this route structurally cannot represent - read it before concluding a fact is absent |
+| `out` | the Markdown path, or `null` when it went to stdout |
+| `markdown_schema`, `unit_keys` | the contract and ordered full-source content keys; success only |
+| `artifacts` | available keyed formula or opaque VBA outputs and requested output paths; success only |
+| `selected_sheets` | the `--sheet` names in caller order; present only when sheets were selected |
+
+Paths resolve against the current working directory; `--out` creates parent directories.
+Exit code is non-zero on refusal; the receipt line is still printed.
+
+## Formats
+
+| in | reader | notes |
+|---|---|---|
+| `.pdf` | pdfplumber | needs a text layer; route chosen per region, never per page |
+| `.docx` | stdlib zip + XML | paragraphs and tables |
+| `.pptx` | stdlib zip + XML | slides in declared order; text, tables, notes and picture metadata |
+| `.xlsx` `.xlsm` `.xls` `.xlsb` `.ods` | python-calamine | selected sheets keep full-source ordinals; numbers as stored (`85.0`), dates as ISO days |
+| `.html` | selectolax Lexbor | full static body or fragment, complete tables and source-declared controls; CPython 3.12-3.14 |
+
+`.xlsx` and `.xlsm` expose original OOXML formulas as one deterministic JSON artifact per
+formula-bearing selected sheet. Markdown still contains cached values. `.xlsm` and `.xlsb` can expose
+one complete related `vbaProject.bin` as opaque bytes. brewdoc does not execute macros, decompile VBA,
+report source-module counts, evaluate formulas, or infer dependency graphs.
+
+HTML reads local strict UTF-8, with an optional BOM. It preserves meaningful Unicode, navigation,
+main content, sidebars and footers in recovered DOM order. It never fetches links or resources,
+executes scripts, submits forms or infers interactive values. Links use a restricted scheme policy;
+form actions remain inert metadata. Inline code outside tables becomes a literal fenced block;
+surrounding emphasis and links remain balanced. Safe links in literal code and around code/images
+retain destination records without changing the source literals. Table-cell code uses labelled
+escaped text. Quotes and list items containing standalone child blocks use explicit nesting
+boundaries in place of visual Markdown
+containers. Plain list paragraphs retain their item marker and continuation indentation.
+See [HTML scope and limits](FORMATS.md#static-html).
+
+The public Python API exposes HTML and presentation rendering and generic workbook artifact access:
+
+```python
+import brewdoc
+
+markdown, tally = brewdoc.render_html("page.html")
+code, receipt, markdown = brewdoc.run("page.html", out="page.md")
+markdown, tally = brewdoc.render_presentation("slides.pptx")
+refs = brewdoc.list_book_artifacts("book.xlsm", sheets=("Calc",))
+payload = brewdoc.read_book_artifact("book.xlsm", refs[0].key, sheets=("Calc",))
+code, receipt, markdown = brewdoc.run(
+    "book.xlsm", out="book.md", sheets=("Calc",),
+    artifact_outputs={refs[0].key: "formulas.json"},
+)
+```
+
+`artifact_outputs` maps artifact keys to paths. The CLI builds it from repeated `--artifact KEY=PATH`.
+
+Planned formats, deferred ones and the never-list: `FORMATS.md`.
+A planned format is refused by name today. The adapter contract and the ordered checklist for
+adding one are in [`docs/architecture.md`](docs/architecture.md).
+
+PDF regions, in the order tried:
+
+| region looks like | rendered as |
+|---|---|
+| ruled on all sides | Markdown table from the drawn ruling |
+| ruling unfinished (cells never closed) | re-read on the grid the ruling implies, kept only when it carries more text than the drawn ruling did |
+| ruled across only (head and foot rules) | column grid from the rule segment ends |
+| unruled, tabular band | layout-preserved text |
+| unruled, captioned `Table N` | the band is bounded first (caption to next blank band), then read as a table |
+| two-column prose | split at the gutter (relative density on the character x-histogram), left then right |
+| plain prose | lines |
+
+## What it does not do
+
+| gap | behaviour |
+|---|---|
+| OCR | a PDF with no text layer is refused by name, never rendered empty |
+| PDF and DOCX images, figures, text drawn inside them | not carried; listed in `not_carried` |
+| PPTX pictures | represented by deterministic name, size, alt text, caption, source and byte-count placeholders; pixels are never emitted |
+| PPTX charts, SmartArt, audio, video and embedded objects | not carried; listed in `not_carried` |
+| a table spanning a page break | columns recovered, wrapped rows stay separate rows |
+| text rotated out of horizontal reading order | not carried |
+| sub/superscripts | folded back into their line (`NH4H2PO4`, not `NHHPO` over `4 2 4`) |
+| broken font CMaps (ligatures mapped to wrong code points) | counted (`broken_ligature_words`), folded to ASCII, never guessed back |
+| formula calculation | cached values in Markdown; passive source formulas only for `.xlsx` and `.xlsm` |
+| readable VBA source | unavailable; `.xlsm` and `.xlsb` preserve a related project only as opaque bytes |
+
+## Determinism
+
+No timestamps or unordered iteration. Two renders of one file have the same sha256;
+`--self-check` pins it. PDF, DOCX, PPTX and workbook output remains ASCII. HTML Markdown uses
+UTF-8 without BOM and LF newlines, with the same bytes in the API, file output and CLI stdout.
+Receipt JSON keeps ASCII escaping.
+
+## Size and speed
+
+These measurements cover the existing PDF/workbook baseline before the HTML parser addition.
+They do not measure HTML conversion or the new installed footprint.
+
+| measure | value |
+|---|---|
+| installed footprint | ~45 MB (pdfplumber, pypdfium2, Pillow, cryptography, python-calamine) |
+| import | 0.08 s |
+| 130-page PDF | ~5.5 s |
+| 14-sheet xlsx | ~0.9 s |
+
+## Benchmarks
+
+Browse the [corpus catalog](benchmarks/CATALOG.md), follow the
+[measurement method](benchmarks/METHODOLOGY.md), and inspect the
+[full-run results](benchmarks/results/README.md). Completed runs include actual
+outputs and known failures; capture completion does not mean content quality passed.
+
+## Releasing
+
+Tag-triggered, see `RELEASING.md`.
+
+## License
+
+MIT, see `LICENSE`.