diff --git a/docs/internal/adapters.md b/docs/internal/adapters.md
index 9089a9b..1d805b6 100644
--- a/docs/internal/adapters.md
+++ b/docs/internal/adapters.md
@@ -11,6 +11,7 @@ This document describes implemented adapter/repository boundaries and their curr
 - root package `scriptorium`: public Go library facade for preparing and running prompt requests.
 - `internal/promptdef`: filesystem and `fs.FS` prompt-definition repositories.
 - `internal/profile`: filesystem, `fs.FS`, and overlay execution-profile repositories.
+- `internal/filecatalog`: shared YAML discovery and display-path helpers for prompt/profile repositories.
 - `internal/profile/builtin`: embedded built-in execution-profile repository.
 - `internal/artifact`: input artifact reader.
 - `internal/prompt`: Go-template renderer.
@@ -45,6 +46,7 @@ Prompt/profile repositories:
 
 - Input: prompt/profile YAML files under configured directories or `fs.FS` roots.
 - Output: normalized domain definitions/profiles or typed errors.
+- Shared YAML catalog helpers provide recursive discovery, extension filtering, deterministic ordering, file stems, and `fs.FS` display paths.
 - Single-file public sources are represented as `fs.FS` roots containing one YAML file; lookup still uses YAML `id` values.
 
 Profile repository composition:
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 31b1bb8..092be81 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -146,26 +146,33 @@ Symptom:
 
 - CLI run/render error reading input artifacts.
 - HTTP `400 artifact_read_failed`.
+- HTTP `400 artifact_not_allowed`.
 
 Likely cause:
 
 - File path in input mapping does not exist or is unreadable.
 - Unsupported artifact reference type in HTTP request.
+- HTTP `file` input references are disabled because no artifact root is configured.
+- HTTP `file` input path escapes the configured artifact root.
 
 Diagnostic step:
 
 - Verify every mapped file path exists and is readable by the process.
 - For HTTP, verify each input uses supported `type` values.
+- For HTTP `file` inputs, verify `server.artifact_root` or `serve --artifact-root` is configured and the requested path stays inside that root.
 
 Safe fix:
 
 - Correct file paths and permissions.
 - Use supported input types (`file`, `inline`).
+- Configure a narrow HTTP artifact root when HTTP file inputs are required.
+- Use relative paths under the artifact root, or switch to `inline` inputs.
 
 Relevant links:
 
 - [CLI reference](cli.md)
 - [Configuration reference](config.md)
+- [HTTP API integration](integrations/http-api.md)
 
 ## Prompt Template Render Failures