mdka 2.2.2__tar.gz → 2.2.3__tar.gz

{mdka-2.2.2 → mdka-2.2.3}/.github/workflows/scripts/check-docs-examples.py

@@ -38,10 +38,30 @@ class Block:
         return f"{self.path}:{self.line}"
 
 
-def extract(root):
-    """Yield every fenced block under `root`, in document order."""
+def markdown_files(roots):
+    """Every markdown file under each root. A root may be a file or a directory.
+
+    README.md is a root in its own right, not something reachable from
+    `docs/src`. It renders on GitHub, crates.io, npmjs.com and PyPI, and it was
+    invisible to this gate until RFC 029 -- the gate built to catch broken
+    examples was pointed at a directory that excluded the most-read file in the
+    project.
+    """
+    seen, out = set(), []
+    for root in roots:
+        p = Path(root)
+        found = sorted(p.rglob("*.md")) if p.is_dir() else [p]
+        for md in found:
+            if md.resolve() not in seen:
+                seen.add(md.resolve())
+                out.append(md)
+    return out
+
+
+def extract(roots):
+    """Yield every fenced block under `roots`, in document order."""
     blocks = []
-    for md in sorted(Path(root).rglob("*.md")):
+    for md in markdown_files(roots):
         lines = md.read_text(encoding="utf-8").splitlines()
         i = 0
         while i < len(lines):
@@ -67,6 +87,42 @@ def extract(root):
     return blocks
 
 
+LINK = re.compile(r"!?\[[^\]]*\]\(([^)\s]+)")
+
+
+def check_readme_links(path):
+    """Assert README.md carries no relative or root-absolute Markdown link.
+
+    Deliberately a grep, not a link checker: nothing is resolved, followed or
+    crawled. README.md is published inside the npm tarball (four files) and
+    rendered on npmjs.com and the PyPI project page, where a relative path
+    resolves against the registry rather than the repository. `./CHANGELOG.md`,
+    `./docs/` and a root-absolute logo path were all live and broken on both
+    registries at 2.2.2.
+
+    Scoped to README.md alone. `docs/src/` is rendered by mdbook, where
+    relative links are correct and expected.
+    """
+    p = Path(path)
+    if not p.exists():
+        return []
+    # Strip fenced blocks: a `](` inside a code sample is not a link.
+    text, fenced = [], False
+    for line in p.read_text(encoding="utf-8").splitlines():
+        if line.lstrip().startswith("```"):
+            fenced = not fenced
+            continue
+        text.append("" if fenced else line)
+
+    bad = []
+    for n, line in enumerate(text, 1):
+        for target in LINK.findall(line):
+            if target.startswith("#") or "://" in target or target.startswith("mailto:"):
+                continue
+            bad.append(f"{p}:{n}: relative or root-absolute link: {target}")
+    return bad
+
+
 def runnable(blocks):
     out = []
     for b in blocks:
@@ -172,21 +228,63 @@ def check_python(blocks, workdir, python):
         except SyntaxError:
             continue
         names = set()
+        imported = set()
         for node in ast.walk(tree):
             if isinstance(node, ast.ImportFrom) and (node.module or "").split(".")[0] == "mdka":
                 names.update(a.name for a in node.names)
+                imported.update(a.asname or a.name for a in node.names)
             elif (
                 isinstance(node, ast.Attribute)
                 and isinstance(node.value, ast.Name)
                 and node.value.id == "mdka"
             ):
                 names.add(node.attr)
-        if not names:
+
+        # Keyword arguments, not just symbols. `html_to_markdown_with` resolves
+        # whether or not `preserve_unknown_attrs=True` is a real parameter --
+        # and it is not; it raises TypeError. Documenting a call that raises is
+        # worse than documenting nothing, so bind the documented kwargs against
+        # the installed signature (RFC 029 §4.2).
+        calls = []
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call) or not node.keywords:
+                continue
+            fn = node.func
+            if isinstance(fn, ast.Attribute) and isinstance(fn.value, ast.Name) and fn.value.id == "mdka":
+                target = fn.attr
+            elif isinstance(fn, ast.Name) and fn.id in imported:
+                target = fn.id
+            else:
+                continue
+            kws = [k.arg for k in node.keywords if k.arg]
+            if kws:
+                calls.append((target, kws))
+
+        if not names and not calls:
             continue
         probe = (
-            "import mdka, sys\n"
+            "import inspect, mdka, sys\n"
             f"missing = [n for n in {sorted(names)!r} if not hasattr(mdka, n)]\n"
-            "sys.exit('missing from installed mdka: ' + ', '.join(missing)) if missing else None\n"
+            "if missing:\n"
+            "    sys.exit('missing from installed mdka: ' + ', '.join(missing))\n"
+            f"problems = []\n"
+            f"for fname, kws in {calls!r}:\n"
+            "    fn = getattr(mdka, fname, None)\n"
+            "    if fn is None:\n"
+            "        problems.append(fname + ': not in installed mdka'); continue\n"
+            "    try:\n"
+            "        sig = inspect.signature(fn)\n"
+            "    except (TypeError, ValueError):\n"
+            "        continue\n"
+            "    params = sig.parameters\n"
+            "    if any(p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()):\n"
+            "        continue\n"
+            "    bad = [k for k in kws if k not in params]\n"
+            "    if bad:\n"
+            "        problems.append(fname + '() rejects: ' + ', '.join(bad))\n"
+            "if problems:\n"
+            "    sys.exit('documented call does not match the installed signature -- '\n"
+            "             + '; '.join(problems))\n"
         )
         pf = workdir / f"probe{n}.py"
         pf.write_text(probe, encoding="utf-8")
@@ -252,7 +350,9 @@ def check_ts(blocks, workdir, types_dir):
 
 def main():
     ap = argparse.ArgumentParser()
-    ap.add_argument("--root", default="docs/src")
+    ap.add_argument("--root", action="append", default=None,
+                    help="file or directory to scan; repeatable "
+                         "(default: docs/src and README.md)")
     ap.add_argument("--types", default="node", help="dir holding the generated index.d.ts")
     ap.add_argument("--python", default="", help="interpreter with mdka installed; enables symbol resolution")
     ap.add_argument("--list", action="store_true", help="list blocks and exit")
@@ -265,7 +365,8 @@ def main():
         print(f"error: --python {args.python} does not exist", file=sys.stderr)
         return 2
 
-    blocks = extract(args.root)
+    roots = args.root or ["docs/src", "README.md"]
+    blocks = extract(roots)
     run = runnable(blocks)
 
     if args.list:
@@ -291,9 +392,22 @@ def main():
         failures += check_js(by.get("js", []), wd)
         failures += check_ts(by.get("ts", []), wd, args.types)
 
-    if not failures:
-        print("\nAll runnable examples OK.")
+    link_problems = check_readme_links("README.md")
+    if link_problems:
+        print(f"\n{len(link_problems)} README link problem(s):\n")
+        for msg in link_problems:
+            print("  " + msg)
+        print(
+            "\nREADME.md ships inside the npm tarball and renders on npmjs.com\n"
+            "and the PyPI project page, where a relative path resolves against the\n"
+            "registry rather than the repository. Use an absolute URL."
+        )
+
+    if not failures and not link_problems:
+        print("\nAll runnable examples OK. README links OK.")
         return 0
+    if not failures:
+        return 1
 
     print(f"\n{len(failures)} failing example(s):\n")
     for b, err in failures:

{mdka-2.2.2 → mdka-2.2.3}/CHANGELOG.md

@@ -11,6 +11,59 @@ confidence, that is stated explicitly rather than guessed.
 
 ## [Unreleased]
 
+## [2.2.3] - 2026-09-16
+
+### Added
+
+- **`mdka --version`.** It previously failed with
+  `error: IO error: No such file or directory`, because an unrecognised
+  `-`-prefixed argument was treated as a filename. `-V` works too.
+
+### Changed
+
+- **The CLI now rejects unknown options instead of treating them as
+  filenames.** `mdka --drop-shel page.html` used to exit 0 having converted
+  nothing; it now prints `error: unknown option '--drop-shel'` with the usage
+  text and exits 1.
+
+  **This can break an existing invocation.** A file whose name begins with `-`
+  was previously converted and is now rejected. Put `--` before it:
+
+  ```
+  mdka -- -weird.html
+  ```
+
+  A bare `-` is still passed through as a path, unchanged.
+
+### Fixed
+
+- **The README's Node.js Quick Start did not parse.** It declared `const md`
+  twice, called `htmlToMarkdownWithAsync` without importing it, referenced an
+  undefined `html`, and used top-level `await` in a CommonJS example. Its Rust
+  and Python examples also used an undefined `html`. All of them now run as
+  written. This is the file rendered on GitHub, crates.io, npmjs.com and PyPI.
+- **README links and the logo now resolve outside GitHub.** The logo path was
+  root-absolute and `./docs/`, `./CHANGELOG.md` and `./ROADMAP.md` are not in
+  the published npm tarball, so all four were broken on npmjs.com and the PyPI
+  project page. They are absolute URLs now, and CI fails if a relative link is
+  reintroduced.
+- **The Python and Node.js guides documented two options that do not exist.**
+  `preserve_unknown_attrs` and `drop_presentation_attrs` are fields of the Rust
+  `ConversionOptions` but are not exposed by either binding: Python raises
+  `TypeError`, TypeScript reports `TS2353`. Three of the five deprecated
+  attribute options are reachable from the bindings, and the pages now say
+  which.
+- **`mdka --help` no longer shows a multi-file example that fails.**
+  `mdka --mode minimal --drop-shell *.html` needs `-o` for more than one input,
+  two lines below the rule saying so. Fixed in `--help` and in the README.
+- **`installation.md` no longer tells you to run `npm run build` on
+  unsupported platforms.** The published npm package contains four files and no
+  Rust source, so that could never work. It now names the three platforms with
+  prebuilt bindings and what is actually possible elsewhere.
+- **The README now carries two caveats it previously omitted**: that
+  `Balanced`, `Strict` and `Preserve` currently produce identical output, and
+  that tables are not yet converted.
+
 ## [2.2.2] - 2026-09-16
 
 ### Fixed

{mdka-2.2.2 → mdka-2.2.3}/Cargo.lock

