Add built-in profile repository wiring

docs/cli.md

@@ -29,8 +29,9 @@ Integration references:
 - `run` and `render` require:
   - `--prompt`
   - at least one `--input`
-  - an effective `prompt_dir` and `profile_dir` (from flags or config)
-- `serve` requires an effective `prompt_dir` and `profile_dir` (from flags or config).
+  - an effective `prompt_dir` from flags or config
+- `serve` requires an effective `prompt_dir` from flags or config.
+- `profile_dir` is optional. If omitted, only built-in profiles are available; if provided, custom profiles override built-ins with the same ID.
 - Positional arguments are rejected.
 - Prompt cache control is configured in prompt YAML (`messages[].cache_control`), not with CLI flags.
 - Provider-specific `reasoning_effort` and `extra_params` are configured in profile YAML or HTTP model overrides, not with CLI flags.
@@ -41,7 +42,7 @@ Integration references:
 
 - `--config <path>`: app config file path.
 - `--prompt-dir <dir>`: prompt definition directory.
-- `--profile-dir <dir>`: profile definition directory.
+- `--profile-dir <dir>`: custom profile definition directory.
 - `--schema-dir <dir>`: schema base directory for `json_schema` validation.
 - `--prompt <id>`: prompt ID to execute. Required.
 - `--prompt-id <id>`: deprecated alias for `--prompt`.
@@ -79,7 +80,7 @@ Notes:
 - `--config <path>`: app config file path.
 - `--addr <listen-address>`: HTTP listen address.
 - `--prompt-dir <dir>`: prompt definition directory.
-- `--profile-dir <dir>`: profile definition directory.
+- `--profile-dir <dir>`: custom profile definition directory.
 - `--schema-dir <dir>`: schema base directory for `json_schema` validation.
 
 Notes:

docs/config.md

@@ -21,10 +21,9 @@ When `--config <path>` is provided, that file is required.
 
 ```yaml
 prompt_dir: ./examples/prompts
-profile_dir: ./examples/profiles
 ```
 
-This is enough to use `run` and `render` when prompt/profile files are valid.
+This is enough to use `run` and `render` when prompts select built-in profiles.
 
 ## Production-Oriented App Config
 
@@ -45,7 +44,7 @@ defaults:
 Top-level fields:
 
 - `prompt_dir` (optional): default prompt definition directory.
-- `profile_dir` (optional): default profile definition directory.
+- `profile_dir` (optional): default custom profile definition directory.
 - `schema_dir` (optional): base directory for schema files used by `json_schema` validation.
 - `server.addr` (optional): default listen address for `serve`.
 - `defaults.render_format` (optional): default `render` output format (`text` or `json`).
@@ -173,7 +172,7 @@ Repair behavior boundary:
 
 ## Profile Definition Files
 
-Execution profiles are YAML files anywhere under `profile_dir`, including nested subdirectories.
+Scriptorium includes built-in execution profiles. Custom execution profiles are YAML files anywhere under `profile_dir`, including nested subdirectories.
 
 Subdirectories are organizational only. Callers still select profiles by the YAML `id`, not by file path. For example, `profiles/local/local-quality.yaml` may still declare `id: local-quality`, and callers use `--profile local-quality`.
 
@@ -212,6 +211,9 @@ Field reference:
 
 Profile rules:
 
+- `profile_dir` is optional. If omitted, only built-in profiles are available.
+- If `profile_dir` is set, custom profiles from that directory override built-in profiles with the same `id`.
+- Duplicate IDs within the custom profile directory are invalid. Matching IDs across custom and built-in profiles are valid override behavior.
 - Profile decoding is strict; unknown YAML fields are rejected.
 - Raw `api_key` is rejected; use `api_key_env`.
 - If `api_key_env` is set, that environment variable must be set when preparing/running.
@@ -250,7 +252,7 @@ Supported artifact reference types for request inputs are `file` and `inline`.
 
 - App config: `examples/config.yml`
 - Prompt examples: `examples/prompts/`
