Establish canonical developer documentation structure

docs/internal/adapters.md

@@ -145,6 +145,37 @@ Adapters do not add durable run state.
 - `internal/format/prepared_run_test.go`
 - `internal/llm/openai_compatible_client_test.go`
 
+## Change Recipes
+
+### Application Configuration Fields
+
+1. Add the field to the relevant `internal/config` shape and default handling.
+2. Parse and validate it, then preserve configuration and CLI-override
+   precedence while wiring it through its consuming adapter.
+3. Add focused configuration and adapter tests for parsing, mapping, and
+   effective behavior.
+4. Update the [configuration contract](../config.md) and any external contract
+   affected by the new behavior.
+
+### CLI Flags
+
+1. Add the flag to the relevant command in `internal/adapter/cli/run.go`.
+2. Keep command scope and application-configuration precedence intentional.
+3. Add or update parser and command tests in
+   `internal/adapter/cli/run_test.go`.
+4. Update the [CLI contract](../cli.md) and any maintained examples affected by
+   the invocation.
+
+### Adapter Capabilities
+
+1. Define or reuse the appropriate domain or use-case interface boundary.
+2. Implement translation and IO behavior in the adapter without moving
+   use-case decisions out of `internal/usecase`.
+3. Add focused mapping, parsing, and error-behavior tests.
+4. Update this document and the affected canonical public or integration
+   contract. Update [source internals](sources.md) when source-loading behavior
+   changes.
+
 ## Architectural Invariants
 
 - Adapter packages stay thin and translation-focused.

docs/internal/overview.md

@@ -0,0 +1,48 @@
+# Internal Component Overview
+
+## Purpose
+
+This is the inventory of Scriptorium's implemented components for contributors.
+The [architecture policy](../policy/architecture.md) owns normative boundaries
+and invariants; public behavior belongs in the linked contracts.
+
+## Public And Command Entrypoints
+
+| Component | Implemented responsibility | References |
+| --- | --- | --- |
+| Root package `scriptorium` | Public Go facade that constructs the engine, exposes request/result types and options, and maps internal errors. | [Go package contract](../consumers/pkg-scriptorium.md), [adapter internals](adapters.md) |
+| `cmd/scriptorium` | Process entrypoint that delegates command execution to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
+
+## Adapters, Domain, And Use Case
+
+| Component | Implemented responsibility | References |
+| --- | --- | --- |
+| `internal/adapter/cli` | Parses CLI commands, applies application wiring, and handles process input and output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
+| `internal/adapter/http` | Maps HTTP requests and responses to domain operations and maps public errors. | [HTTP API contract](../api.md), [adapter internals](adapters.md) |
+| `internal/domain` | Defines core request, result, output-contract, and LLM-boundary types. | [runner internals](runner.md) |
+| `internal/usecase` | Implements `Runner` preparation, execution, validation coordination, and the repairer boundary. | [runner internals](runner.md) |
+
+## Configuration And Sources
+
+| Component | Implemented responsibility | References |
+| --- | --- | --- |
+| `internal/config` | Loads application settings, applies defaults, and applies CLI overrides. | [configuration contract](../config.md), [adapter internals](adapters.md) |
+| `internal/defaults` | Holds compile-time default values used when application settings are resolved. | [configuration contract](../config.md) |
+| `internal/promptdef` | Loads prompt definitions from filesystem and `fs.FS` sources. | [configuration contract](../config.md), [source internals](sources.md) |
+| `internal/profile` | Loads filesystem and `fs.FS` execution profiles and combines profile repositories. | [configuration contract](../config.md), [source internals](sources.md) |
+| `internal/profile/builtin` | Provides embedded built-in execution profiles as a repository. | [configuration contract](../config.md), [source internals](sources.md) |
+| `internal/filecatalog` | Provides shared YAML discovery and source-root helpers. | [source internals](sources.md) |
+| `internal/artifact` | Reads inline and file-backed input artifacts. | [configuration contract](../config.md), [HTTP API contract](../api.md), [source internals](sources.md) |
+| `internal/prompt` | Renders prompt templates into messages. | [runner internals](runner.md) |
+
+## Formatting, Validation, And Model Access
+
+| Component | Implemented responsibility | References |
+| --- | --- | --- |
+| `internal/format` | Formats prepared-run information for CLI output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
+| `internal/validate` | Defines validation interfaces and provides standard filesystem and `fs.FS` schema validation. | [configuration contract](../config.md), [source internals](sources.md), [runner internals](runner.md) |
+| `internal/llm` | Defines the provider-neutral LLM client boundary and its OpenAI-compatible implementation. | [OpenAI-compatible integration](../integrations/openai-compatible-chat.md), [runner internals](runner.md) |
+
+Focused internal documents describe the components that have detailed
+orchestration, adapter, or source behavior. Package tests live alongside the
+implementation and are identified in those focused documents where relevant.

docs/internal/sources.md

@@ -147,6 +147,18 @@ Source packages do not persist run state.
 - `internal/usecase/integration_test.go`
 - `engine_test.go`
 
+## Change Recipe
+
+When updating prompt, profile, schema, or built-in-profile assets:
+
+1. Keep files valid for their strict loader and source boundary.
+2. Keep maintained examples and fixtures secret-free.
+3. Run focused prompt, profile, schema, or validation tests for the changed
+   source.
+4. Update the [configuration contract](../config.md) and every affected
+   external contract; update this document when loading or precedence mechanics
+   change.
+
 ## Architectural Invariants
 
 - Prompt/profile identity comes from YAML `id`.