diff --git a/website/docs/cli/reference/run.md b/website/docs/cli/reference/run.md
index c5552b790..aa4b4a8d6 100644
--- a/website/docs/cli/reference/run.md
+++ b/website/docs/cli/reference/run.md
@@ -42,7 +42,7 @@ Flags that are passed to the `spiced` runtime directly using `--`.
 - `-v`, `--verbose` Enable verbose logging (use `-vv` for more detail)
 - `--very-verbose` Enable very verbose logging
 - `--set-runtime` Override [runtime configuration](../../reference/spicepod/#runtime) with a name/value pair specified as `name=value`. Multiple overrides can be specified by using the flag multiple times.
-- `[PATH]` Positional argument specifying the path to a Spicepod directory or file. Supports local paths and `s3://` remote URLs.
+- `[PATH]` Positional argument specifying the path to a Spicepod directory or file. Supports local paths and `s3://` remote URLs. Directories must contain a `spicepod.yaml` (or `spicepod.yml`); file paths can use any name as long as the file declares `kind: Spicepod` and a recognized `version`.
 
 ### Examples
 
diff --git a/website/docs/cli/reference/spiced.md b/website/docs/cli/reference/spiced.md
index 7d62561f7..7a547aa40 100644
--- a/website/docs/cli/reference/spiced.md
+++ b/website/docs/cli/reference/spiced.md
@@ -17,7 +17,7 @@ Most users invoke `spiced` indirectly via [`spice run`](./run), which installs t
 spiced [flags] [SPICEPOD_PATH]
 ```
 
-If `SPICEPOD_PATH` is omitted, `spiced` uses the current working directory.
+If `SPICEPOD_PATH` is omitted, `spiced` uses the current working directory. When the path resolves to a directory, the runtime loads `spicepod.yaml` (or `spicepod.yml`) from inside it. When the path resolves to a file, any YAML filename is accepted (e.g. `spiced ./configs/my-app.yaml`); the file must declare `kind: Spicepod` and a recognized `version` — otherwise `spiced` exits with an explicit validation error.
 
 ### Runtime flags
 
diff --git a/website/docs/cli/reference/validate.md b/website/docs/cli/reference/validate.md
index bbb130449..7deb8ae6c 100644
--- a/website/docs/cli/reference/validate.md
+++ b/website/docs/cli/reference/validate.md
@@ -14,7 +14,7 @@ Checks YAML syntax and schema, component references, duplicate component names,
 spice validate [path]
 ```
 
-- `path`: Path to a `spicepod.yaml` file or a directory containing one. Defaults to the current directory (`.`).
+- `path`: Path to a Spicepod YAML file or a directory containing one. Defaults to the current directory (`.`). Directories must contain a `spicepod.yaml` (or `spicepod.yml`); file paths accept any name as long as the file declares `kind: Spicepod` and a recognized `version`.
 
 #### Flags
 
diff --git a/website/docs/reference/spicepod/index.md b/website/docs/reference/spicepod/index.md
index d7f3362be..2c1dca2bc 100644
--- a/website/docs/reference/spicepod/index.md
+++ b/website/docs/reference/spicepod/index.md
@@ -10,7 +10,7 @@ tags:
   - manifest
 ---
 
-Spicepod manifests use YAML syntax. They are stored in the root directory of the application and must be named `spicepod.yaml` or `spicepod.yml`.
+Spicepod manifests use YAML syntax. By default they are stored in the root directory of the application and named `spicepod.yaml` or `spicepod.yml` — when the runtime is given a directory path, it looks for one of those two filenames. The runtime also accepts any YAML file path directly (e.g. `spiced ./configs/my-app.yaml`); files passed by path must declare `kind: Spicepod` and a recognized `version` and are otherwise rejected with an explicit error.
 
 :::info[Tip]