diff --git a/api/README.md b/api/README.md
index cfb0ed3d10d99c..8fae30c7ac38ac 100644
--- a/api/README.md
+++ b/api/README.md
@@ -86,7 +86,7 @@ The [API schema guide](controllers/API_SCHEMA_GUIDE.md) owns schema changes and
 pnpm -C packages/contracts gen-api-contract
 ```
 
-Refresh the checked-in Markdown reference with:
+The checked-in Markdown reference lives in `api/openapi/markdown`. The generator's default output directories are anchored to `api/`, regardless of the working directory. Refresh it with:
 
 ```bash
 uv run --project api python api/dev/generate_swagger_markdown_docs.py \
diff --git a/api/dev/generate_swagger_markdown_docs.py b/api/dev/generate_swagger_markdown_docs.py
index 519a0067095d33..1c627a3216b760 100644
--- a/api/dev/generate_swagger_markdown_docs.py
+++ b/api/dev/generate_swagger_markdown_docs.py
@@ -410,14 +410,14 @@ def parse_args() -> argparse.Namespace:
         "--openapi-dir",
         dest="openapi_dir",
         type=Path,
-        default=Path("openapi"),
-        help="Directory where intermediate JSON spec files will be written.",
+        default=API_ROOT / "openapi",
+        help="Directory where intermediate JSON spec files will be written (default: api/openapi).",
     )
     parser.add_argument(
         "--markdown-dir",
         type=Path,
-        default=Path("openapi/markdown"),
-        help="Directory where split Markdown API docs will be written.",
+        default=API_ROOT / "openapi" / "markdown",
+        help="Directory where split Markdown API docs will be written (default: api/openapi/markdown).",
     )
     parser.add_argument(
         "--keep-swagger-json",