-- Profile examples: `examples/profiles/`
+- Custom profile examples: `examples/profiles/`
 - Schema examples: `examples/schemas/`
 - Input fixtures: `examples/fixtures/`
 - Render example script: `examples/render-markdown-summary.sh`

docs/consumers/pkg-scriptorium.md

@@ -21,7 +21,7 @@ if err != nil {
 }
 ```
 
-`PromptDir` and `ProfileDir` are required. `SchemaDir` defaults to the built-in schema directory. `Timeout` and `HTTPClient` configure the default OpenAI-compatible client used by `Run` when no custom LLM client is supplied.
+`PromptDir` is required. `ProfileDir` is optional; omit it to use built-in profiles only, or set it to overlay custom profiles above built-ins. `SchemaDir` defaults to the built-in schema directory. `Timeout` and `HTTPClient` configure the default OpenAI-compatible client used by `Run` when no custom LLM client is supplied.
 
 ## Prepare A Prompt
 

docs/internal/adapters.md

@@ -10,7 +10,8 @@ This document describes implemented adapter/repository boundaries and their curr
 - `internal/adapter/http`: HTTP request/response mapping for `POST /v1/runs`.
 - root package `scriptorium`: public Go library facade for preparing and running prompt requests.
 - `internal/promptdef`: filesystem prompt-definition repository.
-- `internal/profile`: filesystem execution-profile repository.
+- `internal/profile`: filesystem, `fs.FS`, and overlay execution-profile repositories.
+- `internal/profile/builtin`: embedded built-in execution-profile repository.
 - `internal/artifact`: input artifact reader.
 - `internal/prompt`: Go-template renderer.
 - `internal/llm`: OpenAI-compatible LLM client implementation.
@@ -43,6 +44,13 @@ Filesystem repositories:
 - Input: prompt/profile YAML files under configured directories.
 - Output: normalized domain definitions/profiles or typed errors.
 
+Profile repository composition:
+
+- Built-in profiles are embedded and loaded through the same profile validation rules as filesystem profiles.
+- When no custom profile directory is configured, the runner receives the built-in profile repository.
+- When a custom profile directory is configured, the runner receives an overlay repository with custom profiles as primary and built-ins as fallback.
+- Overlay lookup falls back only after custom profile-not-found errors; custom load/validation/raw-key errors are returned directly.
+
 Artifact reader:
 
 - Input: `domain.ArtifactRef`.
@@ -69,7 +77,7 @@ Validator:
 Primary app settings consumed by adapters:
 
 - `prompt_dir`
-- `profile_dir`
+- `profile_dir` (optional custom profile source)
 - `schema_dir`
 - `server.addr`
 - `defaults.render_format`
@@ -94,6 +102,7 @@ Strict decoding and input checks:
 - prompt/profile repositories scan nested subdirectories recursively.
 - prompt/profile lookup uses YAML `id` values; subdirectory paths are organizational only.
 - duplicate prompt/profile IDs are invalid and fail instead of using first-match behavior.
+- duplicate profile IDs across custom and built-in sources are allowed; the custom source overrides the built-in profile.
 - HTTP DTO decoder rejects unknown JSON fields.
 - raw API key payload fields are rejected by strict decoding in profile/http paths.
 

docs/troubleshooting.md

@@ -33,23 +33,23 @@ Relevant links:
 - [Configuration reference](config.md)
 - [CLI reference](cli.md)
 
-## Missing Prompt/Profile Directory Settings
+## Missing Prompt Directory Settings
 
 Symptom:
 
-- CLI parse errors saying prompt directory or profile directory is required.
+- CLI parse errors saying prompt directory is required.
 
 Likely cause:
 
-- Neither CLI flags nor config provide effective `prompt_dir` / `profile_dir`.
+- Neither CLI flags nor config provide an effective `prompt_dir`.
 
 Diagnostic step:
 
-- Run the failing command with explicit `--prompt-dir` and `--profile-dir` once to verify.
+- Run the failing command with explicit `--prompt-dir` once to verify.
 
 Safe fix:
 
-- Set `prompt_dir` and `profile_dir` in config, or always pass both flags.
+- Set `prompt_dir` in config, or always pass `--prompt-dir`.
 
 Relevant links: