diff --git a/.github/refresh-reviewers/tests/test_inputs_docs.py b/.github/refresh-reviewers/tests/test_inputs_docs.py
index 1659c471..65e359f3 100644
--- a/.github/refresh-reviewers/tests/test_inputs_docs.py
+++ b/.github/refresh-reviewers/tests/test_inputs_docs.py
@@ -15,12 +15,13 @@
 * `on.workflow_call.inputs` in `.github/workflows/refresh-reviewers.yml`, and
 * the "Inputs" table in `docs/callers/refresh-reviewers.md`.
 
-This is deliberately a TWO-set check. `.github/refresh-reviewers/README.md`'s
-"Knob defaults (and why)" table is intentionally partial (it omits
-`reviewer_config_path`, `map_exclude`, `extra_exclude_paths` and `workflows_ref`)
-and uses combined-cell rows (`| `top_k` / `floor` |`), so the bare-name table
-regex neither captures nor should capture it — including it would make this test
-permanently red or vacuous.
+The guide's Inputs table is checked for full set-equality in BOTH directions.
+`.github/refresh-reviewers/README.md`'s "Knob defaults (and why)" table is
+intentionally partial (it omits `reviewer_config_path`, `map_exclude`,
+`extra_exclude_paths` and `workflows_ref`), so it is checked ONE way only — no
+phantom knob — but its combined-cell rows (`| `top_k` / `floor` |`) ARE parsed,
+so every knob it names is still policed. Set-equality there would be permanently
+red, since the table omits many inputs by design.
 
 Deliberately parsed WITHOUT PyYAML, like the cursor-review model
 (test_workflow_inputs_docs.py): this repo is stdlib-only and CI installs no
@@ -43,6 +44,7 @@
 SETUP_GUIDE = os.path.normpath(
     os.path.join(HERE, "..", "..", "..", "docs", "callers", "refresh-reviewers.md")
 )
+README = os.path.normpath(os.path.join(HERE, "..", "README.md"))
 
 # An input declaration: the key alone on its 6-space line, directly under
 # `    inputs:`. Sub-keys of an input (description/type/default) are 8-space,
@@ -51,6 +53,15 @@
 # A table row's first cell: `| `name` | ...`.
 TABLE_KEY = re.compile(r"^\|\s*`([A-Za-z0-9_-]+)`\s*\|")
 HEADING = re.compile(r"^#{2,}\s")
+# An input's `default:` / `required:` sub-keys — 8-space, one level under the
+# 6-space input key — used to pin the guide's Default column to the real value.
+INPUT_DEFAULT = re.compile(r"^        default:\s*(.*?)\s*$")
+INPUT_REQUIRED = re.compile(r"^        required:\s*(\S+)\s*$")
+# A `with:` mapping in an example caller (at any indent), and a mapping key
+# directly under it. A placeholder scalar VALUE (`<same-sha>`, a login) never
+# starts a line, so MAPPING_KEY never mistakes one for an input.
+WITH_LINE = re.compile(r"^(\s*)with:\s*$")
+MAPPING_KEY = re.compile(r"^\s*([A-Za-z0-9_-]+):")
 
 
 def read_lines(path):
@@ -61,6 +72,32 @@ def read_lines(path):
         return [line.rstrip("\r") for line in f.read().split("\n")]
 
 
+def section_lines(lines, heading):
+    """Lines strictly under `heading` (a `## …` line), up to the next heading at
+    the same or a higher level. Lets a scan be scoped to one section instead of
+    the whole file, so an unrelated block elsewhere can't stand in for it."""
+    out, in_section = [], False
+    for line in lines:
+        if line.strip() == heading:
+            in_section = True
+            continue
+        if in_section and HEADING.match(line):
+            break
+        if in_section:
+            out.append(line)
+    return out
+
+
+def split_cells(line):
+    """Split a markdown table row into trimmed cells, honoring GFM's escaped
+    `\\|` (a literal pipe inside a cell) so a Default value that contains a pipe
+    — plausible for a regex-valued input — doesn't shift every later column and
+    make the Default comparison run against the wrong cell."""
+    body = line.strip().strip("|")
+    cells = re.split(r"(?<!\\)\|", body)
+    return [cell.strip().replace("\\|", "|") for cell in cells]
+
+
 def workflow_inputs():
     """Input names declared under on.workflow_call.inputs."""
     lines = read_lines(WORKFLOW)
@@ -107,6 +144,264 @@ def documented_inputs(path, heading):
     return names
 
 
+def documented_knob_names(path, heading):
+    """Every backticked knob named in the FIRST cell of each table row under
+    `heading`, INCLUDING combined-cell rows like `| `top_k` / `floor` |` that
+    the lone-name `TABLE_KEY` regex skips. A cell counts only when every
+    `/`-separated part is itself a lone backticked name, so the header, the
+    `---` separator, and prose rows contribute nothing. Used for the README
+    phantom-knob direction, where combined cells would otherwise let
+    `top_k`/`floor`/`min_touches`/`min_score` drift unnoticed."""
+    names, in_section = set(), False
+    for line in read_lines(path):
+        if line.strip() == heading:
+            in_section = True
+            continue
+        if in_section and HEADING.match(line):
+            break
+        if not in_section or not line.lstrip().startswith("|"):
+            continue
+        cells = split_cells(line)
+        if not cells or not cells[0]:
+            continue
+        parts = [part.strip() for part in cells[0].split("/")]
+        matched = [re.fullmatch(r"`([A-Za-z0-9_-]+)`", part) for part in parts]
+        if all(matched):
+            names.update(match.group(1) for match in matched)
+    return names
+
+
+def strip_comment_prefix(line):
+    """Drop the leading `# ` from a full-line YAML comment while preserving the
+    example's own indentation, so relative-indent parsing still works. A bare
+    `#` becomes empty."""
+    if line.startswith("# "):
+        return line[2:]
+    if line == "#":
+        return ""
+    return line
+
+
+def fenced_blocks(lines):
+    """Content lines of every ``` fenced code block, one list per block."""
+    blocks, current, inside = [], [], False
+    for line in lines:
+        if line.lstrip().startswith("```"):
+            if inside:
+                blocks.append(current)
+                current = []
+            inside = not inside
+            continue
+        if inside:
+            current.append(line)
+    return blocks
+
+
+def with_keys(lines):
+    """Mapping keys directly under each `with:` in `lines`.
+
+    Relative-indentation only, no YAML parser: the first non-blank line after a
+    `with:` fixes the child indent, and keys at exactly that indent are
+    collected until the block dedents back to (or past) the `with:` line. So
+    `uses:` / `secrets:`, which sit at the `with:` indent, end the block rather
+    than count as inputs.
+    """
+    keys = set()
+    i, n = 0, len(lines)
+    while i < n:
+        opener = WITH_LINE.match(lines[i])
+        if not opener:
+            i += 1
+            continue
+        base = len(opener.group(1))
+        child = None
+        j = i + 1
+        while j < n:
+            line = lines[j]
+            if not line.strip() or line.lstrip().startswith("#"):
+                j += 1
+                continue
+            indent = len(line) - len(line.lstrip())
+            if indent <= base:  # dedent to a sibling (secrets:, next job key)
+                break
+            if child is None:
+                child = indent
+            if indent == child:
+                key = MAPPING_KEY.match(line)
+                if key:
+                    keys.add(key.group(1))
+            j += 1
+        i = j
+    return keys
+
+
+def example_with_keys():
+    """`with:` keys from the two example callers this repo ships: the fenced
+    YAML under the guide's ## Caller heading, and the `# `-prefixed example in
+    the workflow header comment. Returns {source_label: set_of_keys}.
+
+    Both sources are scoped the way their label claims, and each fenced block is
+    scanned on its own:
+
+    * Guide side — ONLY the fences under `## Caller`, not every fence in the
+      file, so the anti-vacuity `workflows_ref` guard can't be satisfied by some
+      unrelated snippet while the real Caller example silently loses its `with:`,
+      and so a stray step-level `with:` in another section (e.g. an
+      `actions/checkout`) can't register here as a phantom input.
+    * Workflow side — ONLY the header comment above `jobs:`, bounded exactly the
+      way `workflow_inputs` bounds its scan, not every column-0 `#` line in the
+      file.
+
+    Scanning per block (rather than one flattened list) keeps a `with:` that
+    ends one block from absorbing the next block's more-indented lines.
+    """
+    guide_keys = set()
+    for block in fenced_blocks(section_lines(read_lines(SETUP_GUIDE), "## Caller")):
+        guide_keys |= with_keys(block)
+
+    workflow_lines = read_lines(WORKFLOW)
+    head = (
+        workflow_lines[: workflow_lines.index("jobs:")]
+        if "jobs:" in workflow_lines
+        else workflow_lines
+    )
+    header_comment = [
+        strip_comment_prefix(line) for line in head if line.startswith("#")
+    ]
+    return {
+        "docs/callers/refresh-reviewers.md ## Caller": guide_keys,
+        "refresh-reviewers.yml header comment": with_keys(header_comment),
+    }
+
+
+def workflow_input_defaults():
+    """(`{name: raw default:}`, `{names marked required: true}`) from the
+    workflow. Required inputs carry no default (`workflows_ref`)."""
+    lines = read_lines(WORKFLOW)
+    if "jobs:" not in lines:
+        raise AssertionError(
+            f"no top-level `jobs:` line in {WORKFLOW} — file moved or its "
+            "structure changed; the input scan cannot be bounded"
+        )
+    head = lines[: lines.index("jobs:")]
+    defaults, required, current, in_inputs = {}, set(), None, False
+    for line in head:
+        if line == "    inputs:":
+            in_inputs = True
+            continue
+        if not in_inputs:
+            continue
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        if re.match(r"^    \S", line):  # dedent out of inputs: (secrets:, etc.)
+            break
+        key = INPUT_KEY.match(line)
+        if key:
+            current = key.group(1)
+            continue
+        if current is None:
+            continue
+        default = INPUT_DEFAULT.match(line)
+        if default:
+            defaults[current] = default.group(1)
+            continue
+        req = INPUT_REQUIRED.match(line)
+        if req and req.group(1) == "true":
+            required.add(current)
+    return defaults, required
+
+
+def documented_input_defaults(path, heading):
+    """`{input key: raw Default-column cell}` from the table under `heading`."""
+    result, in_section = {}, False
+    for line in read_lines(path):
+        if line.strip() == heading:
+            in_section = True
+            continue
+        if in_section and HEADING.match(line):
+            break
+        if in_section and line.lstrip().startswith("|"):
+            cells = split_cells(line)
+            if len(cells) < 2:
+                continue
+            key = re.fullmatch(r"`([A-Za-z0-9_-]+)`", cells[0])
+            if key:
+                name = key.group(1)
+                # A second row for the same input would silently overwrite the
+                # first, so two contradictory Default cells would pass as long as
+                # the last one is right. Surface it — that's exactly the drift
+                # this file exists to catch.
+                if name in result:
+                    raise AssertionError(
+                        f"`{name}` appears twice in the `{heading}` table of "
+                        f"{path} — a duplicate row hides a contradictory Default "
+                        "cell from this comparison"
+                    )
+                result[name] = cells[1]
+    return result
+
+
+# Canonical form for the required-with-no-default input, shared by both sides
+# of the Default-column comparison so `workflows_ref`'s `— (**required**)` cell
+# and the workflow's `required: true` compare equal.
+_REQUIRED = "\x00required-no-default"
+
+
+def _clean_workflow_default(raw):
+    """Canonicalize a raw `default:` value so cosmetic YAML — a trailing inline
+    comment, surrounding quotes — doesn't turn this suite red against correct
+    docs. Backticks are stripped from the guide side, so the two sides would
+    otherwise compare a value against its raw YAML source."""
+    text = raw.strip()
+    # A quoted scalar ends at its closing quote; anything after that (including
+    # a ` #` that would otherwise look like a comment marker) is a trailing
+    # inline comment, not part of the value. Keep the `''` spelling both the
+    # guide and this file use for the empty string.
+    if text[:1] in "\"'":
+        quote = text[0]
+        end = 1
+        while end < len(text):
+            if quote == '"' and text[end] == "\\":
+                end += 2
+                continue
+            if quote == "'" and text[end : end + 2] == "''":
+                end += 2
+                continue
+            if text[end] == quote:
+                inner = text[1:end]
+                return inner if inner else quote * 2
+            end += 1
+    # An unquoted inline comment (` # …`) is not part of the value.
+    hash_at = text.find(" #")
+    if hash_at != -1:
+        text = text[:hash_at].rstrip()
+    return text
+
+
+def canonical_guide_default(cell):
+    text = cell.strip()
+    # Anchor on the required-cell SHAPE (`— (**required**)`), not a loose
+    # `**required**` substring: a cell like `` `main` (**required**) `` advertises
+    # a default the workflow deliberately lacks and must NOT canonicalize to
+    # _REQUIRED (that drift is the whole point of this check), while a real
+    # default annotated in prose must not false-match either.
+    if text.startswith("—") and "**required**" in text:
+        return _REQUIRED
+    return text.strip("`").strip()
+
+
+def canonical_workflow_default(name, defaults, required):
+    if name in defaults:
+        return _clean_workflow_default(defaults[name])
+    if name in required:
+        return _REQUIRED
+    # Optional with no `default:` — a legal `workflow_call` shape that arrives at
+    # runtime as `''`. Canonicalize to the empty string it actually delivers
+    # rather than to None (which the guide side can never produce, permanently
+    # reddening the subTest).
+    return ""
+
+
 class RefreshReviewersInputsDocsTest(unittest.TestCase):
     def setUp(self):
         self.declared = workflow_inputs()
