diff --git a/init.lua b/init.lua
index 98da418..3617a7f 100644
--- a/init.lua
+++ b/init.lua
@@ -40,4 +40,25 @@ function M.parse_readme_api(markdown_string)
     return { documented = documented }
 end
 
+-- Diffs code-surface vs README-doc.
+-- Compares surface.public (set) vs readme.documented (set).
+-- Returns: { missing_docs = [...], stale_docs = [...] }
+function M.diff_surface(surface, readme)
+    local public_set = {}
+    for _, name in ipairs(surface.public) do public_set[name] = true end
+    local doc_set = {}
+    for _, name in ipairs(readme.documented) do doc_set[name] = true end
+
+    local missing = {}
+    for name in pairs(public_set) do
+        if not doc_set[name] then table.insert(missing, name) end
+    end
+    local stale = {}
+    for name in pairs(doc_set) do
+        if not public_set[name] then table.insert(stale, name) end
+    end
+    table.sort(missing); table.sort(stale)
+    return { missing_docs = missing, stale_docs = stale }
+end
+
 return M