Normalize maintained documentation examples

README.md

@@ -22,6 +22,7 @@ go run ./cmd/scriptorium render \
 ```
 
 This command renders the prepared prompt and effective runtime settings without calling an LLM.
+For complete invocation and output behavior, see the [CLI reference](docs/cli.md).
 
 ## Documentation
 
@@ -37,8 +38,8 @@ This command renders the prepared prompt and effective runtime settings without
 
 ## Examples
 
-- `examples/config.yml`
+- [Minimal configuration](examples/config.yml) and [complete configuration](examples/config.full.yml)
-- `examples/config.full.yml`
+- [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/), [schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/)
-- `examples/render-markdown-summary.sh`
+- [Render script](examples/render-markdown-summary.sh)
-- `examples/http-run.json`
+- [HTTP request](examples/http-run.json)
-- `examples/go-library/prepare`
+- [Go library example](examples/go-library/prepare/main.go)

internal/adapter/http/handler_test.go

@@ -36,6 +36,40 @@ func (f *fakeRunner) Run(ctx context.Context, req domain.RunRequest) (*domain.Ru
 	return f.result, nil
 }
 
+func TestMaintainedHTTPRunExampleMatchesRequestContract(t *testing.T) {
+	body, err := os.ReadFile(filepath.Join("..", "..", "..", "examples", "http-run.json"))
+	if err != nil {
+		t.Fatalf("read maintained HTTP request example: %v", err)
+	}
+
+	runner := &fakeRunner{result: &domain.RunResult{}}
+	h := NewHandler(runner)
+	req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewReader(body))
+	w := httptest.NewRecorder()
+
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected maintained HTTP request example to be accepted, got %d: %s", w.Code, w.Body.String())
+	}
+	if runner.last.PromptID != "generic.markdown_summary" {
+		t.Fatalf("unexpected prompt ID: %q", runner.last.PromptID)
+	}
+	if runner.last.ProfileID != "local-fast" {
+		t.Fatalf("unexpected profile ID: %q", runner.last.ProfileID)
+	}
+	wantInputs := map[string]domain.ArtifactRef{
+		"transcript": {Type: domain.ArtifactRefFile, URI: "./examples/fixtures/transcript.md"},
+		"glossary":   {Type: domain.ArtifactRefFile, URI: "./examples/fixtures/glossary.yml"},
+	}
+	if !reflect.DeepEqual(runner.last.Inputs, wantInputs) {
+		t.Fatalf("unexpected inputs: got %#v, want %#v", runner.last.Inputs, wantInputs)
+	}
+	if runner.last.Vars["session_date"] != "2026-05-04" {
+		t.Fatalf("unexpected session_date: %#v", runner.last.Vars)
+	}
+}
+
 type handlerPromptRepo struct {
 	def *domain.PromptDefinition
 }