docs: update for bounded traversal, includes isolation, and init defaults.md

- api-reference: document defaultsRoot default behavior and includes note
- prompt-format: add note that includes don't inherit folder defaults
- cli.md: add defaults.md to init scaffold listing
- README: mention init scaffolds defaults.md, add includes note

Author: PredictabilityAtScale

README.md

@@ -225,6 +225,9 @@ Define a `defaults.md` file in `prompts/` (and optional subfolders) to provide i
 - Shared `# System instructions` in body
 - Nearest subfolder `defaults.md` overrides parent defaults
 - Prompt-local values always win over defaults
+- Included files (`includes`) are not affected by folder defaults
+
+> `promptopskit init` scaffolds a starter `defaults.md` in the prompts root.
 
 ```text
 prompts/

docs/api-reference.md

@@ -149,7 +149,9 @@ const { asset } = await loadPromptFile('/path/to/prompts/support/reply.md', {
 });
 ```
 
-`options.defaultsRoot` (optional) limits defaults discovery to a specific directory tree.
+`options.defaultsRoot` (optional) limits defaults discovery to a specific directory tree. When omitted, defaults to the prompt file's own directory (only the local `defaults.md` is checked). Pass the prompts root directory to enable full ancestor traversal.
+
+> **Note:** `includes` are resolved with `parsePrompt`, not `loadPromptFile`, so included files do not inherit folder defaults. This prevents double-applying system instructions.
 
 ### `interpolate(template, variables, options?)`
 

docs/cli.md

@@ -22,6 +22,7 @@ Creates:
 
 ```
 prompts/
+├── defaults.md         # Folder-level defaults (metadata + system instructions)
 ├── hello.md            # Sample prompt with variables
 ├── hello.test.yaml     # Test sidecar with sample inputs
 └── shared/

docs/prompt-format.md

@@ -48,6 +48,7 @@ You can define shared defaults for an entire prompt tree by adding a `defaults.m
 - `defaults.md` values apply to all prompts in that folder and subfolders.
 - Subfolders can define their own `defaults.md`; nearest (most local) values win.
 - Only missing prompt values are filled from defaults (explicit prompt values always take precedence).
+- Included files (`includes`) are **not** affected by folder defaults — only the top-level prompt inherits.
 
 Supported default fields: