Document the new configuration and processing workflow

docs/integrations/openai-compatible-llm.md

@@ -1,26 +1,26 @@
 # OpenAI-Compatible LLM Integration
 
-Audita uses the pinned [PromptKit](https://gitea.maximumdirect.net/eric/promptkit)
+Audita uses the pinned [PromptKit](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09)
 built-in OpenAI-compatible transport. PromptKit owns chat-completions wire framing,
 provider envelope parsing, transient retries, per-generation timeouts, and JSON
 Schema repair. A backend's configured base endpoint must support the selected
 profile's model and structured JSON-schema responses; local configuration
 inspection does not contact the provider.
 
-Audita selects a role profile, supplies its registered backend credential, and
-passes the embedded response schema as a complete per-call output contract. It
-prepares each call once, checks that the prepared target still matches the
-inspected backend and endpoint, then executes that same prepared request. A
-profile cannot introduce a separate credential environment lookup. An absent
-backend credential permits an unauthenticated local service.
+Audita selects role profiles independently for each pipeline entry and supplies
+its domain response schema and per-operation budget. PromptKit owns backend and
+credential selection, request preparation, transport, retries, repairs, and
+admission. Audita executes the same prepared handle and retains its own domain
+validation. Profiles may use native endpoint and credential settings; local
+inspection does not resolve a credential value or call the provider.
 
 `llm.transient_retries` counts additional attempts for eligible transient
 failures; explicit zero makes one attempt. `llm.repair_attempts` counts
 additional generations for schema-invalid model output. The operation timeout
 covers preparation, capacity waiting, retries, generation, and repair. Caller
 cancellation or an earlier deadline also applies. See [configuration](../config.md#settings)
-for defaults and [PromptKit v0.14.0's consumer contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.14.0/docs/consumers/pkg-promptkit.md)
-for the pinned protocol and retry details.
+for defaults and the [PromptKit consumer contract](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.21.0/docs/consumers/pkg-promptkit.md)
+for protocol and retry details.
 
 A model operation that exhausts structural repair, a live-parent local operation
 timeout, capacity rejection, transport failure, malformed provider response,
@@ -31,4 +31,4 @@ continue. Caller cancellation, broken assets or configuration, and unknown
 internal failures remain fatal and cancel peers. Audita decodes into domain
 types only after PromptKit validates the JSON. Ordinary reports use safe reason
 codes and counts rather than provider messages. Full request/response content
-is written only with `--debug`; see [operations](../operations.md#diagnostics-directory).
+is written only with `--debug`; see [operations](../operations.md#debug-evidence).

docs/integrations/output-files.md

@@ -5,7 +5,7 @@
 The corrected transcript uses the selected `output.schema`: `bare-segments`
 or `audita-v1`. Its schema and text rules are unchanged by resilience
 reporting. See [configuration](../config.md#settings) for selection and
-[operations](../operations.md#required-output-files) for placement and writes.
+[operations](../operations.md#outputs-and-lifecycle) for placement and writes.
 
 With reporting enabled, Audita produces three ordinary files:
 
@@ -46,7 +46,7 @@ remain in opt-in debug files.
 ## Error and Recovery Records
 
 An `errors` record with `scope: work_unit` identifies zero-based `stage_index`
-and `chunk_index`, module key/instance, initial segment range, applied-correction
+and `chunk_index`, optional `stage_id`, module key/instance, initial segment range, applied-correction
 count, and a `failures` sequence. Each failure identifies the operation
 (`proposal`, `validation`, or `validation_input`), optional validator and
 zero-based batch index, safe reason/message, sorted proposal indices when
@@ -59,7 +59,7 @@ For `validation_decisions_invalid`, proposal indices identify only candidates
 whose required decisions were unavailable. Other candidates in the same batch
 may still be approved or rejected normally.
 
-Each recovery identifies its work unit and successful operation, with sorted
+Each recovery identifies its work unit, optional `stage_id`, and successful operation, with sorted
 `reasons`, a safe message, available execution counts, and sorted
 `filtered_proposals` details. One recovery can contain `output_repaired`,
 `service_recovered`, and `proposals_filtered` together. Filtering covers
@@ -79,8 +79,8 @@ is an error even when unexpected indices were also ignored.
 `report.md` includes run ID, status, corrections, work coverage, error and
 recovery totals, input/output paths, and full work-unit error and recovery
 matrices. Rows show every initial chunk with 1-based chunk number and initial
-segment range; columns follow configured module-instance order, including
-repeats. Completed error cells are `0` or `1`; recovery cells are operation
+segment range; columns follow configured pipeline order, including repeated modules. Labels show
+the one-based position and module, plus the operator ID when supplied. Completed error cells are `0` or `1`; recovery cells are operation
 counts. `—` means not started and `n*` means interrupted with n facts recorded.
 An empty stage or chunk set is identified as having no work units. Short reason breakdowns count
 records containing each reason; a recovery can have several reasons, so those
@@ -91,10 +91,9 @@ files. It does not include transcript excerpts or correction lists.
 
 With `--debug`, `correction-ledger.json` contains proposed candidates and
 their application, rejection, or interruption details. `llm-execution.json`
-holds logical calls and PromptKit execution events; `utilization-diagnostics.json`
-groups backend capacity and timing observations while preserving known and
-complete usage semantics. Interaction request/response artifacts, selected
-profiles, configuration provenance, and input snapshots are also debug-only.
+holds logical calls and PromptKit execution events. Interaction request/response
+artifacts and input snapshots are also debug-only. Records carry zero-based
+`stage_index` and optional `stage_id` where an entry is identified.
 These files are diagnostic evidence, not an alternate ordinary report schema.
 Each candidate-backed ledger entry includes `proposed_corrected_text`, the
 literal replacement span, even when it is `""` for a deletion. Applied entries

docs/integrations/subprocess.md

@@ -6,15 +6,15 @@ The [CLI reference](../cli.md) owns command syntax, streams, and exit semantics;
 
 ## Invocation
 
-Use an argument array with the transcript path and required glossary argument,
-following the [process examples](../cli.md#commands-and-help). For machine workflows,
+Use an argument array with the transcript path and configured glossary selections,
+following the [process examples](../cli.md#processing). For machine workflows,
 select an explicit transcript file destination and a configuration path. Reports
 go beside the transcript unless an explicit `--report-dir` selects another
 directory. For stdout output, reports use the effective `reporting.stdout_dir`
 (defaulting to the invocation working directory), including a `--report-dir`
 override. A config-file or overlay value for `reporting.stdout_dir` alone does
 not redirect file-output reports. `--work-dir` selects a debug root, while
-configuration or `--debug` enables capture; the path flag alone does not.
+`--debug` enables capture; the path flag alone does not.
 Supplying a configuration path also makes file selection predictable; only
 explicitly referenced credential variables are read from the environment.
 
@@ -26,7 +26,7 @@ or cancellation in the parent process when needed.
 ## Result Handling
 
 Interpret the exit result according to the
-[CLI output and exit contract](../cli.md#streams-and-exit-status).
+[CLI output and exit contract](../cli.md#inspection-and-outcomes).
 Consume transcript/report data through the
 [output-file contract](output-files.md), and treat stderr as human-readable detail.
 The three reports may be absent after early configuration or destination
@@ -38,7 +38,7 @@ transcript may have been written before a later required report failure, so
 the file alone does not prove completion.
 
 If processing fails, preserve available evidence and follow
-[operations recovery](../operations.md#failure-inspection-and-recovery).
+[operations recovery](../operations.md#recovery).
 Ordinary reports are independent of optional retained debug evidence. Parent
 cancellation reaches the child through its context; Audita joins workers and
 attempts failed-status report finalization before exiting. Uncatchable
@@ -49,4 +49,4 @@ file nor a debug directory alone establishes successful completion.
 
 - [Transcript and glossary inputs](transcript-glossary-files.md)
 - [LLM endpoint compatibility](openai-compatible-llm.md)
-- [Configuration inspection commands](../cli.md#commands-and-help)
+- [Configuration inspection commands](../cli.md#inspection-and-outcomes)

docs/integrations/transcript-glossary-files.md

@@ -28,23 +28,11 @@ The [tiny transcript](../../examples/tiny-transcript.json) is a complete copyabl
 input. Invalid JSON, unsupported top-level shapes, empty transcripts, invalid field
 types, duplicate supplied IDs, and the validation failures above are rejected.
 
-## Glossary YAML Contract
+## Glossary collections
 
-The top-level object contains a `glossary` list with at least one entry.
-
-| Entry field | Type and validation |
-| --- | --- |
-| `name` | Non-empty string |
-| `category` | Non-empty string |
-| `summary` | Non-empty string |
-| `aliases` | Optional list of non-empty strings |
-| `plural` | Optional string |
-
-The parser checks empty strings without trimming them. Unknown YAML fields are
-ignored by the glossary parser, unlike the stricter
-[configuration-file schema](../config.md#loading-and-precedence).
-
-The [tiny glossary](../../examples/tiny-glossary.yaml) is a complete copyable input.
-Malformed YAML, an empty/missing glossary, invalid shapes, missing required text,
-and empty aliases are rejected. These formats describe input acceptance, not
-additional vocabulary restrictions.
+Glossary definitions are composed as application configuration, including the
+optional companion inputs described by the [configuration reference](../config.md).
+The [local example](../../examples/local/glossary.yml) provides a complete
+collection. Configuration may contain empty collections; processing preflight
+requires every glossary-correction entry to select at least one glossary entry.
+The previous standalone `glossary` file format is not a processing input.