Consolidate external documentation contracts

docs/consumers/api.md

@@ -1,65 +1,26 @@
 # Consumer Integration Overview
 
-This guide is for applications that call Scriptorium from another codebase.
+This guide helps applications choose a Scriptorium interface and understand
+their responsibilities. The linked contracts own interface syntax and wire
+semantics.
 
-Scriptorium exposes three integration surfaces:
-
-| Surface | Use when |
+| Interface | Use when |
 | --- | --- |
-| Go package | The consumer is Go, needs typed requests/results, or wants injected LLM clients for tests. |
-| CLI subprocess | The consumer wants process isolation or is not written in Go. |
-| HTTP API | The consumer needs a service boundary or remote access to `POST /v1/runs`. |
+| Go package | The consumer is Go and needs typed requests, results, or an injected LLM client. |
+| CLI subprocess | The consumer needs process isolation or is not written in Go. |
+| HTTP API | The consumer needs a service boundary or remote access. |
 
-Canonical references:
+- Go package: [package contract](pkg-scriptorium.md)
+- CLI subprocess: [subprocess integration](../integrations/subprocess.md)
+- HTTP service: [HTTP API reference](../api.md)
+- Prompt, profile, schema, and credential configuration: [configuration reference](../config.md)
 
-- Go package: [Package scriptorium](pkg-scriptorium.md)
-- CLI subprocess: [Subprocess integration](../integrations/subprocess.md)
-- HTTP: [HTTP API reference](../api.md)
-- File formats: [Configuration reference](../config.md)
-
-## Required Deployment Inputs
-
-Every integration needs operators to provide:
-
-- prompt definitions;
-- profile definitions or built-in profile IDs;
-- schema files when prompts use `json_schema`;
-- input artifacts or inline input bodies;
-- API-key environment variables or direct per-request keys where supported.
-
-Raw API keys do not belong in config, prompt files, profile YAML, CLI
-arguments, or HTTP request bodies.
-
-## Recommended Workflow
-
-Use the Go package when:
-
-- the consumer is a Go application;
-- the application needs `context.Context` cancellation;
-- repeated calls should avoid subprocess startup;
-- tests need a fake LLM client;
-- direct per-request `RunRequest.APIKey` is required.
-
-Use the CLI subprocess when:
-
-- the consumer is not Go;
-- process isolation is useful;
-- stdout/stderr separation and exit codes are enough;
-- the consumer already manages local files and environment variables.
-
-Use HTTP when:
-
-- Scriptorium should run as a service;
-- multiple clients need a shared prompt/profile deployment;
-- clients can reach a trusted, protected HTTP boundary.
-
-## Minimal Go Example
+## Minimal Go Use
 
 ```go
 engine, err := scriptorium.NewEngine(scriptorium.Config{
 	PromptDir:  "./examples/prompts",
 	ProfileDir: "./examples/profiles",
-	SchemaDir:  "./examples/schemas",
 })
 if err != nil {
 	return err
@@ -69,54 +30,30 @@ prepared, err := engine.Prepare(ctx, scriptorium.RunRequest{
 	PromptID: "generic.markdown_summary",
 	Inputs: map[string]scriptorium.ArtifactRef{
 		"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
-		"glossary":   scriptorium.File("./examples/fixtures/glossary.yml"),
 	},
 })
 if err != nil {
 	return err
 }
-_ = prepared.Messages
+_ = prepared
 ```
 
-Run the maintained package example:
-
-```bash
-go run ./examples/go-library/prepare
-```
-
-## Subprocess Workflow
-
-Invoke `scriptorium render` for preflight and `scriptorium run` for generation.
-Capture stdout and stderr separately. Treat exit code `2` from `run` as a
-completed generation with failed validation.
-
-See [Subprocess integration](../integrations/subprocess.md) for the stable
-invocation contract.
-
-## HTTP Workflow
-
-Run `scriptorium serve` behind trusted controls and send JSON requests to
-`POST /v1/runs`.
-
-Do not duplicate endpoint schemas in consumers. Use the [HTTP API
-reference](../api.md) as the authoritative contract.
+For a maintained program, see
+[`examples/go-library/prepare`](../../examples/go-library/prepare).
 
 ## Consumer Responsibilities
 
 Consumers are responsible for:
 
-- selecting prompt/profile IDs as deployment configuration;
-- supplying all required inputs and vars;
-- protecting generated artifacts and rendered prompts as sensitive data;
-- deciding whether to keep output when validation fails;
-- implementing retries only when another model call is acceptable.
+- selecting and deploying prompt, profile, and schema assets;
+- supplying required inputs and template variables;
+- supplying credentials through the applicable interface;
+- protecting rendered prompts and generated artifacts as potentially sensitive;
+- deciding whether validation-failed output is usable; and
+- retrying only when another model call is acceptable.
 
-Scriptorium does not persist run state. Retrying a failed or timed-out request
-can produce different output and can incur another provider request.
-
-## Status Behavior
-
-- Go package methods return typed results or errors that support `errors.Is`.
-- CLI `run` exits `2` when generation succeeds but validation fails.
-- HTTP returns `200 OK` for generated-content validation failures and exposes the failed status in the response body.
-- Runtime validation failures are errors.
+Scriptorium does not persist run state. A retry can produce different output and
+can incur another provider request. CLI exit behavior belongs to the
+[CLI reference](../cli.md); HTTP status behavior belongs to the
+[HTTP API reference](../api.md); package errors and results belong to the
+[package contract](pkg-scriptorium.md).