diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/tests/__init__.py
@@ -0,0 +1 @@
+
diff --git a/tests/fixtures.py b/tests/fixtures.py
new file mode 100644
index 0000000..e922c5d
--- /dev/null
+++ b/tests/fixtures.py
@@ -0,0 +1,41 @@
+from pathlib import Path
+
+
+def write_readme_only_repo(root: Path) -> Path:
+    repo = root / "readme-only"
+    repo.mkdir()
+    (repo / "README.md").write_text(
+        "# Readme Only\n\nThis repository describes a planned interface.\n",
+        encoding="utf-8",
+    )
+    return repo
+
+
+def write_python_cli_repo(root: Path) -> Path:
+    repo = root / "python-cli"
+    repo.mkdir()
+    (repo / "README.md").write_text("# Python CLI\n", encoding="utf-8")
+    (repo / "requirements.txt").write_text("click\npytest\n", encoding="utf-8")
+    (repo / "cli.py").write_text(
+        "import click\n\n"
+        "@click.command()\n"
+        "def main():\n"
+        "    click.echo('ok')\n",
+        encoding="utf-8",
+    )
+    (repo / "tests").mkdir()
+    (repo / "tests" / "test_cli.py").write_text(
+        "def test_cli(): pass\n",
+        encoding="utf-8",
+    )
+    return repo
+
+
+def write_misleading_docs_repo(root: Path) -> Path:
+    repo = root / "misleading-docs"
+    repo.mkdir()
+    (repo / "README.md").write_text(
+        "# Misleading Docs\n\nClaims to provide payments and search, but has no code.\n",
+        encoding="utf-8",
+    )
+    return repo
diff --git a/tests/test_repository_scanner.py b/tests/test_repository_scanner.py
index 615a7d6..02837a6 100644
--- a/tests/test_repository_scanner.py
+++ b/tests/test_repository_scanner.py
@@ -1,4 +1,9 @@
 from repo_registry.repo_scanning.scanner import DeterministicScanner
+from tests.fixtures import (
+    write_misleading_docs_repo,
+    write_python_cli_repo,
+    write_readme_only_repo,
+)
 
 
 def test_deterministic_scanner_extracts_structural_facts(tmp_path):
@@ -34,3 +39,35 @@ def test_deterministic_scanner_extracts_structural_facts(tmp_path):
 
     languages = {fact.name: fact.metadata["file_count"] for fact in result.facts if fact.kind == "language"}
     assert languages == {"Python": 2}
+
+
+def test_scanner_readme_only_fixture_records_docs_without_interfaces(tmp_path):
+    repo = write_readme_only_repo(tmp_path)
+
+    result = DeterministicScanner().scan(repo)
+
+    facts = {(fact.kind, fact.name, fact.path) for fact in result.facts}
+    assert ("documentation", "README", "README.md") in facts
+    assert {fact.kind for fact in result.facts} == {"documentation"}
+
+
+def test_scanner_python_cli_fixture_records_cli_and_framework_hints(tmp_path):
+    repo = write_python_cli_repo(tmp_path)
+
+    result = DeterministicScanner().scan(repo)
+
+    facts = {(fact.kind, fact.name, fact.path) for fact in result.facts}
+    assert ("framework", "Click", "requirements.txt") in facts
+    assert ("framework", "pytest", "requirements.txt") in facts
+    assert ("interface", "python CLI command decorator", "cli.py") in facts
+    assert ("test", "test_cli.py", "tests/test_cli.py") in facts
+
+
+def test_scanner_misleading_docs_fixture_stays_observational(tmp_path):
+    repo = write_misleading_docs_repo(tmp_path)
+
+    result = DeterministicScanner().scan(repo)
+
+    assert [(fact.kind, fact.name, fact.path) for fact in result.facts] == [
+        ("documentation", "README", "README.md")
+    ]