@@ -1179,7 +1179,7 @@ dependencies = [
 
 [[package]]
 name = "mdka"
-version = "2.2.2"
+version = "2.2.3"
 dependencies = [
  "criterion",
  "dom_smoothie",
@@ -1198,16 +1198,16 @@ dependencies = [
 
 [[package]]
 name = "mdka-cli"
-version = "2.2.2"
+version = "2.2.3"
 dependencies = [
- "mdka 2.2.2",
+ "mdka 2.2.3",
 ]
 
 [[package]]
 name = "mdka-node"
-version = "2.2.2"
+version = "2.2.3"
 dependencies = [
- "mdka 2.2.2",
+ "mdka 2.2.3",
  "napi",
  "napi-build",
  "napi-derive",
@@ -1216,9 +1216,9 @@ dependencies = [
 
 [[package]]
 name = "mdka-python"
-version = "2.2.2"
+version = "2.2.3"
 dependencies = [
- "mdka 2.2.2",
+ "mdka 2.2.3",
  "pyo3",
  "rayon",
 ]

{mdka-2.2.2 → mdka-2.2.3}/Cargo.toml

@@ -3,11 +3,11 @@ members  = [".", "python"]
 resolver = "2"
 
 [workspace.dependencies]
-mdka = { version = "2.2.2", path = "." }
+mdka = { version = "2.2.3", path = "." }
 
 [package]
 name    = "mdka"
-version = "2.2.2"
+version = "2.2.3"
 edition = "2024"
 rust-version = "1.88"
 

{mdka-2.2.2 → mdka-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdka
-Version: 2.2.2
+Version: 2.2.3
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: License :: OSI Approved :: Apache Software License
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 [![npm](https://github.com/nabbisen/mdka-rs/actions/workflows/release-npm.yaml/badge.svg)](https://github.com/nabbisen/mdka-rs/actions/workflows/release-npm.yaml)
 [![PyPi](https://github.com/nabbisen/mdka-rs/actions/workflows/release-pypi.yaml/badge.svg)](https://github.com/nabbisen/mdka-rs/actions/workflows/release-pypi.yaml)
 
-![logo](/docs/src/assets/logo.png)
+![logo](https://raw.githubusercontent.com/nabbisen/mdka-rs/main/docs/src/assets/logo.png)
 
 mdka balances conversion quality with runtime efficiency —
 readable output from real-world HTML, without sacrificing speed or memory.    
@@ -49,7 +49,8 @@ CMS output, and SPA-rendered DOM without special-casing.
 no matter the nesting depth.
 - **Configurable pre-processing.**
     Five [conversion modes](#conversion-modes) let you tune what gets kept or
-stripped — from noise-free LLM input to lossless archiving.
+stripped, from noise-free LLM input to maximum retention. Three of the five
+currently produce identical output — see [Conversion Modes](#conversion-modes).
 - **Multi-language.**
     The same Rust implementation is accessible from Node.js (napi-rs) and
 Python (PyO3).
@@ -98,7 +99,7 @@ echo '<h1>Hello</h1><p><strong>world</strong></p>' | mdka
 
 ```bash
 mdka page.html                          # → page.md  (same directory)
-mdka --mode minimal --drop-shell *.html # strip nav/header/footer
+mdka --mode minimal --drop-shell -o out/ *.html  # strip nav/header/footer
 mdka --help                             # full option list
 ```
 
@@ -120,12 +121,14 @@ let md = html_to_markdown("<h1>Hello</h1><p><em>world</em></p>");
 With options:
 
 ```rust
-use mdka::{html_to_markdown_with};
+use mdka::html_to_markdown_with;
 use mdka::options::{ConversionMode, ConversionOptions};
 
+let html = "<nav>menu</nav><h1>Hello</h1>";
 let mut opts = ConversionOptions::for_mode(ConversionMode::Minimal);
 opts.drop_interactive_shell = true;
 let md = html_to_markdown_with(html, &opts);
+// "# Hello\n"
 ```
 
 ### Add to a Node.js project
@@ -135,14 +138,20 @@ npm install mdka
 ```
 
 ```js
-const { htmlToMarkdown, htmlToMarkdownWith } = require('mdka')
+const { htmlToMarkdown, htmlToMarkdownWithAsync } = require('mdka')
 
 const md = htmlToMarkdown('<h1>Hello</h1>')
-
-const md = await htmlToMarkdownWithAsync(html, {
-  mode: 'minimal',
-  dropInteractiveShell: true,
-})
+// "# Hello\n"
+
+async function main() {
+  const html = '<nav>menu</nav><h1>Hello</h1>'
+  const minimal = await htmlToMarkdownWithAsync(html, {
+    mode: 'minimal',
+    dropInteractiveShell: true,
+  })
+  console.log(minimal)
+}
+main()
 ```
 
 ### Add to a Python project
@@ -155,8 +164,10 @@ pip install mdka
 import mdka
 
 md = mdka.html_to_markdown('<h1>Hello</h1>')
+# "# Hello\n"
 
-md = mdka.html_to_markdown_with(
+html = '<nav>menu</nav><h1>Hello</h1>'
+minimal = mdka.html_to_markdown_with(
     html,
     mode=mdka.ConversionMode.Minimal,
     drop_interactive_shell=True,
@@ -175,11 +186,24 @@ md = mdka.html_to_markdown_with(
 | `Semantic` | SPA content, ARIA-aware pipelines |
 | `Preserve` | Archiving, audit trails |
 
+**`Balanced`, `Strict` and `Preserve` currently produce identical output.** They
+differ only in the defaults of five fields that have no effect, so choosing
+between them changes nothing today. They remain distinct API and may diverge
+again — see
+[Conversion Modes](https://nabbisen.github.io/mdka-rs/api/modes), which explains
+why in full.
+
+**Tables are not yet converted.** `<table>` cell text is emitted without
+structure or separators, so a table becomes a run of joined text. See
+[Supported Elements](https://nabbisen.github.io/mdka-rs/api/elements) for the
+full list of what is and is not supported.
+
 ---
 
 ## Learn More
 
-Full documentation lives in the [`docs/`](./docs/) folder, published as GitHub Pages.
+Full documentation is published as GitHub Pages, and its source lives in
+[`docs/`](https://github.com/nabbisen/mdka-rs/tree/main/docs).
 
 https://nabbisen.github.io/mdka-rs/
 
@@ -198,8 +222,8 @@ https://nabbisen.github.io/mdka-rs/
 | Performance Characteristics | [/design/performance-characteristics](https://nabbisen.github.io/mdka-rs/design/performance-characteristics) |
 | Architecture | [/design/architecture](https://nabbisen.github.io/mdka-rs/design/architecture) |
 | Features | [/design/features](https://nabbisen.github.io/mdka-rs/design/features) |
-| Changelog | [CHANGELOG.md](./CHANGELOG.md) |
-| Roadmap | [ROADMAP.md](./ROADMAP.md) |
+| Changelog | [CHANGELOG.md](https://github.com/nabbisen/mdka-rs/blob/main/CHANGELOG.md) |
+| Roadmap | [ROADMAP.md](https://github.com/nabbisen/mdka-rs/blob/main/ROADMAP.md) |
 
 ---
 

{mdka-2.2.2/python → mdka-2.2.3}/README.md

@@ -13,7 +13,7 @@
 [![npm](https://github.com/nabbisen/mdka-rs/actions/workflows/release-npm.yaml/badge.svg)](https://github.com/nabbisen/mdka-rs/actions/workflows/release-npm.yaml)
 [![PyPi](https://github.com/nabbisen/mdka-rs/actions/workflows/release-pypi.yaml/badge.svg)](https://github.com/nabbisen/mdka-rs/actions/workflows/release-pypi.yaml)
 
-![logo](/docs/src/assets/logo.png)
+![logo](https://raw.githubusercontent.com/nabbisen/mdka-rs/main/docs/src/assets/logo.png)
 
 mdka balances conversion quality with runtime efficiency —
 readable output from real-world HTML, without sacrificing speed or memory.    
@@ -37,7 +37,8 @@ CMS output, and SPA-rendered DOM without special-casing.
 no matter the nesting depth.
 - **Configurable pre-processing.**
     Five [conversion modes](#conversion-modes) let you tune what gets kept or
-stripped — from noise-free LLM input to lossless archiving.
+stripped, from noise-free LLM input to maximum retention. Three of the five
+currently produce identical output — see [Conversion Modes](#conversion-modes).
 - **Multi-language.**
     The same Rust implementation is accessible from Node.js (napi-rs) and
 Python (PyO3).
@@ -86,7 +87,7 @@ echo '<h1>Hello</h1><p><strong>world</strong></p>' | mdka
 
 ```bash
 mdka page.html                          # → page.md  (same directory)
-mdka --mode minimal --drop-shell *.html # strip nav/header/footer
+mdka --mode minimal --drop-shell -o out/ *.html  # strip nav/header/footer
 mdka --help                             # full option list
 ```
 
@@ -108,12 +109,14 @@ let md = html_to_markdown("<h1>Hello</h1><p><em>world</em></p>");
 With options:
 
 ```rust
-use mdka::{html_to_markdown_with};
+use mdka::html_to_markdown_with;
 use mdka::options::{ConversionMode, ConversionOptions};
 
+let html = "<nav>menu</nav><h1>Hello</h1>";
 let mut opts = ConversionOptions::for_mode(ConversionMode::Minimal);
 opts.drop_interactive_shell = true;
 let md = html_to_markdown_with(html, &opts);
+// "# Hello\n"
 ```
 
 ### Add to a Node.js project
@@ -123,14 +126,20 @@ npm install mdka
 ```
 
 ```js
-const { htmlToMarkdown, htmlToMarkdownWith } = require('mdka')
+const { htmlToMarkdown, htmlToMarkdownWithAsync } = require('mdka')
 
 const md = htmlToMarkdown('<h1>Hello</h1>')
-
-const md = await htmlToMarkdownWithAsync(html, {
-  mode: 'minimal',
-  dropInteractiveShell: true,
-})
+// "# Hello\n"
+
+async function main() {
+  const html = '<nav>menu</nav><h1>Hello</h1>'
+  const minimal = await htmlToMarkdownWithAsync(html, {
+    mode: 'minimal',
+    dropInteractiveShell: true,
+  })
+  console.log(minimal)
+}
+main()
 ```
 
 ### Add to a Python project
@@ -143,8 +152,10 @@ pip install mdka
 import mdka
 
 md = mdka.html_to_markdown('<h1>Hello</h1>')
+# "# Hello\n"
 
-md = mdka.html_to_markdown_with(
+html = '<nav>menu</nav><h1>Hello</h1>'
+minimal = mdka.html_to_markdown_with(
     html,
     mode=mdka.ConversionMode.Minimal,
     drop_interactive_shell=True,
@@ -163,11 +174,24 @@ md = mdka.html_to_markdown_with(
 | `Semantic` | SPA content, ARIA-aware pipelines |
 | `Preserve` | Archiving, audit trails |
 
+**`Balanced`, `Strict` and `Preserve` currently produce identical output.** They
+differ only in the defaults of five fields that have no effect, so choosing
+between them changes nothing today. They remain distinct API and may diverge
+again — see
+[Conversion Modes](https://nabbisen.github.io/mdka-rs/api/modes), which explains
+why in full.
+
+**Tables are not yet converted.** `<table>` cell text is emitted without
+structure or separators, so a table becomes a run of joined text. See
+[Supported Elements](https://nabbisen.github.io/mdka-rs/api/elements) for the
+full list of what is and is not supported.
+
 ---
 
 ## Learn More
 
-Full documentation lives in the [`docs/`](./docs/) folder, published as GitHub Pages.
+Full documentation is published as GitHub Pages, and its source lives in
+[`docs/`](https://github.com/nabbisen/mdka-rs/tree/main/docs).
 
 https://nabbisen.github.io/mdka-rs/
 
@@ -186,8 +210,8 @@ https://nabbisen.github.io/mdka-rs/
 | Performance Characteristics | [/design/performance-characteristics](https://nabbisen.github.io/mdka-rs/design/performance-characteristics) |
 | Architecture | [/design/architecture](https://nabbisen.github.io/mdka-rs/design/architecture) |
 | Features | [/design/features](https://nabbisen.github.io/mdka-rs/design/features) |
-| Changelog | [CHANGELOG.md](./CHANGELOG.md) |
-| Roadmap | [ROADMAP.md](./ROADMAP.md) |
+| Changelog | [CHANGELOG.md](https://github.com/nabbisen/mdka-rs/blob/main/CHANGELOG.md) |
+| Roadmap | [ROADMAP.md](https://github.com/nabbisen/mdka-rs/blob/main/ROADMAP.md) |
 
 ---
 

{mdka-2.2.2 → mdka-2.2.3}/ROADMAP.md

@@ -1,9 +1,10 @@
 # mdka — Roadmap
 
 **Status.** Active — planning baseline approved by the project owner on 2026-08-02.
-**Current version.** 2.2.2 (released 2026-09-16)
-**Milestone progress.** M1, M1b, M2 and **M2b complete**. `2.2.1` shipped RFC 020;
-`2.2.2` shipped RFC 007, 021, 022, 023, 026 and 027. **M3 is next.**
+**Current version.** 2.2.3 (released 2026-09-16)
+**Current version note.** `2.2.1` shipped RFC 020; `2.2.2` shipped RFC 007, 021,
+022, 023, 026 and 027; `2.2.3` shipped RFC 029.
+**Milestone progress.** M1, M1b, M2, M2b and **M2c complete**. **M3 is next.**
 **Governance.** RFC lifecycle follows [RFC 000](./rfcs/done/000-rfc-lifecycle-policy.md).
 
 This document is the planning baseline from which the RFC portfolio is derived.
@@ -382,6 +383,49 @@ These gates narrow what the consumer pass has to catch; they do not replace it.
 **Do not describe this set as complete coverage.** Four green checkmarks mean
 the Linux artifacts install and the documented examples resolve — nothing more.
 
+### M2c · Published-surface repair → `2.2.3` (patch) — ✅ COMPLETE
+
+From the **first consumer pass** (RFC 027 Rule 1), run against published `2.2.2`
+by a session with no history of this project. Disposition:
+`.git-exclude/reviewed/2.2.2-consumer-pass/README.md`.
+
+| RFC | Title | Priority | Size |
+|---|---|---|---|
+| 029 | Published-surface documentation repair | **P0** | S |
+
+**Why a patch of its own.** The README's Node Quick Start does not parse, and it
+renders on GitHub, crates.io, npm and PyPI. `usage-python.md` documents a keyword
+argument that raises `TypeError`. Both are live; neither should wait behind M3's
+renderer work.
+
+#### What the consumer pass exposed about our controls
+
+**`README.md` has never been in scope for any documentation RFC.** RFC 023's
+boundary was `docs/src/getting-started/`; RFC 007's was six source files. The
+most-read file in the project sat outside every one — **the third scope-boundary
+miss this milestone**, after RFC 022's `examples/` consumers and RFC 007's count
+table.
+
+RFC 027 Rule 2 now requires boundaries be derived from a search. **That is
+necessary and was not sufficient**: a search only covers what you think to
+search for.
+
+**The docs-example gate could not see it either** — `--root` defaults to
+`docs/src`. And it checks symbol resolution, not keyword arguments, so the
+Python defect was invisible twice over. Both recorded as corrections on RFC 026;
+both fixed by RFC 029.
+
+**One finding went to M3, not here.** F-04 — link text silently losing spaces
+inside `<a>` — shares RFC 024's root cause but has a worse symptom: `****[b](/x)`
+is visibly wrong, `[Readmore now]` reads as prose with a word gone. Added to
+RFC 024 as an explicit acceptance criterion so it cannot be fixed by accident.
+
+**Recorded, not scheduled:** F-24, deep nesting is quadratic — 25k depth 0.72s,
+100k 10.5s, 300k 255s. The README's "no stack overflow at any depth" claim holds;
+the failure mode moved from crash to hang. M4. And F-23, default `Balanced`
+emitting 1,190 `<a id>` anchors on a real Wikipedia page — a design question
+shared with bekoedit's item 8, not a defect.
+
 ### M3 · Conversion fidelity → `2.3.0` (minor)
 
 Purely additive element coverage. Tables are the largest known gap against the