diff --git a/MANIFEST.in b/MANIFEST.in
index d78ba0416..959c8f9ca 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -9,5 +9,7 @@ recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif
 
 recursive-include shiny/www *
 recursive-include shiny/experimental/www *
-recursive-include shiny/api-examples *
 recursive-include shiny/templates *
+
+prune shiny/api-examples
+prune shiny/experimental/api-examples
diff --git a/pyproject.toml b/pyproject.toml
index 8115cfa1a..b2a380e11 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -3,7 +3,13 @@ requires = ["setuptools>=60", "wheel", "setuptools_scm>=8.0"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
-packages = { find = { include = ["shiny", "shiny.*"] } }
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["shiny*"]
+namespaces = false
+
+[tool.setuptools.exclude-package-data]
+"*" = ["api-examples/**"]
 
 [tool.setuptools_scm]
 write_to = "shiny/_version.py"
diff --git a/shiny/_docstring.py b/shiny/_docstring.py
index 93f7fd747..d012b0d69 100644
--- a/shiny/_docstring.py
+++ b/shiny/_docstring.py
@@ -8,6 +8,7 @@
 
 def find_api_examples_dir(start_dir: str) -> Optional[str]:
     current_dir = os.path.abspath(start_dir)
+    search_start = current_dir
     while True:
         api_examples_dir = os.path.join(current_dir, "api-examples")
         if os.path.isdir(api_examples_dir):
@@ -19,6 +20,15 @@ def find_api_examples_dir(start_dir: str) -> Optional[str]:
         if current_dir == os.path.dirname(current_dir):
             break  # Reached the global root directory
         current_dir = os.path.dirname(current_dir)
+
+    # Not found - provide helpful error for documentation builders
+    if os.getenv("SHINY_ADD_EXAMPLES") == "true":
+        raise FileNotFoundError(
+            "Could not find 'api-examples/' directory. "
+            "Documentation must be built from the source repository, "
+            "not from an installed package. "
+            f"Searched from: {search_start}"
+        )
     return None