@@ -143,6 +438,99 @@ def test_every_declared_input_is_documented(self):
             f"`docs/callers/refresh-reviewers.md` inputs table: {sorted(missing)}",
         )
 
+    def test_example_with_blocks_are_declared_inputs(self):
+        # The two copy-paste callers (guide ## Caller fence, workflow header
+        # comment) pass inputs via `with:`. A phantom key there is a zero-job
+        # startup_failure for whoever copies it — the #31 failure, one level in
+        # from the Inputs table the two methods above already police. Subset,
+        # not equality: an example legitimately shows only a couple of inputs.
+        for label, keys in example_with_keys().items():
+            # Guard: each example genuinely names inputs incl. workflows_ref, so
+            # a scanner gone quiet fails loudly instead of asserting {} ⊆ {}.
+            self.assertIn(
+                "workflows_ref",
+                keys,
+                f"the {label} `with:` scanner found no workflows_ref — the "
+                "example block moved or the parser broke; this subset check is "
+                "now vacuous",
+            )
+            undeclared = keys - self.declared
+            self.assertFalse(
+                undeclared,
+                f"the {label} example passes `with:` inputs refresh-reviewers."
+                f"yml does not declare: {sorted(undeclared)} — a phantom input "
+                "there is a zero-job startup_failure for whoever copies it",
+            )
+
+    def test_readme_knob_table_has_no_phantom_knob(self):
+        # `.github/refresh-reviewers/README.md`'s "Knob defaults (and why)"
+        # table is intentionally partial, so assert ONLY the phantom direction —
+        # a knob named there but not declared. Set-equality would be permanently
+        # red (the table omits many inputs by design). Combined-cell rows
+        # (`| `top_k` / `floor` |`) ARE parsed here: skipping them would leave
+        # top_k/floor/min_touches/min_score free to drift to a stale name with
+        # this test still green.
+        documented = documented_knob_names(README, "## Knob defaults (and why)")
+        # Guard: a heading rename would empty this and make the check vacuous.
+        self.assertTrue(
+            documented,
+            "the README `## Knob defaults (and why)` scanner found no knob rows "
+            "— the heading was renamed or the table reshaped",
+        )
+        phantom = documented - self.declared
+        self.assertFalse(
+            phantom,
+            "`.github/refresh-reviewers/README.md` Knob defaults table names "
+            f"knobs refresh-reviewers.yml does not declare: {sorted(phantom)}",
+        )
+
+    def test_guide_default_column_matches_workflow(self):
+        # Both assertions above are name-only, so the guide's Default column can
+        # silently drift from the workflow's real `default:`. Pin it.
+        defaults, required = workflow_input_defaults()
+        guide = documented_input_defaults(SETUP_GUIDE, "## Inputs")
+        # Guard both scanners: the workflow side must have parsed real defaults
+        # and the required-only workflows_ref; the guide side must show its cell.
+        self.assertTrue(
+            defaults,
+            "workflow_input_defaults found no `default:` lines — parser or file "
+            "structure changed; the Default-column check is now vacuous",
+        )
+        self.assertIn(
+            "workflows_ref",
+            required,
+            "workflow_input_defaults lost the required `workflows_ref` — parser "
+            "or file structure changed; the Default-column check is now vacuous",
+        )
+        self.assertIn(
+            "workflows_ref",
+            guide,
+            "the guide Inputs table Default scanner lost `workflows_ref` — "
+            "parser or table shape changed; this check is now vacuous",
+        )
+        for name in sorted(self.declared):
+            with self.subTest(input=name):
+                self.assertIn(
+                    name,
+                    guide,
+                    f"`{name}` is declared but absent from the guide Inputs "
+                    "table Default column",
+                )
+                want = canonical_workflow_default(name, defaults, required)
+                got = canonical_guide_default(guide[name])
+                if name in required:
+                    have = "required: true (no default)"
+                elif name in defaults:
+                    have = f"default: {defaults[name]!r}"
+                else:
+                    have = "no default and not required (arrives as '')"
+                self.assertEqual(
+                    got,
+                    want,
+                    f"guide Default column for `{name}` is {guide[name]!r} but "
+                    f"refresh-reviewers.yml has {have}",
+                )
+
 
 if __name__ == "__main__":
     unittest.main(verbosity=2)