fix(docs): use canonical API Markdown output paths

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 \

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",