Updated audita configuration to reflect the new audita public CLI

Update the audita integration documentation reference
Added filesystem-based secrets loading configuration
2026-05-16 08:46:48 -05:00 · 2026-05-16 08:02:18 -05:00 · 2026-05-16 07:56:22 -05:00 · 2026-05-16 07:36:25 -05:00 · 2026-05-14 21:02:06 -05:00
26 changed files with 2313 additions and 376 deletions
--- a/README.md
+++ b/README.md
@@ -28,6 +28,23 @@ Narratio expects two YAML files:
 - `pipeline.yml`: pipeline/workspace settings
 - `session.yml`: per-session settings

+Pipeline config lookup for CLI commands:
+
+- if `--config <path>` is provided, Narratio uses that path
+- if `--config` is omitted, Narratio searches in this order:
+  - `/usr/local/etc/narratio/pipeline.yml`
+  - `/etc/narratio/pipeline.yml`
+
+Optional secrets-from-files config:
+
+- `pipeline.secrets.env_dir` may point to a directory of secret files
+- each top-level file with an env-var-style name is loaded as an environment variable:
+  - file name = env var name
+  - file contents = env var value (trailing newline/CRLF trimmed)
+- process environment wins: existing env vars are not overwritten
+- if configured, Narratio fails fast when `env_dir` is missing/unreadable
+- relative `env_dir` values resolve from Narratio’s current working directory
+
 YAML decoding is strict (`KnownFields(true)`), so unknown fields fail fast.

 ## Canonical Stage Order
@@ -49,6 +66,33 @@ YAML decoding is strict (`KnownFields(true)`), so unknown fields fail fast.
 - `transcripts/normalized.json`: Seriatim-normalized transcript from the normalize stage
 - `transcripts/trimmed.json`: gameplay-only normalized polished transcript from trim stage

+## Audita Configuration
+
+`pipeline.audita` configures the real Audita subprocess adapter used by `polish`.
+
+Required:
+
+- `binary`
+- `timeout`
+- `base_url`
+- `model`
+
+Optional:
+
+- `llm_api_key_env` (when set, Narratio requires that env var and passes it to Audita as `AUDITA_LLM_API_KEY`)
+- `modules` override list (when empty/omitted, Narratio does not pass `--modules`)
+- `transcript_description`
+- `config_path`
+- `output_schema` (`bare-segments` or `audita-v1`)
+- `work_dir_retention` (`always`, `auto`, or `never`)
+- `total_llm_concurrency` (> 0 when provided)
+- `proposal_llm_concurrency` (> 0 when provided)
+- `validation_model`
+- `validation_llm_concurrency` (> 0 when provided)
+- `report` (defaults to `true`)
+
+Narratio passes only configured optional Audita flags. Omitted optional values are left to Audita runtime defaults.
+
 ## Normalize Configuration

 `pipeline.normalize` is optional. When omitted, Narratio defaults to:
@@ -192,6 +236,8 @@ Prompt IDs and profile IDs are configuration values. They are not hardcoded in a

 Do not put secrets in `pipeline.yml`. If API-key behavior is configured, use env var names only.

+If `pipeline.secrets.env_dir` is configured, keep only references and secret files there; secret values are still not written to manifests, generated configs, or Narratio-managed logs.
+
 ## Scriptorium Runtime Behavior

 Narratio integrates with Scriptorium through the public CLI subprocess contract:
@@ -242,9 +288,11 @@ go test ./...
 Plan a run:

 ```bash
-go run ./cmd/narratio plan --config examples/pipeline.minimal.yml --session examples/session.minimal.yml
+go run ./cmd/narratio plan --session examples/session.minimal.yml
 ```

+Use `--config <path>` to override default pipeline lookup when needed.
+
 Run full pipeline:

 ```bash
--- a/architecture.md
+++ b/architecture.md
@@ -94,12 +94,53 @@ Adapter behavior:

 ## 5. Configuration Contract

+CLI pipeline config path resolution:
+
+- when `--config <path>` is provided, that path is used
+- when `--config` is omitted, Narratio searches defaults in order:
+  - `/usr/local/etc/narratio/pipeline.yml`
+  - `/etc/narratio/pipeline.yml`
+
+Optional pipeline secrets directory:
+
+- `pipeline.secrets.env_dir` enables loading environment variables from local files before command execution
+- file name = env var name; file contents = env var value (trailing newline/CRLF trimmed)
+- only env-var-style file names are considered; other entries are ignored
+- existing process environment values are preserved (not overwritten)
+- if configured, unreadable/missing `env_dir` fails command execution early
+- relative `env_dir` values are resolved from current working directory
+
 `pipeline.scriptorium` is optional. Existing pipelines without Scriptorium continue to work.

 `pipeline.trim` is optional. Existing pipelines without trim config continue to work.

 `pipeline.normalize` is optional. Existing pipelines without normalize config continue to work.

+`pipeline.audita` drives the real Audita subprocess adapter for the `polish` stage.
+
+Audita required fields:
+
+- `binary`
+- `timeout`
+- `base_url`
+- `model`
+
+Audita optional fields:
+
+- `llm_api_key_env` (enforced only when configured)
+- `modules` override list (when omitted/empty, Narratio does not pass `--modules`)
+- `transcript_description`
+- `config_path`
+- `output_schema` (`bare-segments` or `audita-v1`)
+- `work_dir_retention` (`always`, `auto`, `never`)
+- `total_llm_concurrency` (> 0 when provided)
+- `proposal_llm_concurrency` (> 0 when provided)
+- `validation_model`
+- `validation_llm_concurrency` (> 0 when provided)
+- `report` (default `true`)
+
+Narratio passes only configured optional Audita flags; omitted optional values defer to Audita defaults.
+
 When `pipeline.normalize` is omitted, defaults are applied:

 - `output_path: transcripts/normalized.json`
@@ -281,6 +322,7 @@ Current expected paths for `session_recap`:

 - do not store secrets in pipeline YAML, generated invocation YAML, logs, or manifest metadata
 - if API-key integration is configured, pass env var names only (never raw key values)
+- with `pipeline.secrets.env_dir`, secret file values are loaded into process env only and are not persisted in manifest metadata or generated configs
 - avoid logging transcript content or rendered prompt content by default
 - treat generated artifacts and logs as potentially sensitive session material

--- a/docs/integrations/audita.md
+++ b/docs/integrations/audita.md
@@ -1,147 +1,96 @@
-# Audita
+# Audita Subprocess Operations

-Audita is a framework-first transcript correction application. The public `audita` package provides:
+This document describes how parent processes should invoke `audita process` safely in production orchestration.

- deterministic transcript normalization
- token-batched module orchestration
- concrete `glossary`, `homophones`, `spoken_word`, and `grammar` modules built on reusable proposal / validator contracts
- structured run reporting and work-dir diagnostics
+## Recommended command form

-The previous working implementation has been preserved as `audita_prototype` inside this repository. Its full regression suite lives under `tests/audita_prototype`.
-
-## Development
-
-This project is set up for `uv`.
+Use explicit file outputs for orchestrated runs:

 ```sh
-uv sync --extra dev
-uv run pytest
+audita process <transcript.json> \
+  --transcript-description "Brief context that may help resolve ambiguous terms." \
+  --glossary <glossary.yaml> \
+  --output <output-transcript.json> \
+  --report-json <report.json>
 ```

-## Usage
+Additional flags that may be situationally appropriate:
+- `--config <path>` to select an explicit versioned config file.
+- `--output-schema <bare-segments|audita-v1>` to select transcript output shape.
+- `--work-dir <dir>` to control diagnostics location.
+- `--work-dir-retention <always|auto|never>` to control retained run directories.
+- `--total-llm-concurrency`, `--proposal-llm-concurrency`, and `--validation-llm-concurrency` when orchestration needs to set explicit LLM throughput controls.
+- `--modules ...` only when intentionally overriding the default sequence.

-Process a transcript with the current framework implementation:
+For config-driven orchestration, validate config files in CI/preflight:

 ```sh
-uv run audita process transcript.json --glossary glossary.yaml --output corrected.json
+audita config validate --config <path>
 ```

-The framework currently runs this default module sequence:
+## Stdout behavior

-1. `glossary`
-2. `homophones`
-3. `glossary`
-4. `spoken_word`
-5. `grammar`
+- With `--output`: stdout is expected to be empty on success.
+- Without `--output`: stdout contains transcript JSON only on success.
+- Report JSON is never written to stdout.

-Resolved run instance names are auto-numbered for repeats, so the default report pipeline is:
+## Stderr behavior

-1. `glossary_1`
-2. `homophones`
-3. `glossary_2`
-4. `spoken_word`
-5. `grammar`
+- Success path should be quiet or minimal human-readable logs.
+- Failure path writes concise human-readable errors.
+- When a diagnostics run directory exists, failure stderr includes its path.
+- Prompt/response diagnostic payloads are not streamed to stderr.

-The default module sequence is fully implemented today:
+## Output file behavior

- `glossary` proposes glossary-supported acoustic corrections
- `homophones` proposes conservative homophone and mistranscription corrections
- `spoken_word` proposes conservative dysfluency cleanup
- `grammar` proposes punctuation, capitalization, and spacing cleanup only
+- `--output` writes transcript JSON in the selected output schema to the provided path.
+- Output write failures return nonzero and surface actionable errors.
+- The command does not silently ignore output write errors.

-To run a custom module sequence, pass `--modules`:
+## Report JSON behavior

-```sh
-uv run audita process transcript.json --glossary glossary.yaml --modules grammar --output corrected.json
-```
+- `--report-json` writes a machine-readable process report to the requested path.
+- Run-directory `report.json` is written independently under diagnostics.
+- Best-effort failure reports are emitted when possible without masking the primary failure.
+- Report write failures return nonzero with clear stderr messaging.
+- Report diagnostics metadata references run-directory artifacts including utilization diagnostics and correction ledger paths when available.

-To also write a structured JSON report:
+## Diagnostics directory behavior

-```sh
-uv run audita process transcript.json --glossary glossary.yaml --output corrected.json --report-json report.json
-```
+- Each run creates (when possible) a per-run diagnostics directory.
+- Typical artifacts include transcript, normalization, chunking, invocation, effective config, LLM diagnostics, `utilization-diagnostics.json`, `correction-ledger.json`, `report.json`, and `error.log` on failure.
+- Failed runs retain diagnostics.
+- Under `auto` retention, successful runs with skipped/rejected corrections are retained; clean successful runs may be removed.

-From a checked-out repository, you can also use the root launcher:
+## Exit codes

-```sh
-./audita process transcript.json --glossary glossary.yaml --output corrected.json
-```
+- `0`: success.
+- Nonzero: failure (input/schema/config/module/LLM/runtime/output/report/diagnostics errors).

-For a system-wide command, install the source tree under `/usr/local/src/audita`, sync dependencies there, and symlink the root launcher into your `PATH`:
+Treat any nonzero as a failed subprocess invocation.

-```sh
-cd /usr/local/src/audita
-uv sync --extra dev
-ln -s /usr/local/src/audita/audita /usr/local/bin/audita
-audita process transcript.json --glossary glossary.yaml --output corrected.json
-```
+## Timeout and cancellation

-Without `--output`, Audita writes the corrected transcript JSON to stdout and progress logs to stderr.
-`--report-json` writes a separate machine-readable run report and never mixes report data into stdout.
+- Runtime operations propagate context cancellation and request timeouts through LLM/scheduler paths.
+- On cancellation or timeout, the process exits nonzero and should not hang.
+- If diagnostics were initialized before failure, failure artifacts remain available for debugging.

-Useful configuration can be supplied by CLI flag or environment variable. CLI flags take precedence over environment variables. Normal runs now require LLM API credentials, because the `glossary`, `homophones`, `spoken_word`, and `grammar` modules make real LLM calls. `AUDITA_LLM_API_KEY` and `--llm-api-key` are the preferred provider-neutral credential surfaces, while `OPENROUTER_API_KEY` remains supported as a backward-compatible fallback.
+## Secret redaction expectations

-| Environment variable | CLI flag | Default | Purpose |
-| --- | --- | --- | --- |
-| `AUDITA_MODULES` | `--modules` | `glossary,homophones,glossary,spoken_word,grammar` | Comma-separated logical module keys to run; CLI overrides the environment value |
-| `AUDITA_LLM_API_KEY` | `--llm-api-key` | unset | Preferred provider-neutral LLM API credential; CLI overrides both environment-key variants |
-| `AUDITA_VALIDATION_LLM_API_KEY` | `--validation-llm-api-key` | unset | Validation-phase LLM API credential; defaults to the primary LLM API key |
-| `AUDITA_MODEL` | `--model` | `openrouter/google/gemma-4-31b-it` | LLM model name sent to the configured OpenAI-compatible endpoint |
-| `AUDITA_VALIDATION_MODEL` | `--validation-model` | unset | Validation-phase LLM model; defaults to `AUDITA_MODEL` |
-| `AUDITA_BASE_URL` | `--base-url` | `https://openrouter.ai/api/v1` | OpenAI-compatible API base URL |
-| `AUDITA_VALIDATION_BASE_URL` | `--validation-base-url` | unset | Validation-phase OpenAI-compatible API base URL; defaults to `AUDITA_BASE_URL` |
-| `AUDITA_LLM_TIMEOUT_SECONDS` | `--llm-timeout-seconds` | `600` | Per-request timeout in seconds for LLM calls to the configured OpenAI-compatible endpoint |
-| `AUDITA_VALIDATION_LLM_TIMEOUT_SECONDS` | `--validation-llm-timeout-seconds` | unset | Validation-phase per-request timeout in seconds; defaults to `AUDITA_LLM_TIMEOUT_SECONDS` |
-| `AUDITA_VALIDATION_MAX_PROMPT_TOKENS` | `--validation-max-prompt-tokens` | `2048` | Maximum estimated tokens per validation-phase LLM prompt batch |
-| `AUDITA_TARGET_SECTIONS` | `--target-sections` | unset | Exact number of contiguous proposal-stage transcript sections; errors if min/max token bounds cannot be satisfied |
-| `AUDITA_MAX_RETRIES` | `--max-retries` | `3` | Maximum Instructor retries for structured responses |
-| `AUDITA_VALIDATION_MAX_RETRIES` | `--validation-max-retries` | unset | Validation-phase structured-output retries; defaults to `AUDITA_MAX_RETRIES` |
-| `AUDITA_VALIDATION_LLM_CONCURRENCY` | `--validation-llm-concurrency` | unset | Validation-phase LLM concurrency; defaults to `AUDITA_LLM_CONCURRENCY` |
-| `AUDITA_MAX_SECTION_TOKENS` | `--max-section-tokens` | `8192` | Maximum estimated tokens per proposal-stage transcript section |
-| `AUDITA_MIN_SECTION_TOKENS` | `--min-section-tokens` | `2048` | Minimum estimated tokens per proposal-stage transcript section when balancing for concurrency |
-| `AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD` | `--glossary-confidence-threshold` | `0.8` | Minimum confidence required for glossary proposals to survive validation |
-| `AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD` | `--grammar-confidence-threshold` | `0.8` | Minimum confidence required for grammar proposals to survive validation |
-| `AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD` | `--homophones-confidence-threshold` | `0.8` | Minimum confidence required for homophone proposals to survive validation |
-| `AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD` | `--spoken-word-confidence-threshold` | `0.8` | Minimum confidence required for spoken-word proposals to survive validation |
-| `AUDITA_NORMALIZE_MAX_SEGMENT_GAP` | `--normalize-max-segment-gap` | `4.0` | Same-speaker gaps eligible for deterministic merging |
-| `AUDITA_NORMALIZE_ELLIPSIS_GAP` | `--normalize-ellipsis-gap` | `3.5` | Same-speaker gaps above this value are joined with ` ... ` |
-| `AUDITA_NORMALIZE_MAX_SEGMENT_DURATION` | `--normalize-max-segment-duration` | `60.0` | Maximum merged segment duration |
-| `AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS` | `--normalize-max-segment-tokens` | `2048` | Maximum merged segment prompt payload size |
-| `AUDITA_WORK_DIR` | `--work-dir` | `/tmp/audita` | Per-run scratch diagnostics directory |
-| `AUDITA_WORK_DIR_RETENTION` | `--work-dir-retention` | `auto` | Whether to retain the per-run work directory: `auto`, `always`, or `never` |
+API keys and configured secret values are redacted from:
+- reports (`--report-json` and run-dir `report.json`);
+- diagnostics artifacts (including effective config and LLM interaction artifacts);
+- surfaced adapter/runtime errors;
+- test fixtures and regression outputs.

-Set `AUDITA_MODULES=grammar` to run only the grammar module by default, or override it per command with `--modules`.
+Parent-process logs should still avoid printing raw environment variables.

-Validation-phase LLM settings inherit from the primary `AUDITA_*` LLM settings by default. Set any of the `AUDITA_VALIDATION_*` values only when you want LLM-backed validators to use a different model, endpoint, credential, timeout, retry budget, or concurrency level.
+## Parent-process pipe guidance

-OpenRouter remains the default out of the box:
+To avoid deadlocks in orchestrators:
+- always read both stdout and stderr concurrently when invoking as a subprocess;
+- prefer file outputs (`--output`, `--report-json`) for machine workflows;
+- treat stderr as human-readable diagnostics, not structured data;
+- parse structured results from output/report files.

-```sh
-export AUDITA_LLM_API_KEY=your-openrouter-key
-audita process transcript.json --glossary glossary.yaml --output corrected.json
-```
-
-You can point Audita at any OpenAI-compatible endpoint by changing `AUDITA_BASE_URL` and, if needed, `AUDITA_MODEL`. For example, a local vLLM server:
-
-```sh
-export AUDITA_LLM_API_KEY=local-dev-key
-export AUDITA_BASE_URL=http://localhost:8000/v1
-export AUDITA_MODEL=meta-llama/Llama-3.1-8B-Instruct
-audita process transcript.json --glossary glossary.yaml --output corrected.json
-```
-
-Or the actual OpenAI API:
-
-```sh
-export AUDITA_LLM_API_KEY=your-openai-key
-export AUDITA_BASE_URL=https://api.openai.com/v1
-export AUDITA_MODEL=gpt-4.1-mini
-audita process transcript.json --glossary glossary.yaml --output corrected.json
-```
-
-`AUDITA_WORK_DIR` stores per-run diagnostics while processing. Under the default `AUDITA_WORK_DIR_RETENTION=auto`, clean successful runs are removed, while failed runs and successful runs with final skipped corrections are preserved. Use `always` to keep every run directory and `never` to remove successful run directories even when skips remain.
-Failed runs always preserve the run directory and include an authoritative `report.json` alongside normalization and prompt/response diagnostics.
-
-## Prototype Archive
-
-The archived prototype remains importable as `audita_prototype` and is still covered by its original regression suite. This is intentional: the new `audita` package is a framework-oriented rewrite, not a thin wrapper around the old code.
+For Go callers, prefer `exec.CommandContext` with explicit timeout/cancellation and buffered/streamed readers for both pipes.
--- a/docs/roadmap/narratio-s3-archive-implementation-plan.md
+++ b/docs/roadmap/narratio-s3-archive-implementation-plan.md
--- a/examples/pipeline.minimal.yml
+++ b/examples/pipeline.minimal.yml
@@ -4,6 +4,11 @@ workspace:
 storage:
  backend: local

+secrets:
+  # Optional: load environment variables from files in this directory.
+  # File name = env var name; file contents = env var value.
+  env_dir: /var/local/narratio/secrets
+
 whisperx:
  transcribe_url: "https://transcription.example.com/transcribe"
  language: "en"
@@ -28,17 +33,16 @@ audita:
  binary: "audita"
  timeout: "3h"
  llm_api_key_env: "AUDITA_LLM_API_KEY"
-  modules:
-    - glossary
-    - homophones
-    - glossary
-    - spoken_word
-    - grammar
-    - homophones
-    - glossary
+  # Optional: pass only when overriding Audita's default module sequence.
+  modules: []
  base_url: "https://openrouter.ai/api/v1"
  model: "openrouter/google/gemma-4-31b-it"
-  llm_concurrency: 1
+  transcript_description: ""
+  config_path: ""
+  output_schema: "audita-v1"
+  work_dir_retention: "auto"
+  total_llm_concurrency: 1
+  proposal_llm_concurrency: 1
  validation_model: ""
  validation_llm_concurrency: 1
  report: true
--- a/internal/adapters/audita/runner.go
+++ b/internal/adapters/audita/runner.go
@@ -24,6 +24,12 @@ type PolishRequest struct {
 	Modules                  []string
 	BaseURL                  string
 	Model                    string
+	TranscriptDescription    string
+	ConfigPath               string
+	OutputSchema             string
+	WorkDirRetention         string
+	TotalLLMConcurrency      *int
+	ProposalLLMConcurrency   *int
 	ValidationModel          string
 	ValidationLLMConcurrency *int
 	StdoutLogPath            string
--- a/internal/adapters/audita/subprocess.go
+++ b/internal/adapters/audita/subprocess.go
@@ -21,7 +21,12 @@ type SubprocessRunnerConfig struct {
 	Modules                  []string
 	BaseURL                  string
 	Model                    string
-	LLMConcurrency           *int
+	TranscriptDescription    string
+	ConfigPath               string
+	OutputSchema             string
+	WorkDirRetention         string
+	TotalLLMConcurrency      *int
+	ProposalLLMConcurrency   *int
 	ValidationModel          string
 	ValidationLLMConcurrency *int
 	Report                   bool
@@ -35,7 +40,12 @@ type SubprocessRunner struct {
 	modules                  []string
 	baseURL                  string
 	model                    string
-	llmConcurrency           *int
+	transcriptDescription    string
+	configPath               string
+	outputSchema             string
+	workDirRetention         string
+	totalLLMConcurrency      *int
+	proposalLLMConcurrency   *int
 	validationModel          string
 	validationLLMConcurrency *int
 	report                   bool
@@ -49,7 +59,12 @@ func NewSubprocessRunnerFromConfigValues(
 	modules []string,
 	baseURL string,
 	model string,
-	llmConcurrency *int,
+	transcriptDescription string,
+	configPath string,
+	outputSchema string,
+	workDirRetention string,
+	totalLLMConcurrency *int,
+	proposalLLMConcurrency *int,
 	validationModel string,
 	validationLLMConcurrency *int,
 	report bool,
@@ -68,7 +83,12 @@ func NewSubprocessRunnerFromConfigValues(
 		Modules:                  modules,
 		BaseURL:                  baseURL,
 		Model:                    model,
-		LLMConcurrency:           llmConcurrency,
+		TranscriptDescription:    transcriptDescription,
+		ConfigPath:               configPath,
+		OutputSchema:             outputSchema,
+		WorkDirRetention:         workDirRetention,
+		TotalLLMConcurrency:      totalLLMConcurrency,
+		ProposalLLMConcurrency:   proposalLLMConcurrency,
 		ValidationModel:          validationModel,
 		ValidationLLMConcurrency: validationLLMConcurrency,
 		Report:                   report,
@@ -83,9 +103,6 @@ func NewSubprocessRunner(cfg SubprocessRunnerConfig) (*SubprocessRunner, error)
 	if cfg.Timeout <= 0 {
 		return nil, fmt.Errorf("audita timeout must be > 0")
 	}
-	if len(cfg.Modules) == 0 {
-		return nil, fmt.Errorf("audita modules must include at least one module")
-	}
 	for i, module := range cfg.Modules {
 		if strings.TrimSpace(module) == "" {
 			return nil, fmt.Errorf("audita module at index %d is empty", i)
@@ -104,12 +121,25 @@ func NewSubprocessRunner(cfg SubprocessRunnerConfig) (*SubprocessRunner, error)
 	if strings.TrimSpace(cfg.Model) == "" {
 		return nil, fmt.Errorf("audita model is required")
 	}
-	if cfg.LLMConcurrency != nil && *cfg.LLMConcurrency <= 0 {
-		return nil, fmt.Errorf("audita llm concurrency must be > 0 when provided")
+	if cfg.TotalLLMConcurrency != nil && *cfg.TotalLLMConcurrency <= 0 {
+		return nil, fmt.Errorf("audita total llm concurrency must be > 0 when provided")
+	}
+	if cfg.ProposalLLMConcurrency != nil && *cfg.ProposalLLMConcurrency <= 0 {
+		return nil, fmt.Errorf("audita proposal llm concurrency must be > 0 when provided")
 	}
 	if cfg.ValidationLLMConcurrency != nil && *cfg.ValidationLLMConcurrency <= 0 {
 		return nil, fmt.Errorf("audita validation llm concurrency must be > 0 when provided")
 	}
+	switch strings.TrimSpace(cfg.OutputSchema) {
+	case "", "bare-segments", "audita-v1":
+	default:
+		return nil, fmt.Errorf("audita output schema must be one of: bare-segments, audita-v1")
+	}
+	switch strings.TrimSpace(cfg.WorkDirRetention) {
+	case "", "always", "auto", "never":
+	default:
+		return nil, fmt.Errorf("audita work dir retention must be one of: always, auto, never")
+	}

 	modules := make([]string, len(cfg.Modules))
 	for i, m := range cfg.Modules {
@@ -123,7 +153,12 @@ func NewSubprocessRunner(cfg SubprocessRunnerConfig) (*SubprocessRunner, error)
 		modules:                  modules,
 		baseURL:                  strings.TrimSpace(cfg.BaseURL),
 		model:                    strings.TrimSpace(cfg.Model),
-		llmConcurrency:           cfg.LLMConcurrency,
+		transcriptDescription:    strings.TrimSpace(cfg.TranscriptDescription),
+		configPath:               strings.TrimSpace(cfg.ConfigPath),
+		outputSchema:             strings.TrimSpace(cfg.OutputSchema),
+		workDirRetention:         strings.TrimSpace(cfg.WorkDirRetention),
+		totalLLMConcurrency:      cfg.TotalLLMConcurrency,
+		proposalLLMConcurrency:   cfg.ProposalLLMConcurrency,
 		validationModel:          strings.TrimSpace(cfg.ValidationModel),
 		validationLLMConcurrency: cfg.ValidationLLMConcurrency,
 		report:                   cfg.Report,
@@ -152,7 +187,7 @@ func (r *SubprocessRunner) Run(ctx context.Context, req PolishRequest) (PolishRe
 	}

 	reqModules := req.Modules
-	if len(reqModules) == 0 {
+	if reqModules == nil {
 		reqModules = append([]string(nil), r.modules...)
 	}
 	args := r.buildArgs(req, reqModules)
@@ -168,14 +203,9 @@ func (r *SubprocessRunner) Run(ctx context.Context, req PolishRequest) (PolishRe
 		env["AUDITA_LLM_API_KEY"] = credential
 		credentialPresent = true
 	}
-	primaryConcurrencyViaEnv := false
-	if r.llmConcurrency != nil {
-		env["AUDITA_LLM_CONCURRENCY"] = strconv.Itoa(*r.llmConcurrency)
-		primaryConcurrencyViaEnv = true
-	}

 	if req.GeneratedConfigPath != "" {
-		if err := r.writeInvocationConfig(req, args, reqModules, credentialPresent, primaryConcurrencyViaEnv); err != nil {
+		if err := r.writeInvocationConfig(req, args, reqModules, credentialPresent); err != nil {
 			return PolishResult{}, fmt.Errorf("write audita invocation config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
@@ -196,7 +226,7 @@ func (r *SubprocessRunner) Run(ctx context.Context, req PolishRequest) (PolishRe
 			req.StderrLogPath,
 		)
 		wrappedMessage = addSubprocessStreamHint(wrappedMessage, err)
-		return r.failureResult(req, reqModules, runRes, credentialPresent, primaryConcurrencyViaEnv), fmt.Errorf(
+		return r.failureResult(req, reqModules, runRes, credentialPresent), fmt.Errorf(
 			"%s: %w",
 			wrappedMessage,
 			err,
@@ -204,11 +234,11 @@ func (r *SubprocessRunner) Run(ctx context.Context, req PolishRequest) (PolishRe
 	}

 	if err := validateProcessedOutput(req.OutputProcessedPath); err != nil {
-		return r.failureResult(req, reqModules, runRes, credentialPresent, primaryConcurrencyViaEnv), fmt.Errorf("validate audita processed output %q: %w", req.OutputProcessedPath, err)
+		return r.failureResult(req, reqModules, runRes, credentialPresent), fmt.Errorf("validate audita processed output %q: %w", req.OutputProcessedPath, err)
 	}
 	if r.report {
 		if err := validateJSONFile(req.ReportPath); err != nil {
-			return r.failureResult(req, reqModules, runRes, credentialPresent, primaryConcurrencyViaEnv), fmt.Errorf("validate audita report output %q: %w", req.ReportPath, err)
+			return r.failureResult(req, reqModules, runRes, credentialPresent), fmt.Errorf("validate audita report output %q: %w", req.ReportPath, err)
 		}
 	}

@@ -223,21 +253,25 @@ func (r *SubprocessRunner) Run(ctx context.Context, req PolishRequest) (PolishRe
 		Duration:                runRes.Duration,
 		InvokedBinary:           r.binary,
 		Metadata: map[string]any{
-			"adapter":                          "audita_subprocess",
-			"modules":                          reqModules,
-			"base_url":                         r.baseURL,
-			"model":                            r.model,
-			"validation_model":                 r.validationModel,
-			"validation_llm_concurrency":       r.validationLLMConcurrency,
-			"credential_env_var":               r.llmAPIKeyEnv,
-			"credential_present":               credentialPresent,
-			"primary_llm_concurrency_via_env":  primaryConcurrencyViaEnv,
-			"primary_llm_concurrency_env_name": "AUDITA_LLM_CONCURRENCY",
+			"adapter":                    "audita_subprocess",
+			"modules":                    reqModules,
+			"base_url":                   r.baseURL,
+			"model":                      r.model,
+			"transcript_description":     r.transcriptDescription,
+			"config_path":                r.configPath,
+			"output_schema":              r.outputSchema,
+			"work_dir_retention":         r.workDirRetention,
+			"validation_model":           r.validationModel,
+			"total_llm_concurrency":      r.totalLLMConcurrency,
+			"proposal_llm_concurrency":   r.proposalLLMConcurrency,
+			"validation_llm_concurrency": r.validationLLMConcurrency,
+			"credential_env_var":         r.llmAPIKeyEnv,
+			"credential_present":         credentialPresent,
 		},
 	}, nil
 }

-func (r *SubprocessRunner) failureResult(req PolishRequest, modules []string, runRes subprocess.RunResult, credentialPresent bool, primaryConcurrencyViaEnv bool) PolishResult {
+func (r *SubprocessRunner) failureResult(req PolishRequest, modules []string, runRes subprocess.RunResult, credentialPresent bool) PolishResult {
 	return PolishResult{
 		ProcessedTranscriptPath: req.OutputProcessedPath,
 		ReportPath:              req.ReportPath,
@@ -249,16 +283,20 @@ func (r *SubprocessRunner) failureResult(req PolishRequest, modules []string, ru
 		Duration:                runRes.Duration,
 		InvokedBinary:           r.binary,
 		Metadata: map[string]any{
-			"adapter":                          "audita_subprocess",
-			"modules":                          modules,
-			"base_url":                         r.baseURL,
-			"model":                            r.model,
-			"validation_model":                 r.validationModel,
-			"validation_llm_concurrency":       r.validationLLMConcurrency,
-			"credential_env_var":               r.llmAPIKeyEnv,
-			"credential_present":               credentialPresent,
-			"primary_llm_concurrency_via_env":  primaryConcurrencyViaEnv,
-			"primary_llm_concurrency_env_name": "AUDITA_LLM_CONCURRENCY",
+			"adapter":                    "audita_subprocess",
+			"modules":                    modules,
+			"base_url":                   r.baseURL,
+			"model":                      r.model,
+			"transcript_description":     r.transcriptDescription,
+			"config_path":                r.configPath,
+			"output_schema":              r.outputSchema,
+			"work_dir_retention":         r.workDirRetention,
+			"validation_model":           r.validationModel,
+			"total_llm_concurrency":      r.totalLLMConcurrency,
+			"proposal_llm_concurrency":   r.proposalLLMConcurrency,
+			"validation_llm_concurrency": r.validationLLMConcurrency,
+			"credential_env_var":         r.llmAPIKeyEnv,
+			"credential_present":         credentialPresent,
 		},
 	}
 }
@@ -269,14 +307,34 @@ func (r *SubprocessRunner) buildArgs(req PolishRequest, modules []string) []stri
 		req.MergedTranscriptPath,
 		"--glossary", req.GlossaryPath,
 		"--output", req.OutputProcessedPath,
-		"--modules", strings.Join(modules, ","),
 		"--base-url", r.baseURL,
 		"--model", r.model,
 		"--work-dir", req.WorkDir,
 	}
+	if len(modules) > 0 {
+		args = append(args, "--modules", strings.Join(modules, ","))
+	}
 	if r.report {
 		args = append(args, "--report-json", req.ReportPath)
 	}
+	if r.transcriptDescription != "" {
+		args = append(args, "--transcript-description", r.transcriptDescription)
+	}
+	if r.configPath != "" {
+		args = append(args, "--config", r.configPath)
+	}
+	if r.outputSchema != "" {
+		args = append(args, "--output-schema", r.outputSchema)
+	}
+	if r.workDirRetention != "" {
+		args = append(args, "--work-dir-retention", r.workDirRetention)
+	}
+	if r.totalLLMConcurrency != nil {
+		args = append(args, "--total-llm-concurrency", strconv.Itoa(*r.totalLLMConcurrency))
+	}
+	if r.proposalLLMConcurrency != nil {
+		args = append(args, "--proposal-llm-concurrency", strconv.Itoa(*r.proposalLLMConcurrency))
+	}
 	if r.validationModel != "" {
 		args = append(args, "--validation-model", r.validationModel)
 	}
@@ -286,29 +344,31 @@ func (r *SubprocessRunner) buildArgs(req PolishRequest, modules []string) []stri
 	return args
 }

-func (r *SubprocessRunner) writeInvocationConfig(req PolishRequest, args []string, modules []string, credentialPresent bool, primaryConcurrencyViaEnv bool) error {
+func (r *SubprocessRunner) writeInvocationConfig(req PolishRequest, args []string, modules []string, credentialPresent bool) error {
 	payload := map[string]any{
-		"schema":                          "audita.generated.v1",
-		"binary":                          r.binary,
-		"args":                            args,
-		"timeout":                         r.timeout.String(),
-		"modules":                         modules,
-		"base_url":                        r.baseURL,
-		"model":                           r.model,
-		"validation_model":                r.validationModel,
-		"validation_llm_concurrency":      r.validationLLMConcurrency,
-		"report_enabled":                  r.report,
-		"merged_transcript_path":          req.MergedTranscriptPath,
-		"glossary_path":                   req.GlossaryPath,
-		"output_path":                     req.OutputProcessedPath,
-		"report_path":                     req.ReportPath,
-		"work_dir":                        req.WorkDir,
-		"credential_env_var":              r.llmAPIKeyEnv,
-		"credential_present":              credentialPresent,
-		"primary_llm_concurrency_via_env": primaryConcurrencyViaEnv,
-	}
-	if r.llmConcurrency != nil {
-		payload["llm_concurrency"] = *r.llmConcurrency
+		"schema":                     "audita.generated.v1",
+		"binary":                     r.binary,
+		"args":                       args,
+		"timeout":                    r.timeout.String(),
+		"modules":                    modules,
+		"base_url":                   r.baseURL,
+		"model":                      r.model,
+		"transcript_description":     r.transcriptDescription,
+		"config_path":                r.configPath,
+		"output_schema":              r.outputSchema,
+		"work_dir_retention":         r.workDirRetention,
+		"validation_model":           r.validationModel,
+		"total_llm_concurrency":      r.totalLLMConcurrency,
+		"proposal_llm_concurrency":   r.proposalLLMConcurrency,
+		"validation_llm_concurrency": r.validationLLMConcurrency,
+		"report_enabled":             r.report,
+		"merged_transcript_path":     req.MergedTranscriptPath,
+		"glossary_path":              req.GlossaryPath,
+		"output_path":                req.OutputProcessedPath,
+		"report_path":                req.ReportPath,
+		"work_dir":                   req.WorkDir,
+		"credential_env_var":         r.llmAPIKeyEnv,
+		"credential_present":         credentialPresent,
 	}
 	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, 0o644)
 }
--- a/internal/adapters/audita/subprocess_test.go
+++ b/internal/adapters/audita/subprocess_test.go
@@ -25,7 +25,8 @@ func TestSubprocessRunnerSuccessArgsEnvAndValidation(t *testing.T) {
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", recordPath)

 	wrapper := writeAuditaHelperWrapper(t)
-	llmConcurrency := 1
+	totalLLMConcurrency := 3
+	proposalLLMConcurrency := 2
 	validationLLMConcurrency := 2
 	runner, err := NewSubprocessRunner(SubprocessRunnerConfig{
 		Binary:                   wrapper,
@@ -34,7 +35,12 @@ func TestSubprocessRunnerSuccessArgsEnvAndValidation(t *testing.T) {
 		Modules:                  []string{"glossary", "homophones", "glossary"},
 		BaseURL:                  "https://openrouter.ai/api/v1",
 		Model:                    "openrouter/google/gemma-4-31b-it",
-		LLMConcurrency:           &llmConcurrency,
+		TranscriptDescription:    "Campaign Session 42",
+		ConfigPath:               "/etc/audita/config.yml",
+		OutputSchema:             "audita-v1",
+		WorkDirRetention:         "auto",
+		TotalLLMConcurrency:      &totalLLMConcurrency,
+		ProposalLLMConcurrency:   &proposalLLMConcurrency,
 		ValidationModel:          "openrouter/google/gemma-4-31b-it",
 		ValidationLLMConcurrency: &validationLLMConcurrency,
 		Report:                   true,
@@ -93,11 +99,17 @@ func TestSubprocessRunnerSuccessArgsEnvAndValidation(t *testing.T) {
 		"process", req.MergedTranscriptPath,
 		"--glossary", req.GlossaryPath,
 		"--output", req.OutputProcessedPath,
-		"--modules", "glossary,homophones,glossary",
 		"--base-url", "https://openrouter.ai/api/v1",
 		"--model", "openrouter/google/gemma-4-31b-it",
 		"--work-dir", req.WorkDir,
+		"--modules", "glossary,homophones,glossary",
 		"--report-json", req.ReportPath,
+		"--transcript-description", "Campaign Session 42",
+		"--config", "/etc/audita/config.yml",
+		"--output-schema", "audita-v1",
+		"--work-dir-retention", "auto",
+		"--total-llm-concurrency", "3",
+		"--proposal-llm-concurrency", "2",
 		"--validation-model", "openrouter/google/gemma-4-31b-it",
 		"--validation-llm-concurrency", "2",
 	}
@@ -107,8 +119,8 @@ func TestSubprocessRunnerSuccessArgsEnvAndValidation(t *testing.T) {
 	if rec.Env["AUDITA_LLM_API_KEY"] != "super-secret" {
 		t.Fatalf("AUDITA_LLM_API_KEY = %q, want propagated secret", rec.Env["AUDITA_LLM_API_KEY"])
 	}
-	if rec.Env["AUDITA_LLM_CONCURRENCY"] != "1" {
-		t.Fatalf("AUDITA_LLM_CONCURRENCY = %q, want 1", rec.Env["AUDITA_LLM_CONCURRENCY"])
+	if rec.Env["AUDITA_LLM_CONCURRENCY"] != "" {
+		t.Fatalf("AUDITA_LLM_CONCURRENCY = %q, want empty/omitted", rec.Env["AUDITA_LLM_CONCURRENCY"])
 	}

 	cfgData, err := os.ReadFile(req.GeneratedConfigPath)
@@ -124,16 +136,14 @@ func TestSubprocessRunnerMissingConfiguredCredentialFails(t *testing.T) {
 	if runtime.GOOS == "windows" {
 		t.Skip("helper wrapper script uses /bin/sh")
 	}
-	llmConcurrency := 1
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:         writeAuditaHelperWrapper(t),
-		Timeout:        mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv:   "MISSING_AUDITA_KEY",
-		Modules:        []string{"glossary"},
-		BaseURL:        "https://openrouter.ai/api/v1",
-		Model:          "openrouter/google/gemma-4-31b-it",
-		LLMConcurrency: &llmConcurrency,
-		Report:         false,
+		Binary:       writeAuditaHelperWrapper(t),
+		Timeout:      mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyEnv: "MISSING_AUDITA_KEY",
+		Modules:      []string{"glossary"},
+		BaseURL:      "https://openrouter.ai/api/v1",
+		Model:        "openrouter/google/gemma-4-31b-it",
+		Report:       false,
 	})
 	req := auditaReqForTest(t, false)

@@ -155,16 +165,14 @@ func TestSubprocessRunnerUnconfiguredCredentialEnvOmitsCredential(t *testing.T)
 	recordPath := filepath.Join(t.TempDir(), "record.json")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", recordPath)

-	llmConcurrency := 1
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:         writeAuditaHelperWrapper(t),
-		Timeout:        mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv:   "",
-		Modules:        []string{"glossary"},
-		BaseURL:        "https://openrouter.ai/api/v1",
-		Model:          "openrouter/google/gemma-4-31b-it",
-		LLMConcurrency: &llmConcurrency,
-		Report:         false,
+		Binary:       writeAuditaHelperWrapper(t),
+		Timeout:      mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyEnv: "",
+		Modules:      []string{"glossary"},
+		BaseURL:      "https://openrouter.ai/api/v1",
+		Model:        "openrouter/google/gemma-4-31b-it",
+		Report:       false,
 	})
 	req := auditaReqForTest(t, false)

@@ -211,6 +219,35 @@ func TestSubprocessRunnerInheritsParentEnvironment(t *testing.T) {
 	}
 }

+func TestSubprocessRunnerOmitsModulesFlagWhenNotConfigured(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("helper wrapper script uses /bin/sh")
+	}
+	t.Setenv("GO_WANT_AUDITA_HELPER", "1")
+	t.Setenv("AUDITA_HELPER_MODE", "success")
+	recordPath := filepath.Join(t.TempDir(), "record.json")
+	t.Setenv("AUDITA_HELPER_RECORD_PATH", recordPath)
+
+	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
+		Binary:       writeAuditaHelperWrapper(t),
+		Timeout:      mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyEnv: "",
+		BaseURL:      "https://openrouter.ai/api/v1",
+		Model:        "openrouter/google/gemma-4-31b-it",
+		Report:       false,
+	})
+	req := auditaReqForTest(t, false)
+	if _, err := runner.Run(context.Background(), req); err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	rec := readAuditaHelperRecord(t, recordPath)
+	for i := 0; i < len(rec.Args); i++ {
+		if rec.Args[i] == "--modules" {
+			t.Fatalf("args contained --modules unexpectedly: %#v", rec.Args)
+		}
+	}
+}
+
 func TestSubprocessRunnerSubprocessFailure(t *testing.T) {
 	if runtime.GOOS == "windows" {
 		t.Skip("helper wrapper script uses /bin/sh")
@@ -220,16 +257,14 @@ func TestSubprocessRunnerSubprocessFailure(t *testing.T) {
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))

-	llmConcurrency := 1
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:         writeAuditaHelperWrapper(t),
-		Timeout:        mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv:   "OPENAI_KEY_SOURCE",
-		Modules:        []string{"glossary"},
-		BaseURL:        "https://openrouter.ai/api/v1",
-		Model:          "openrouter/google/gemma-4-31b-it",
-		LLMConcurrency: &llmConcurrency,
-		Report:         true,
+		Binary:       writeAuditaHelperWrapper(t),
+		Timeout:      mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
+		Modules:      []string{"glossary"},
+		BaseURL:      "https://openrouter.ai/api/v1",
+		Model:        "openrouter/google/gemma-4-31b-it",
+		Report:       true,
 	})
 	req := auditaReqForTest(t, true)
 	_, err := runner.Run(context.Background(), req)
@@ -256,16 +291,14 @@ func TestSubprocessRunnerSubprocessFailureAddsStderrDescriptorHint(t *testing.T)
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))

-	llmConcurrency := 1
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:         writeAuditaHelperWrapper(t),
-		Timeout:        mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv:   "OPENAI_KEY_SOURCE",
-		Modules:        []string{"glossary"},
-		BaseURL:        "https://openrouter.ai/api/v1",
-		Model:          "openrouter/google/gemma-4-31b-it",
-		LLMConcurrency: &llmConcurrency,
-		Report:         true,
+		Binary:       writeAuditaHelperWrapper(t),
+		Timeout:      mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
+		Modules:      []string{"glossary"},
+		BaseURL:      "https://openrouter.ai/api/v1",
+		Model:        "openrouter/google/gemma-4-31b-it",
+		Report:       true,
 	})
 	req := auditaReqForTest(t, true)
 	_, err := runner.Run(context.Background(), req)
@@ -286,16 +319,14 @@ func TestSubprocessRunnerMissingOutputFails(t *testing.T) {
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))

-	llmConcurrency := 1
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:         writeAuditaHelperWrapper(t),
-		Timeout:        mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv:   "OPENAI_KEY_SOURCE",
-		Modules:        []string{"glossary"},
-		BaseURL:        "https://openrouter.ai/api/v1",
-		Model:          "openrouter/google/gemma-4-31b-it",
-		LLMConcurrency: &llmConcurrency,
-		Report:         false,
+		Binary:       writeAuditaHelperWrapper(t),
+		Timeout:      mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
+		Modules:      []string{"glossary"},
+		BaseURL:      "https://openrouter.ai/api/v1",
+		Model:        "openrouter/google/gemma-4-31b-it",
+		Report:       false,
 	})
 	req := auditaReqForTest(t, false)
 	_, err := runner.Run(context.Background(), req)
@@ -316,16 +347,14 @@ func TestSubprocessRunnerInvalidOutputJSONFails(t *testing.T) {
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))

-	llmConcurrency := 1
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:         writeAuditaHelperWrapper(t),
-		Timeout:        mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv:   "OPENAI_KEY_SOURCE",
-		Modules:        []string{"glossary"},
-		BaseURL:        "https://openrouter.ai/api/v1",
-		Model:          "openrouter/google/gemma-4-31b-it",
-		LLMConcurrency: &llmConcurrency,
-		Report:         false,
+		Binary:       writeAuditaHelperWrapper(t),
+		Timeout:      mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
+		Modules:      []string{"glossary"},
+		BaseURL:      "https://openrouter.ai/api/v1",
+		Model:        "openrouter/google/gemma-4-31b-it",
+		Report:       false,
 	})
 	req := auditaReqForTest(t, false)
 	_, err := runner.Run(context.Background(), req)
@@ -346,16 +375,14 @@ func TestSubprocessRunnerSegmentsMissingFails(t *testing.T) {
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))

-	llmConcurrency := 1
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:         writeAuditaHelperWrapper(t),
-		Timeout:        mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv:   "OPENAI_KEY_SOURCE",
-		Modules:        []string{"glossary"},
-		BaseURL:        "https://openrouter.ai/api/v1",
-		Model:          "openrouter/google/gemma-4-31b-it",
-		LLMConcurrency: &llmConcurrency,
-		Report:         false,
+		Binary:       writeAuditaHelperWrapper(t),
+		Timeout:      mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
+		Modules:      []string{"glossary"},
+		BaseURL:      "https://openrouter.ai/api/v1",
+		Model:        "openrouter/google/gemma-4-31b-it",
+		Report:       false,
 	})
 	req := auditaReqForTest(t, false)
 	_, err := runner.Run(context.Background(), req)
@@ -376,16 +403,14 @@ func TestSubprocessRunnerInvalidReportJSONFails(t *testing.T) {
 	t.Setenv("OPENAI_KEY_SOURCE", "super-secret")
 	t.Setenv("AUDITA_HELPER_RECORD_PATH", filepath.Join(t.TempDir(), "record.json"))

-	llmConcurrency := 1
 	runner := mustAuditaRunner(t, SubprocessRunnerConfig{
-		Binary:         writeAuditaHelperWrapper(t),
-		Timeout:        mustParseAuditaDuration(t, "2s"),
-		LLMAPIKeyEnv:   "OPENAI_KEY_SOURCE",
-		Modules:        []string{"glossary"},
-		BaseURL:        "https://openrouter.ai/api/v1",
-		Model:          "openrouter/google/gemma-4-31b-it",
-		LLMConcurrency: &llmConcurrency,
-		Report:         true,
+		Binary:       writeAuditaHelperWrapper(t),
+		Timeout:      mustParseAuditaDuration(t, "2s"),
+		LLMAPIKeyEnv: "OPENAI_KEY_SOURCE",
+		Modules:      []string{"glossary"},
+		BaseURL:      "https://openrouter.ai/api/v1",
+		Model:        "openrouter/google/gemma-4-31b-it",
+		Report:       true,
 	})
 	req := auditaReqForTest(t, true)
 	_, err := runner.Run(context.Background(), req)
@@ -398,11 +423,11 @@ func TestSubprocessRunnerInvalidReportJSONFails(t *testing.T) {
 }

 func TestSubprocessRunnerConstructorValidation(t *testing.T) {
-	_, err := NewSubprocessRunnerFromConfigValues("", "3h", "AUDITA_LLM_API_KEY", []string{"glossary"}, "https://openrouter.ai/api/v1", "openrouter/google/gemma-4-31b-it", nil, "", nil, true)
+	_, err := NewSubprocessRunnerFromConfigValues("", "3h", "AUDITA_LLM_API_KEY", []string{"glossary"}, "https://openrouter.ai/api/v1", "openrouter/google/gemma-4-31b-it", "", "", "", "", nil, nil, "", nil, true)
 	if err == nil {
 		t.Fatal("expected binary validation error")
 	}
-	_, err = NewSubprocessRunnerFromConfigValues("audita", "bad", "AUDITA_LLM_API_KEY", []string{"glossary"}, "https://openrouter.ai/api/v1", "openrouter/google/gemma-4-31b-it", nil, "", nil, true)
+	_, err = NewSubprocessRunnerFromConfigValues("audita", "bad", "AUDITA_LLM_API_KEY", []string{"glossary"}, "https://openrouter.ai/api/v1", "openrouter/google/gemma-4-31b-it", "", "", "", "", nil, nil, "", nil, true)
 	if err == nil {
 		t.Fatal("expected timeout parse error")
 	}
--- a/internal/app/commands_test.go
+++ b/internal/app/commands_test.go
@@ -12,6 +12,7 @@ import (
 	"testing"
 	"time"

+	"gitea.maximumdirect.net/eric/narratio/internal/config"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )

@@ -63,12 +64,13 @@ func TestExecuteMissingRequiredFlags(t *testing.T) {
 		args []string
 		want string
 	}{
-		{name: "run missing flags", args: []string{"run"}, want: "run: --config and --session are required"},
-		{name: "plan missing flags", args: []string{"plan"}, want: "plan: --config and --session are required"},
+		{name: "run missing flags", args: []string{"run"}, want: "run: --session is required"},
+		{name: "plan missing flags", args: []string{"plan"}, want: "plan: --session is required"},
 		{name: "status missing flags", args: []string{"status"}, want: "status: --manifest is required"},
-		{name: "resume missing flags", args: []string{"resume"}, want: "resume: --config and --session are required"},
+		{name: "resume missing flags", args: []string{"resume"}, want: "resume: --session is required"},
 		{name: "run-stage missing name", args: []string{"run-stage", "--config", "a", "--session", "b"}, want: "run-stage: expected exactly one stage name"},
-		{name: "run-stage missing config flags", args: []string{"run-stage", "polish"}, want: "run-stage: --config and --session are required"},
+		{name: "run-stage missing config flags", args: []string{"run-stage", "polish"}, want: "run-stage: --session is required"},
+		{name: "run missing config uses defaults", args: []string{"run", "--session", "session.yml"}, want: "run: no pipeline config path provided and no default pipeline config found; searched:"},
 	}

 	for _, tc := range cases {
@@ -168,6 +170,157 @@ func TestExecuteRunStageTranscribeUsesConfiguredWhisperXServer(t *testing.T) {
 	}
 }

+func TestExecuteRunStagePolishLoadsCredentialFromSecretsDir(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	configDir := t.TempDir()
+	sessionID := "2026-05-03"
+	secretsDir := filepath.Join(configDir, "secrets")
+	if err := os.MkdirAll(secretsDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll(%q): %v", secretsDir, err)
+	}
+	if err := os.WriteFile(filepath.Join(secretsDir, "OPENROUTER_API_KEY"), []byte("from-secret-file\n"), 0o600); err != nil {
+		t.Fatalf("write OPENROUTER_API_KEY secret file: %v", err)
+	}
+
+	seriatimBinary := writeSeriatimAppTestWrapper(t)
+	auditaBinary := writeAuditaAppTestWrapper(t)
+	t.Setenv("GO_WANT_APP_SERIATIM_HELPER", "1")
+	t.Setenv("GO_WANT_APP_AUDITA_HELPER", "1")
+
+	pipelinePath := filepath.Join(configDir, "pipeline.yml")
+	sessionPath := filepath.Join(configDir, "session.yml")
+	pipelineYAML := `workspace:
+  root: ` + workspaceRoot + `
+storage:
+  backend: local
+secrets:
+  env_dir: ./secrets
+whisperx:
+  transcribe_url: https://example.com/transcribe
+seriatim:
+  binary: ` + seriatimBinary + `
+audita:
+  binary: ` + auditaBinary + `
+  llm_api_key_env: OPENROUTER_API_KEY
+analyzer:
+  timeout: 20m
+notification:
+  timeout: 10s
+`
+	sessionYAML := `session_id: ` + sessionID + `
+inputs:
+  audio_dir: ./audio
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+`
+	if err := os.WriteFile(pipelinePath, []byte(pipelineYAML), 0o644); err != nil {
+		t.Fatalf("write pipeline.yml: %v", err)
+	}
+	if err := os.WriteFile(sessionPath, []byte(sessionYAML), 0o644); err != nil {
+		t.Fatalf("write session.yml: %v", err)
+	}
+
+	originalWD, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("Getwd(): %v", err)
+	}
+	if err := os.Chdir(configDir); err != nil {
+		t.Fatalf("Chdir(%q): %v", configDir, err)
+	}
+	t.Cleanup(func() {
+		_ = os.Chdir(originalWD)
+	})
+
+	workRoot := filepath.Join(workspaceRoot, "work", sessionID)
+	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "merged.json"), `{"schema":"seriatim-intermediate","segments":[]}`)
+	mustWriteTestFile(t, filepath.Join(workRoot, "inputs", "glossary.yml"), "[]\n")
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"run-stage", "--config", pipelinePath, "--session", sessionPath, "--force", "polish"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "stage=polish executed=1 skipped=0") {
+		t.Fatalf("stdout = %q, want polish execution", stdout.String())
+	}
+}
+
+func TestExecuteRunFailsWhenConfiguredSecretsDirMissing(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	configDir := t.TempDir()
+	pipelinePath := filepath.Join(configDir, "pipeline.yml")
+	sessionPath := filepath.Join(configDir, "session.yml")
+
+	pipelineYAML := `workspace:
+  root: ` + workspaceRoot + `
+storage:
+  backend: local
+secrets:
+  env_dir: ./missing-secrets
+whisperx:
+  transcribe_url: https://example.com/transcribe
+seriatim:
+  binary: seriatim
+audita:
+  binary: audita
+analyzer:
+  timeout: 20m
+notification:
+  timeout: 10s
+`
+	sessionYAML := `session_id: 2026-05-03
+inputs:
+  audio_dir: ./audio
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+`
+	if err := os.WriteFile(pipelinePath, []byte(pipelineYAML), 0o644); err != nil {
+		t.Fatalf("write pipeline.yml: %v", err)
+	}
+	if err := os.WriteFile(sessionPath, []byte(sessionYAML), 0o644); err != nil {
+		t.Fatalf("write session.yml: %v", err)
+	}
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"run", "--config", pipelinePath, "--session", sessionPath}, &stdout, &stderr)
+	if code == 0 {
+		t.Fatal("exit code = 0, want non-zero")
+	}
+	if !strings.Contains(stderr.String(), "read secrets env_dir") {
+		t.Fatalf("stderr = %q, want secrets read-dir error context", stderr.String())
+	}
+}
+
+func TestExecuteUsesDefaultPipelineConfigPathWhenConfigFlagOmitted(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"source":"default-config-test","segments":[{"speaker":"alice"}]}`))
+	}))
+	defer srv.Close()
+
+	pipelinePath, sessionPath := writeValidConfigFiles(t, workspaceRoot, srv.URL)
+	originalDefaults := append([]string(nil), config.DefaultPipelineConfigSearchPaths...)
+	config.DefaultPipelineConfigSearchPaths = []string{pipelinePath}
+	defer func() {
+		config.DefaultPipelineConfigSearchPaths = originalDefaults
+	}()
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{"run", "--session", sessionPath}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "narratio run: session 2026-05-03; executed=9 skipped=0; manifest=") {
+		t.Fatalf("stdout = %q, want successful run output", stdout.String())
+	}
+}
+
 func TestExecuteInvalidCommand(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
--- a/internal/app/pipeline_config_path.go
+++ b/internal/app/pipeline_config_path.go
@@ -0,0 +1,49 @@
+package app
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+func resolvePipelineConfigPath(flagValue string) (string, error) {
+	return resolvePipelineConfigPathWithCandidates(flagValue, config.DefaultPipelineConfigSearchPaths)
+}
+
+func resolvePipelineConfigPathWithCandidates(flagValue string, candidates []string) (string, error) {
+	if explicit := strings.TrimSpace(flagValue); explicit != "" {
+		return explicit, nil
+	}
+
+	ordered := make([]string, 0, len(candidates))
+	for _, raw := range candidates {
+		path := strings.TrimSpace(raw)
+		if path == "" {
+			continue
+		}
+		ordered = append(ordered, path)
+		info, err := os.Stat(path)
+		if err == nil {
+			if info.IsDir() {
+				continue
+			}
+			return filepath.Clean(path), nil
+		}
+		if errors.Is(err, os.ErrNotExist) {
+			continue
+		}
+		return "", fmt.Errorf("check default pipeline config %q: %w", path, err)
+	}
+
+	if len(ordered) == 0 {
+		return "", fmt.Errorf("no pipeline config path provided and no default locations configured")
+	}
+	return "", fmt.Errorf(
+		"no pipeline config path provided and no default pipeline config found; searched: %s",
+		strings.Join(ordered, ", "),
+	)
+}
--- a/internal/app/pipeline_config_path_test.go
+++ b/internal/app/pipeline_config_path_test.go
@@ -0,0 +1,65 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestResolvePipelineConfigPathWithCandidatesExplicitWins(t *testing.T) {
+	got, err := resolvePipelineConfigPathWithCandidates("  ./custom/pipeline.yml  ", []string{"/a", "/b"})
+	if err != nil {
+		t.Fatalf("resolvePipelineConfigPathWithCandidates() error = %v", err)
+	}
+	if got != "./custom/pipeline.yml" {
+		t.Fatalf("resolved path = %q, want explicit path", got)
+	}
+}
+
+func TestResolvePipelineConfigPathWithCandidatesUsesFirstExisting(t *testing.T) {
+	dir := t.TempDir()
+	first := filepath.Join(dir, "first.yml")
+	second := filepath.Join(dir, "second.yml")
+	if err := os.WriteFile(second, []byte("workspace:\n  root: ./tmp\n"), 0o644); err != nil {
+		t.Fatalf("write second default: %v", err)
+	}
+
+	got, err := resolvePipelineConfigPathWithCandidates("", []string{first, second})
+	if err != nil {
+		t.Fatalf("resolvePipelineConfigPathWithCandidates() error = %v", err)
+	}
+	if got != filepath.Clean(second) {
+		t.Fatalf("resolved path = %q, want %q", got, filepath.Clean(second))
+	}
+}
+
+func TestResolvePipelineConfigPathWithCandidatesPrecedence(t *testing.T) {
+	dir := t.TempDir()
+	first := filepath.Join(dir, "first.yml")
+	second := filepath.Join(dir, "second.yml")
+	if err := os.WriteFile(first, []byte("workspace:\n  root: ./tmp\n"), 0o644); err != nil {
+		t.Fatalf("write first default: %v", err)
+	}
+	if err := os.WriteFile(second, []byte("workspace:\n  root: ./tmp\n"), 0o644); err != nil {
+		t.Fatalf("write second default: %v", err)
+	}
+
+	got, err := resolvePipelineConfigPathWithCandidates("", []string{first, second})
+	if err != nil {
+		t.Fatalf("resolvePipelineConfigPathWithCandidates() error = %v", err)
+	}
+	if got != filepath.Clean(first) {
+		t.Fatalf("resolved path = %q, want first candidate %q", got, filepath.Clean(first))
+	}
+}
+
+func TestResolvePipelineConfigPathWithCandidatesMissing(t *testing.T) {
+	_, err := resolvePipelineConfigPathWithCandidates("", []string{"/does/not/exist/one.yml", "/does/not/exist/two.yml"})
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "no default pipeline config found") {
+		t.Fatalf("error = %q, want missing-defaults context", err.Error())
+	}
+}
--- a/internal/app/plan.go
+++ b/internal/app/plan.go
@@ -5,9 +5,12 @@ import (
 	"flag"
 	"fmt"
 	"io"
+	"log/slog"
+	"os"

 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/logging"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )

@@ -19,7 +22,7 @@ func Plan(ctx context.Context, args []string, out io.Writer) error {
 	var pipelinePath string
 	var sessionPath string
 	var force bool
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml")
+	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
 	fs.StringVar(&sessionPath, "session", "", "path to session.yml")
 	fs.BoolVar(&force, "force", false, "force stage execution (reserved for future behavior)")

@@ -29,17 +32,25 @@ func Plan(ctx context.Context, args []string, out io.Writer) error {
 	if fs.NArg() != 0 {
 		return fmt.Errorf("plan: unexpected positional arguments")
 	}
-	if pipelinePath == "" || sessionPath == "" {
-		return fmt.Errorf("plan: --config and --session are required")
+	if sessionPath == "" {
+		return fmt.Errorf("plan: --session is required")
 	}

-	cfg, err := config.Load(pipelinePath, sessionPath)
+	resolvedPipelinePath, err := resolvePipelineConfigPath(pipelinePath)
+	if err != nil {
+		return fmt.Errorf("plan: %w", err)
+	}
+
+	cfg, err := config.Load(resolvedPipelinePath, sessionPath)
 	if err != nil {
 		return fmt.Errorf("plan: %w", err)
 	}
 	if err := config.Validate(cfg); err != nil {
 		return fmt.Errorf("plan: %w", err)
 	}
+	if _, err := loadSecretsFromConfig(cfg, logging.NewLogger(os.Stderr, slog.LevelInfo)); err != nil {
+		return fmt.Errorf("plan: %w", err)
+	}

 	store := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root)
 	paths, err := store.EnsureLayout(cfg.Session.SessionID)
--- a/internal/app/plan_test.go
+++ b/internal/app/plan_test.go
@@ -89,6 +89,53 @@ func TestPlanShowsRunAndSkipFromManifest(t *testing.T) {
 	}
 }

+func TestPlanFailsWhenConfiguredSecretsDirMissing(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	configDir := t.TempDir()
+	pipelinePath := filepath.Join(configDir, "pipeline.yml")
+	sessionPath := filepath.Join(configDir, "session.yml")
+
+	pipelineYAML := `workspace:
+  root: ` + workspaceRoot + `
+storage:
+  backend: local
+secrets:
+  env_dir: ./missing-secrets
+whisperx:
+  transcribe_url: https://example.com/transcribe
+seriatim:
+  binary: seriatim
+audita:
+  binary: audita
+analyzer:
+  timeout: 20m
+notification:
+  timeout: 10s
+`
+	sessionYAML := `session_id: 2026-05-03
+inputs:
+  audio_dir: ./audio
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+`
+	if err := os.WriteFile(pipelinePath, []byte(pipelineYAML), 0o644); err != nil {
+		t.Fatalf("write pipeline.yml: %v", err)
+	}
+	if err := os.WriteFile(sessionPath, []byte(sessionYAML), 0o644); err != nil {
+		t.Fatalf("write session.yml: %v", err)
+	}
+
+	var out bytes.Buffer
+	err := Plan(context.Background(), []string{"--config", pipelinePath, "--session", sessionPath}, &out)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "read secrets env_dir") {
+		t.Fatalf("error = %q, want secrets read error context", err.Error())
+	}
+}
+
 func assertDir(t *testing.T, path string) {
 	t.Helper()
 	info, err := os.Stat(path)
--- a/internal/app/resume.go
+++ b/internal/app/resume.go
@@ -18,7 +18,7 @@ func Resume(ctx context.Context, args []string, out io.Writer) error {
 	var pipelinePath string
 	var sessionPath string
 	var force bool
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml")
+	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
 	fs.StringVar(&sessionPath, "session", "", "path to session.yml")
 	fs.BoolVar(&force, "force", false, "force stage execution")

@@ -28,11 +28,16 @@ func Resume(ctx context.Context, args []string, out io.Writer) error {
 	if fs.NArg() != 0 {
 		return fmt.Errorf("resume: unexpected positional arguments")
 	}
-	if pipelinePath == "" || sessionPath == "" {
-		return fmt.Errorf("resume: --config and --session are required")
+	if sessionPath == "" {
+		return fmt.Errorf("resume: --session is required")
 	}

-	cfg, err := config.Load(pipelinePath, sessionPath)
+	resolvedPipelinePath, err := resolvePipelineConfigPath(pipelinePath)
+	if err != nil {
+		return fmt.Errorf("resume: %w", err)
+	}
+
+	cfg, err := config.Load(resolvedPipelinePath, sessionPath)
 	if err != nil {
 		return fmt.Errorf("resume: %w", err)
 	}
--- a/internal/app/run.go
+++ b/internal/app/run.go
@@ -17,7 +17,7 @@ func Run(ctx context.Context, args []string, out io.Writer) error {
 	var pipelinePath string
 	var sessionPath string
 	var force bool
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml")
+	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
 	fs.StringVar(&sessionPath, "session", "", "path to session.yml")
 	fs.BoolVar(&force, "force", false, "force stage execution (reserved for future behavior)")

@@ -27,11 +27,16 @@ func Run(ctx context.Context, args []string, out io.Writer) error {
 	if fs.NArg() != 0 {
 		return fmt.Errorf("run: unexpected positional arguments")
 	}
-	if pipelinePath == "" || sessionPath == "" {
-		return fmt.Errorf("run: --config and --session are required")
+	if sessionPath == "" {
+		return fmt.Errorf("run: --session is required")
 	}

-	cfg, err := config.Load(pipelinePath, sessionPath)
+	resolvedPipelinePath, err := resolvePipelineConfigPath(pipelinePath)
+	if err != nil {
+		return fmt.Errorf("run: %w", err)
+	}
+
+	cfg, err := config.Load(resolvedPipelinePath, sessionPath)
 	if err != nil {
 		return fmt.Errorf("run: %w", err)
 	}
--- a/internal/app/run_stage.go
+++ b/internal/app/run_stage.go
@@ -17,7 +17,7 @@ func RunStage(ctx context.Context, args []string, out io.Writer) error {
 	var pipelinePath string
 	var sessionPath string
 	var force bool
-	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml")
+	fs.StringVar(&pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
 	fs.StringVar(&sessionPath, "session", "", "path to session.yml")
 	fs.BoolVar(&force, "force", false, "force stage execution (reserved for future behavior)")

@@ -27,8 +27,8 @@ func RunStage(ctx context.Context, args []string, out io.Writer) error {
 	if fs.NArg() != 1 {
 		return fmt.Errorf("run-stage: expected exactly one stage name")
 	}
-	if pipelinePath == "" || sessionPath == "" {
-		return fmt.Errorf("run-stage: --config and --session are required")
+	if sessionPath == "" {
+		return fmt.Errorf("run-stage: --session is required")
 	}

 	stageName := fs.Arg(0)
@@ -37,7 +37,12 @@ func RunStage(ctx context.Context, args []string, out io.Writer) error {
 		return fmt.Errorf("run-stage: %w", err)
 	}

-	cfg, err := config.Load(pipelinePath, sessionPath)
+	resolvedPipelinePath, err := resolvePipelineConfigPath(pipelinePath)
+	if err != nil {
+		return fmt.Errorf("run-stage: %w", err)
+	}
+
+	cfg, err := config.Load(resolvedPipelinePath, sessionPath)
 	if err != nil {
 		return fmt.Errorf("run-stage: %w", err)
 	}
--- a/internal/app/runner.go
+++ b/internal/app/runner.go
@@ -51,6 +51,9 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
 	if env.Logger == nil {
 		env.Logger = logging.NewLogger(os.Stderr, slog.LevelInfo)
 	}
+	if _, err := loadSecretsFromConfig(env.Config, env.Logger); err != nil {
+		return nil, fmt.Errorf("load secrets from files: %w", err)
+	}
 	if env.WhisperX == nil {
 		client, err := buildDefaultWhisperXClient(env.Config)
 		if err != nil {
@@ -227,7 +230,7 @@ func buildDefaultAuditaRunner(cfg *config.Config) (audita.Runner, error) {
 	}

 	a := cfg.Pipeline.Audita
-	if strings.TrimSpace(a.Binary) == "" || strings.TrimSpace(a.Timeout) == "" || len(a.Modules) == 0 || strings.TrimSpace(a.BaseURL) == "" || strings.TrimSpace(a.Model) == "" {
+	if strings.TrimSpace(a.Binary) == "" || strings.TrimSpace(a.Timeout) == "" || strings.TrimSpace(a.BaseURL) == "" || strings.TrimSpace(a.Model) == "" {
 		// Compatibility fallback for tests or internal call paths that bypass config validation/defaults.
 		return &audita.NoopRunner{}, nil
 	}
@@ -244,7 +247,12 @@ func buildDefaultAuditaRunner(cfg *config.Config) (audita.Runner, error) {
 		append([]string(nil), a.Modules...),
 		a.BaseURL,
 		a.Model,
-		a.LLMConcurrency,
+		a.TranscriptDescription,
+		a.ConfigPath,
+		a.OutputSchema,
+		a.WorkDirRetention,
+		a.TotalLLMConcurrency,
+		a.ProposalLLMConcurrency,
 		a.ValidationModel,
 		a.ValidationLLMConcurrency,
 		report,
--- a/internal/app/secrets_env.go
+++ b/internal/app/secrets_env.go
@@ -0,0 +1,88 @@
+package app
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+var envVarNamePattern = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
+
+type secretsLoadStats struct {
+	Dir               string
+	Loaded            int
+	PreservedExisting int
+	Skipped           int
+}
+
+func loadSecretsFromConfig(cfg *config.Config, logger *slog.Logger) (*secretsLoadStats, error) {
+	if cfg == nil || cfg.Pipeline == nil || cfg.Pipeline.Secrets == nil {
+		return nil, nil
+	}
+
+	rawDir := strings.TrimSpace(cfg.Pipeline.Secrets.EnvDir)
+	if rawDir == "" {
+		return nil, nil
+	}
+
+	resolvedDir := rawDir
+	if !filepath.IsAbs(resolvedDir) {
+		cwd, err := os.Getwd()
+		if err != nil {
+			return nil, fmt.Errorf("resolve secrets env_dir %q from current working directory: %w", rawDir, err)
+		}
+		resolvedDir = filepath.Join(cwd, resolvedDir)
+	}
+	resolvedDir = filepath.Clean(resolvedDir)
+
+	entries, err := os.ReadDir(resolvedDir)
+	if err != nil {
+		return nil, fmt.Errorf("read secrets env_dir %q: %w", resolvedDir, err)
+	}
+
+	stats := &secretsLoadStats{Dir: resolvedDir}
+	for _, entry := range entries {
+		name := entry.Name()
+		if !envVarNamePattern.MatchString(name) {
+			stats.Skipped++
+			continue
+		}
+		if entry.IsDir() {
+			stats.Skipped++
+			continue
+		}
+
+		secretPath := filepath.Join(resolvedDir, name)
+		bytes, err := os.ReadFile(secretPath)
+		if err != nil {
+			return nil, fmt.Errorf("read secret file %q: %w", secretPath, err)
+		}
+		value := strings.TrimRight(string(bytes), "\r\n")
+
+		if _, exists := os.LookupEnv(name); exists {
+			stats.PreservedExisting++
+			continue
+		}
+		if err := os.Setenv(name, value); err != nil {
+			return nil, fmt.Errorf("set environment variable %q from %q: %w", name, secretPath, err)
+		}
+		stats.Loaded++
+	}
+
+	if logger != nil {
+		logger.Info(
+			"loaded secret environment variables from filesystem",
+			"secrets_env_dir", stats.Dir,
+			"loaded", stats.Loaded,
+			"preserved_existing", stats.PreservedExisting,
+			"skipped", stats.Skipped,
+		)
+	}
+
+	return stats, nil
+}
--- a/internal/app/secrets_env_test.go
+++ b/internal/app/secrets_env_test.go
@@ -0,0 +1,155 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+func TestLoadSecretsFromConfigLoadsValidFiles(t *testing.T) {
+	dir := t.TempDir()
+	mustWriteSecretFile(t, filepath.Join(dir, "NARRATIO_TEST_SECRET_A"), "value-1\n")
+	mustWriteSecretFile(t, filepath.Join(dir, "NARRATIO_TEST_SECRET_B"), "value-2\r\n")
+	mustWriteSecretFile(t, filepath.Join(dir, "not-valid-name.txt"), "ignored")
+
+	cfg := &config.Config{
+		Pipeline: &config.PipelineConfig{
+			Secrets: &config.SecretsConfig{EnvDir: dir},
+		},
+	}
+
+	stats, err := loadSecretsFromConfig(cfg, nil)
+	if err != nil {
+		t.Fatalf("loadSecretsFromConfig() error = %v", err)
+	}
+	if stats == nil {
+		t.Fatal("stats = nil, want non-nil")
+	}
+	if stats.Loaded != 2 {
+		t.Fatalf("Loaded = %d, want 2", stats.Loaded)
+	}
+	if stats.PreservedExisting != 0 {
+		t.Fatalf("PreservedExisting = %d, want 0", stats.PreservedExisting)
+	}
+	if stats.Skipped == 0 {
+		t.Fatalf("Skipped = %d, want > 0 for invalid filename", stats.Skipped)
+	}
+	if got := os.Getenv("NARRATIO_TEST_SECRET_A"); got != "value-1" {
+		t.Fatalf("NARRATIO_TEST_SECRET_A = %q, want value-1", got)
+	}
+	if got := os.Getenv("NARRATIO_TEST_SECRET_B"); got != "value-2" {
+		t.Fatalf("NARRATIO_TEST_SECRET_B = %q, want value-2", got)
+	}
+}
+
+func TestLoadSecretsFromConfigPreservesExistingEnv(t *testing.T) {
+	t.Setenv("OBJECT_STORAGE_KEY", "existing")
+
+	dir := t.TempDir()
+	mustWriteSecretFile(t, filepath.Join(dir, "OBJECT_STORAGE_KEY"), "from-file\n")
+
+	cfg := &config.Config{
+		Pipeline: &config.PipelineConfig{
+			Secrets: &config.SecretsConfig{EnvDir: dir},
+		},
+	}
+
+	stats, err := loadSecretsFromConfig(cfg, nil)
+	if err != nil {
+		t.Fatalf("loadSecretsFromConfig() error = %v", err)
+	}
+	if stats.PreservedExisting != 1 {
+		t.Fatalf("PreservedExisting = %d, want 1", stats.PreservedExisting)
+	}
+	if got := os.Getenv("OBJECT_STORAGE_KEY"); got != "existing" {
+		t.Fatalf("OBJECT_STORAGE_KEY = %q, want existing", got)
+	}
+}
+
+func TestLoadSecretsFromConfigRelativeDirUsesCWD(t *testing.T) {
+	cwd := t.TempDir()
+	secretsDir := filepath.Join(cwd, "secrets")
+	if err := os.MkdirAll(secretsDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll(%q): %v", secretsDir, err)
+	}
+	mustWriteSecretFile(t, filepath.Join(secretsDir, "OBJECT_STORAGE_KEY_ID"), "id-123\n")
+
+	originalWD, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("Getwd(): %v", err)
+	}
+	if err := os.Chdir(cwd); err != nil {
+		t.Fatalf("Chdir(%q): %v", cwd, err)
+	}
+	t.Cleanup(func() {
+		_ = os.Chdir(originalWD)
+	})
+
+	cfg := &config.Config{
+		Pipeline: &config.PipelineConfig{
+			Secrets: &config.SecretsConfig{EnvDir: "./secrets"},
+		},
+	}
+	if _, err := loadSecretsFromConfig(cfg, nil); err != nil {
+		t.Fatalf("loadSecretsFromConfig() error = %v", err)
+	}
+	if got := os.Getenv("OBJECT_STORAGE_KEY_ID"); got != "id-123" {
+		t.Fatalf("OBJECT_STORAGE_KEY_ID = %q, want id-123", got)
+	}
+}
+
+func TestLoadSecretsFromConfigMissingDirFails(t *testing.T) {
+	cfg := &config.Config{
+		Pipeline: &config.PipelineConfig{
+			Secrets: &config.SecretsConfig{EnvDir: filepath.Join(t.TempDir(), "missing")},
+		},
+	}
+
+	_, err := loadSecretsFromConfig(cfg, nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "read secrets env_dir") {
+		t.Fatalf("error = %q, want read-dir context", err.Error())
+	}
+}
+
+func TestLoadSecretsFromConfigUnreadableValidEntryFails(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("symlink behavior differs on windows")
+	}
+
+	dir := t.TempDir()
+	broken := filepath.Join(dir, "OPENROUTER_API_KEY")
+	if err := os.Symlink(filepath.Join(dir, "does-not-exist"), broken); err != nil {
+		t.Fatalf("Symlink(%q): %v", broken, err)
+	}
+
+	cfg := &config.Config{
+		Pipeline: &config.PipelineConfig{
+			Secrets: &config.SecretsConfig{EnvDir: dir},
+		},
+	}
+
+	_, err := loadSecretsFromConfig(cfg, nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "read secret file") {
+		t.Fatalf("error = %q, want read secret file context", err.Error())
+	}
+}
+
+func mustWriteSecretFile(t *testing.T, path, contents string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("MkdirAll(%q): %v", path, err)
+	}
+	if err := os.WriteFile(path, []byte(contents), 0o600); err != nil {
+		t.Fatalf("WriteFile(%q): %v", path, err)
+	}
+}
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -12,6 +12,7 @@ type Config struct {
 type PipelineConfig struct {
 	Workspace    WorkspaceConfig    `yaml:"workspace"`
 	Storage      StorageConfig      `yaml:"storage"`
+	Secrets      *SecretsConfig     `yaml:"secrets"`
 	WhisperX     WhisperXConfig     `yaml:"whisperx"`
 	Seriatim     SeriatimConfig     `yaml:"seriatim"`
 	Audita       AuditaConfig       `yaml:"audita"`
@@ -36,6 +37,11 @@ type WorkspaceConfig struct {
 	Root string `yaml:"root"`
 }

+// SecretsConfig configures optional local filesystem secret loading.
+type SecretsConfig struct {
+	EnvDir string `yaml:"env_dir"`
+}
+
 // StorageConfig configures storage backends and related parameters.
 type StorageConfig struct {
 	Backend string `yaml:"backend"`
@@ -79,9 +85,14 @@ type AuditaConfig struct {
 	Modules                  []string `yaml:"modules"`
 	BaseURL                  string   `yaml:"base_url"`
 	Model                    string   `yaml:"model"`
-	LLMConcurrency           *int     `yaml:"llm_concurrency"`
+	TotalLLMConcurrency      *int     `yaml:"total_llm_concurrency"`
+	ProposalLLMConcurrency   *int     `yaml:"proposal_llm_concurrency"`
 	ValidationModel          string   `yaml:"validation_model"`
 	ValidationLLMConcurrency *int     `yaml:"validation_llm_concurrency"`
+	TranscriptDescription    string   `yaml:"transcript_description"`
+	ConfigPath               string   `yaml:"config_path"`
+	OutputSchema             string   `yaml:"output_schema"`
+	WorkDirRetention         string   `yaml:"work_dir_retention"`
 	Report                   *bool    `yaml:"report"`
 }

--- a/internal/config/defaults.go
+++ b/internal/config/defaults.go
@@ -0,0 +1,18 @@
+package config
+
+// Default filesystem locations for pipeline configuration lookup when --config
+// is omitted. Order is highest to lowest precedence.
+const (
+	DefaultPipelineConfigPathUsrLocal = "/usr/local/etc/narratio/pipeline.yml"
+	DefaultPipelineConfigPathEtc      = "/etc/narratio/pipeline.yml"
+)
+
+// DefaultPipelineConfigSearchPaths defines the default search order for
+// pipeline.yml when callers do not provide an explicit path.
+//
+// Keep this in a variable so future defaults can be extended without changing
+// call sites.
+var DefaultPipelineConfigSearchPaths = []string{
+	DefaultPipelineConfigPathUsrLocal,
+	DefaultPipelineConfigPathEtc,
+}
--- a/internal/config/load.go
+++ b/internal/config/load.go
@@ -143,29 +143,12 @@ func applyAuditaDefaults(cfg *AuditaConfig) {
 	if cfg.Timeout == "" {
 		cfg.Timeout = "3h"
 	}
-	if cfg.Modules == nil {
-		cfg.Modules = []string{
-			"glossary",
-			"homophones",
-			"glossary",
-			"spoken_word",
-			"grammar",
-			"homophones",
-			"glossary",
-		}
-	}
 	if cfg.BaseURL == "" {
 		cfg.BaseURL = "https://openrouter.ai/api/v1"
 	}
 	if cfg.Model == "" {
 		cfg.Model = "openrouter/google/gemma-4-31b-it"
 	}
-	if cfg.LLMConcurrency == nil {
-		cfg.LLMConcurrency = intPtr(1)
-	}
-	if cfg.ValidationLLMConcurrency == nil {
-		cfg.ValidationLLMConcurrency = intPtr(1)
-	}
 	if cfg.Report == nil {
 		cfg.Report = boolPtr(true)
 	}
--- a/internal/config/load_validate_test.go
+++ b/internal/config/load_validate_test.go
@@ -72,6 +72,46 @@ inputs:
 `,
 			wantLoadErr: "strict decode failed",
 		},
+		{
+			name: "unknown secrets field fails",
+			pipelineYAML: `workspace:
+  root: /tmp/narratio
+whisperx:
+  transcribe_url: https://transcription.ai.rakestrawhome.com/transcribe
+seriatim:
+  binary: seriatim
+secrets:
+  bogus: true
+`,
+			sessionYAML: `session_id: 2026-05-03
+inputs:
+  audio_dir: ./audio
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+`,
+			wantLoadErr: "strict decode failed",
+		},
+		{
+			name: "empty secrets env_dir fails",
+			pipelineYAML: `workspace:
+  root: /tmp/narratio
+whisperx:
+  transcribe_url: https://transcription.ai.rakestrawhome.com/transcribe
+seriatim:
+  binary: seriatim
+secrets:
+  env_dir: "   "
+`,
+			sessionYAML: `session_id: 2026-05-03
+inputs:
+  audio_dir: ./audio
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+`,
+			wantValidate: "pipeline config \"pipeline.yml\" invalid: pipeline.secrets.env_dir must be non-empty when pipeline.secrets is configured",
+		},
 		{
 			name: "unknown session field fails",
 			pipelineYAML: `workspace:
@@ -413,7 +453,7 @@ inputs:
 			wantValidate: "pipeline config \"pipeline.yml\" invalid: pipeline.audita.timeout must be a valid duration",
 		},
 		{
-			name: "empty audita modules fails",
+			name: "empty audita modules is valid override",
 			pipelineYAML: `workspace:
  root: /tmp/narratio
 whisperx:
@@ -431,7 +471,6 @@ inputs:
  autocorrect_file: ./autocorrect.yml
  glossary_file: ./glossary.yml
 `,
-			wantValidate: "pipeline config \"pipeline.yml\" invalid: pipeline.audita.modules must include at least one module",
 		},
 		{
 			name: "empty audita module item fails",
@@ -501,7 +540,7 @@ inputs:
 			wantValidate: "pipeline config \"pipeline.yml\" invalid: pipeline.audita.base_url must be a valid URL",
 		},
 		{
-			name: "invalid audita llm_concurrency fails",
+			name: "legacy audita llm_concurrency field fails strict decode",
 			pipelineYAML: `workspace:
  root: /tmp/narratio
 whisperx:
@@ -510,7 +549,7 @@ seriatim:
  binary: seriatim
 audita:
  binary: audita
-  llm_concurrency: 0
+  llm_concurrency: 1
 `,
 			sessionYAML: `session_id: 2026-05-03
 inputs:
@@ -519,7 +558,49 @@ inputs:
  autocorrect_file: ./autocorrect.yml
  glossary_file: ./glossary.yml
 `,
-			wantValidate: "pipeline config \"pipeline.yml\" invalid: pipeline.audita.llm_concurrency must be > 0",
+			wantLoadErr: "strict decode failed",
+		},
+		{
+			name: "invalid audita total_llm_concurrency fails",
+			pipelineYAML: `workspace:
+  root: /tmp/narratio
+whisperx:
+  transcribe_url: https://transcription.ai.rakestrawhome.com/transcribe
+seriatim:
+  binary: seriatim
+audita:
+  binary: audita
+  total_llm_concurrency: 0
+`,
+			sessionYAML: `session_id: 2026-05-03
+inputs:
+  audio_dir: ./audio
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+`,
+			wantValidate: "pipeline config \"pipeline.yml\" invalid: pipeline.audita.total_llm_concurrency must be > 0",
+		},
+		{
+			name: "invalid audita proposal_llm_concurrency fails",
+			pipelineYAML: `workspace:
+  root: /tmp/narratio
+whisperx:
+  transcribe_url: https://transcription.ai.rakestrawhome.com/transcribe
+seriatim:
+  binary: seriatim
+audita:
+  binary: audita
+  proposal_llm_concurrency: 0
+`,
+			sessionYAML: `session_id: 2026-05-03
+inputs:
+  audio_dir: ./audio
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+`,
+			wantValidate: "pipeline config \"pipeline.yml\" invalid: pipeline.audita.proposal_llm_concurrency must be > 0",
 		},
 		{
 			name: "invalid audita validation_llm_concurrency fails",
@@ -542,6 +623,48 @@ inputs:
 `,
 			wantValidate: "pipeline config \"pipeline.yml\" invalid: pipeline.audita.validation_llm_concurrency must be > 0",
 		},
+		{
+			name: "invalid audita output_schema fails",
+			pipelineYAML: `workspace:
+  root: /tmp/narratio
+whisperx:
+  transcribe_url: https://transcription.ai.rakestrawhome.com/transcribe
+seriatim:
+  binary: seriatim
+audita:
+  binary: audita
+  output_schema: bad
+`,
+			sessionYAML: `session_id: 2026-05-03
+inputs:
+  audio_dir: ./audio
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+`,
+			wantValidate: "pipeline config \"pipeline.yml\" invalid: pipeline.audita.output_schema must be one of: bare-segments, audita-v1",
+		},
+		{
+			name: "invalid audita work_dir_retention fails",
+			pipelineYAML: `workspace:
+  root: /tmp/narratio
+whisperx:
+  transcribe_url: https://transcription.ai.rakestrawhome.com/transcribe
+seriatim:
+  binary: seriatim
+audita:
+  binary: audita
+  work_dir_retention: sometimes
+`,
+			sessionYAML: `session_id: 2026-05-03
+inputs:
+  audio_dir: ./audio
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+`,
+			wantValidate: "pipeline config \"pipeline.yml\" invalid: pipeline.audita.work_dir_retention must be one of: always, auto, never",
+		},
 	}

 	for _, tt := range tests {
@@ -605,8 +728,8 @@ inputs:
 				if cfg.Pipeline.Audita.LLMAPIKeyEnv != "" {
 					t.Fatalf("audita.llm_api_key_env = %q, want empty by default", cfg.Pipeline.Audita.LLMAPIKeyEnv)
 				}
-				if got := strings.Join(cfg.Pipeline.Audita.Modules, ","); got != "glossary,homophones,glossary,spoken_word,grammar,homophones,glossary" {
-					t.Fatalf("audita.modules = %q, want default sequence", got)
+				if cfg.Pipeline.Audita.Modules != nil {
+					t.Fatalf("audita.modules = %#v, want nil default (optional override)", cfg.Pipeline.Audita.Modules)
 				}
 				if cfg.Pipeline.Audita.BaseURL != "https://openrouter.ai/api/v1" {
 					t.Fatalf("audita.base_url = %q, want %q", cfg.Pipeline.Audita.BaseURL, "https://openrouter.ai/api/v1")
@@ -614,14 +737,17 @@ inputs:
 				if cfg.Pipeline.Audita.Model != "openrouter/google/gemma-4-31b-it" {
 					t.Fatalf("audita.model = %q, want %q", cfg.Pipeline.Audita.Model, "openrouter/google/gemma-4-31b-it")
 				}
-				if cfg.Pipeline.Audita.LLMConcurrency == nil || *cfg.Pipeline.Audita.LLMConcurrency != 1 {
-					t.Fatalf("audita.llm_concurrency = %v, want 1", cfg.Pipeline.Audita.LLMConcurrency)
-				}
 				if cfg.Pipeline.Audita.ValidationModel != "" {
 					t.Fatalf("audita.validation_model = %q, want empty default", cfg.Pipeline.Audita.ValidationModel)
 				}
-				if cfg.Pipeline.Audita.ValidationLLMConcurrency == nil || *cfg.Pipeline.Audita.ValidationLLMConcurrency != 1 {
-					t.Fatalf("audita.validation_llm_concurrency = %v, want 1", cfg.Pipeline.Audita.ValidationLLMConcurrency)
+				if cfg.Pipeline.Audita.TotalLLMConcurrency != nil {
+					t.Fatalf("audita.total_llm_concurrency = %v, want nil default", cfg.Pipeline.Audita.TotalLLMConcurrency)
+				}
+				if cfg.Pipeline.Audita.ProposalLLMConcurrency != nil {
+					t.Fatalf("audita.proposal_llm_concurrency = %v, want nil default", cfg.Pipeline.Audita.ProposalLLMConcurrency)
+				}
+				if cfg.Pipeline.Audita.ValidationLLMConcurrency != nil {
+					t.Fatalf("audita.validation_llm_concurrency = %v, want nil default", cfg.Pipeline.Audita.ValidationLLMConcurrency)
 				}
 				if cfg.Pipeline.Audita.Report == nil || *cfg.Pipeline.Audita.Report != true {
 					t.Fatalf("audita.report = %v, want true", cfg.Pipeline.Audita.Report)
@@ -685,7 +811,8 @@ func TestValidateMissingAudioSource(t *testing.T) {
 				Modules:                  []string{"glossary", "homophones"},
 				BaseURL:                  "https://openrouter.ai/api/v1",
 				Model:                    "openrouter/google/gemma-4-31b-it",
-				LLMConcurrency:           intPtr(1),
+				TotalLLMConcurrency:      intPtr(1),
+				ProposalLLMConcurrency:   intPtr(1),
 				ValidationModel:          "",
 				ValidationLLMConcurrency: intPtr(1),
 				Report:                   boolPtr(true),
--- a/internal/config/validate.go
+++ b/internal/config/validate.go
@@ -33,6 +33,9 @@ func validatePipeline(cfg *PipelineConfig) error {
 	if strings.TrimSpace(cfg.Workspace.Root) == "" {
 		return fmt.Errorf("pipeline.workspace.root is required")
 	}
+	if err := validateSecrets(cfg.Secrets); err != nil {
+		return err
+	}
 	if err := validateWhisperX(cfg.WhisperX); err != nil {
 		return err
 	}
@@ -61,6 +64,16 @@ func validatePipeline(cfg *PipelineConfig) error {
 	return nil
 }

+func validateSecrets(cfg *SecretsConfig) error {
+	if cfg == nil {
+		return nil
+	}
+	if strings.TrimSpace(cfg.EnvDir) == "" {
+		return fmt.Errorf("pipeline.secrets.env_dir must be non-empty when pipeline.secrets is configured")
+	}
+	return nil
+}
+
 func validateNormalize(cfg *NormalizeConfig) error {
 	if cfg == nil {
 		return nil
@@ -187,15 +200,12 @@ func validateAudita(cfg AuditaConfig) error {
 	if err := validateDuration("pipeline.audita.timeout", cfg.Timeout); err != nil {
 		return err
 	}
-	if len(cfg.Modules) == 0 {
-		return fmt.Errorf("pipeline.audita.modules must include at least one module")
-	}
-	for i, mod := range cfg.Modules {
-		m := strings.TrimSpace(mod)
-		if m == "" {
+	for i, m := range cfg.Modules {
+		module := strings.TrimSpace(m)
+		if module == "" {
 			return fmt.Errorf("pipeline.audita.modules[%d] must be non-empty", i)
 		}
-		switch m {
+		switch module {
 		case "glossary", "homophones", "spoken_word", "grammar":
 		default:
 			return fmt.Errorf("pipeline.audita.modules[%d] must be one of: glossary, homophones, spoken_word, grammar", i)
@@ -213,18 +223,31 @@ func validateAudita(cfg AuditaConfig) error {
 	if strings.TrimSpace(cfg.Model) == "" {
 		return fmt.Errorf("pipeline.audita.model is required")
 	}
-	if cfg.LLMConcurrency == nil {
-		return fmt.Errorf("pipeline.audita.llm_concurrency must be set (defaults should populate this)")
+	if cfg.TotalLLMConcurrency != nil && *cfg.TotalLLMConcurrency <= 0 {
+		return fmt.Errorf("pipeline.audita.total_llm_concurrency must be > 0")
 	}
-	if *cfg.LLMConcurrency <= 0 {
-		return fmt.Errorf("pipeline.audita.llm_concurrency must be > 0")
+	if cfg.ProposalLLMConcurrency != nil && *cfg.ProposalLLMConcurrency <= 0 {
+		return fmt.Errorf("pipeline.audita.proposal_llm_concurrency must be > 0")
 	}
-	if cfg.ValidationLLMConcurrency == nil {
-		return fmt.Errorf("pipeline.audita.validation_llm_concurrency must be set (defaults should populate this)")
-	}
-	if *cfg.ValidationLLMConcurrency <= 0 {
+	if cfg.ValidationLLMConcurrency != nil && *cfg.ValidationLLMConcurrency <= 0 {
 		return fmt.Errorf("pipeline.audita.validation_llm_concurrency must be > 0")
 	}
+	if strings.TrimSpace(cfg.TranscriptDescription) == "" && cfg.TranscriptDescription != "" {
+		return fmt.Errorf("pipeline.audita.transcript_description must be non-empty when provided")
+	}
+	if strings.TrimSpace(cfg.ConfigPath) == "" && cfg.ConfigPath != "" {
+		return fmt.Errorf("pipeline.audita.config_path must be non-empty when provided")
+	}
+	switch strings.TrimSpace(cfg.OutputSchema) {
+	case "", "bare-segments", "audita-v1":
+	default:
+		return fmt.Errorf("pipeline.audita.output_schema must be one of: bare-segments, audita-v1")
+	}
+	switch strings.TrimSpace(cfg.WorkDirRetention) {
+	case "", "always", "auto", "never":
+	default:
+		return fmt.Errorf("pipeline.audita.work_dir_retention must be one of: always, auto, never")
+	}
 	return nil
 }

--- a/internal/stage/polish.go
+++ b/internal/stage/polish.go
@@ -90,6 +90,12 @@ func (polishStage) Run(ctx context.Context, env *Env, m *manifest.Manifest) (*St
 		Modules:                  append([]string(nil), env.Config.Pipeline.Audita.Modules...),
 		BaseURL:                  env.Config.Pipeline.Audita.BaseURL,
 		Model:                    env.Config.Pipeline.Audita.Model,
+		TranscriptDescription:    env.Config.Pipeline.Audita.TranscriptDescription,
+		ConfigPath:               env.Config.Pipeline.Audita.ConfigPath,
+		OutputSchema:             env.Config.Pipeline.Audita.OutputSchema,
+		WorkDirRetention:         env.Config.Pipeline.Audita.WorkDirRetention,
+		TotalLLMConcurrency:      env.Config.Pipeline.Audita.TotalLLMConcurrency,
+		ProposalLLMConcurrency:   env.Config.Pipeline.Audita.ProposalLLMConcurrency,
 		ValidationModel:          env.Config.Pipeline.Audita.ValidationModel,
 		ValidationLLMConcurrency: env.Config.Pipeline.Audita.ValidationLLMConcurrency,
 		StdoutLogPath:            stdoutPath,
@@ -141,44 +147,52 @@ func (polishStage) Run(ctx context.Context, env *Env, m *manifest.Manifest) (*St
 	if env.Config.Pipeline.Audita.ValidationLLMConcurrency != nil {
 		validationConcurrency = *env.Config.Pipeline.Audita.ValidationLLMConcurrency
 	}
-	var llmConcurrency any
-	if env.Config.Pipeline.Audita.LLMConcurrency != nil {
-		llmConcurrency = *env.Config.Pipeline.Audita.LLMConcurrency
+	var totalLLMConcurrency any
+	if env.Config.Pipeline.Audita.TotalLLMConcurrency != nil {
+		totalLLMConcurrency = *env.Config.Pipeline.Audita.TotalLLMConcurrency
+	}
+	var proposalLLMConcurrency any
+	if env.Config.Pipeline.Audita.ProposalLLMConcurrency != nil {
+		proposalLLMConcurrency = *env.Config.Pipeline.Audita.ProposalLLMConcurrency
 	}

 	meta := map[string]any{
-		"stage":                           "polish",
-		"merged_transcript_path":          mergedPath,
-		"merged_transcript_source":        source,
-		"glossary_path":                   glossaryPath,
-		"output_path":                     finalProcessedPath,
-		"report_path":                     finalReportPath,
-		"audita_work_dir":                 workDir,
-		"report_enabled":                  reportEnabled,
-		"modules":                         append([]string(nil), req.Modules...),
-		"base_url":                        req.BaseURL,
-		"model":                           req.Model,
-		"validation_model":                req.ValidationModel,
-		"llm_concurrency":                 llmConcurrency,
-		"validation_llm_concurrency":      validationConcurrency,
-		"llm_api_key_env":                 env.Config.Pipeline.Audita.LLMAPIKeyEnv,
-		"timeout":                         env.Config.Pipeline.Audita.Timeout,
-		"binary":                          env.Config.Pipeline.Audita.Binary,
-		"generated_config_path":           generatedConfigPath,
-		"stdout_log_path":                 stdoutPath,
-		"stderr_log_path":                 stderrPath,
-		"adapter_duration_ms":             res.Duration.Milliseconds(),
-		"adapter_exit_code":               res.ExitCode,
-		"adapter_invoked_binary":          res.InvokedBinary,
-		"adapter_processed_output_path":   res.ProcessedTranscriptPath,
-		"adapter_report_path":             res.ReportPath,
-		"adapter_generated_config_path":   res.GeneratedConfigPath,
-		"adapter_work_dir":                res.WorkDir,
-		"adapter_stdout_log_path":         res.StdoutLogPath,
-		"adapter_stderr_log_path":         res.StderrLogPath,
-		"credential_env_var":              env.Config.Pipeline.Audita.LLMAPIKeyEnv,
-		"credential_present":              false,
-		"primary_llm_concurrency_via_env": false,
+		"stage":                         "polish",
+		"merged_transcript_path":        mergedPath,
+		"merged_transcript_source":      source,
+		"glossary_path":                 glossaryPath,
+		"output_path":                   finalProcessedPath,
+		"report_path":                   finalReportPath,
+		"audita_work_dir":               workDir,
+		"report_enabled":                reportEnabled,
+		"modules":                       append([]string(nil), req.Modules...),
+		"base_url":                      req.BaseURL,
+		"model":                         req.Model,
+		"transcript_description":        req.TranscriptDescription,
+		"config_path":                   req.ConfigPath,
+		"output_schema":                 req.OutputSchema,
+		"work_dir_retention":            req.WorkDirRetention,
+		"validation_model":              req.ValidationModel,
+		"total_llm_concurrency":         totalLLMConcurrency,
+		"proposal_llm_concurrency":      proposalLLMConcurrency,
+		"validation_llm_concurrency":    validationConcurrency,
+		"llm_api_key_env":               env.Config.Pipeline.Audita.LLMAPIKeyEnv,
+		"timeout":                       env.Config.Pipeline.Audita.Timeout,
+		"binary":                        env.Config.Pipeline.Audita.Binary,
+		"generated_config_path":         generatedConfigPath,
+		"stdout_log_path":               stdoutPath,
+		"stderr_log_path":               stderrPath,
+		"adapter_duration_ms":           res.Duration.Milliseconds(),
+		"adapter_exit_code":             res.ExitCode,
+		"adapter_invoked_binary":        res.InvokedBinary,
+		"adapter_processed_output_path": res.ProcessedTranscriptPath,
+		"adapter_report_path":           res.ReportPath,
+		"adapter_generated_config_path": res.GeneratedConfigPath,
+		"adapter_work_dir":              res.WorkDir,
+		"adapter_stdout_log_path":       res.StdoutLogPath,
+		"adapter_stderr_log_path":       res.StderrLogPath,
+		"credential_env_var":            env.Config.Pipeline.Audita.LLMAPIKeyEnv,
+		"credential_present":            false,
 	}
 	if res.Metadata != nil {
 		meta["adapter_metadata"] = res.Metadata
@@ -188,9 +202,6 @@ func (polishStage) Run(ctx context.Context, env *Env, m *manifest.Manifest) (*St
 		if value, ok := res.Metadata["credential_env_var"]; ok {
 			meta["credential_env_var"] = value
 		}
-		if value, ok := res.Metadata["primary_llm_concurrency_via_env"]; ok {
-			meta["primary_llm_concurrency_via_env"] = value
-		}
 	}

 	return &StageResult{
--- a/internal/stage/polish_test.go
+++ b/internal/stage/polish_test.go
@@ -60,6 +60,24 @@ func TestPolishStagePolishesMergedTranscriptAndRecordsMetadata(t *testing.T) {
 	if req.ValidationModel != "openrouter/google/gemma-4-31b-it" {
 		t.Fatalf("validation model = %q", req.ValidationModel)
 	}
+	if req.TranscriptDescription != "Campaign Session 42" {
+		t.Fatalf("transcript description = %q", req.TranscriptDescription)
+	}
+	if req.ConfigPath != "/etc/audita/config.yml" {
+		t.Fatalf("config path = %q", req.ConfigPath)
+	}
+	if req.OutputSchema != "audita-v1" {
+		t.Fatalf("output schema = %q", req.OutputSchema)
+	}
+	if req.WorkDirRetention != "auto" {
+		t.Fatalf("work dir retention = %q", req.WorkDirRetention)
+	}
+	if req.TotalLLMConcurrency == nil || *req.TotalLLMConcurrency != 3 {
+		t.Fatalf("total llm concurrency = %#v, want 3", req.TotalLLMConcurrency)
+	}
+	if req.ProposalLLMConcurrency == nil || *req.ProposalLLMConcurrency != 2 {
+		t.Fatalf("proposal llm concurrency = %#v, want 2", req.ProposalLLMConcurrency)
+	}
 	if req.ValidationLLMConcurrency == nil || *req.ValidationLLMConcurrency != 2 {
 		t.Fatalf("validation llm concurrency = %#v, want 2", req.ValidationLLMConcurrency)
 	}
@@ -89,6 +107,15 @@ func TestPolishStagePolishesMergedTranscriptAndRecordsMetadata(t *testing.T) {
 	if result.Metadata["audita_work_dir"] != filepath.Join(paths.ArtifactsDir, "audita-work") {
 		t.Fatalf("metadata audita_work_dir = %#v", result.Metadata["audita_work_dir"])
 	}
+	if result.Metadata["total_llm_concurrency"] != 3 {
+		t.Fatalf("metadata total_llm_concurrency = %#v, want 3", result.Metadata["total_llm_concurrency"])
+	}
+	if result.Metadata["proposal_llm_concurrency"] != 2 {
+		t.Fatalf("metadata proposal_llm_concurrency = %#v, want 2", result.Metadata["proposal_llm_concurrency"])
+	}
+	if result.Metadata["output_schema"] != "audita-v1" {
+		t.Fatalf("metadata output_schema = %#v, want audita-v1", result.Metadata["output_schema"])
+	}
 }

 func TestPolishStageFallsBackToMergedTranscriptPath(t *testing.T) {
@@ -221,7 +248,8 @@ func setupPolishEnv(t *testing.T) (*Env, *manifest.Manifest) {
 	writeFile(t, pipelinePath, "workspace:\n  root: "+workspace+"\n")

 	report := true
-	llmConcurrency := 1
+	totalLLMConcurrency := 3
+	proposalLLMConcurrency := 2
 	validationLLMConcurrency := 2

 	cfg := &config.Config{
@@ -236,8 +264,13 @@ func setupPolishEnv(t *testing.T) (*Env, *manifest.Manifest) {
 				Modules:                  []string{"glossary", "homophones", "grammar"},
 				BaseURL:                  "https://openrouter.ai/api/v1",
 				Model:                    "openrouter/google/gemma-4-31b-it",
+				TranscriptDescription:    "Campaign Session 42",
+				ConfigPath:               "/etc/audita/config.yml",
+				OutputSchema:             "audita-v1",
+				WorkDirRetention:         "auto",
 				ValidationModel:          "openrouter/google/gemma-4-31b-it",
-				LLMConcurrency:           &llmConcurrency,
+				TotalLLMConcurrency:      &totalLLMConcurrency,
+				ProposalLLMConcurrency:   &proposalLLMConcurrency,
 				ValidationLLMConcurrency: &validationLLMConcurrency,
 				Report:                   &report,
 			},
Author	SHA1	Message	Date
Eric Rakestraw	58c6ab2d54	Updated audita configuration to reflect the new audita public CLI All checks were successful ci/woodpecker/tag/release Pipeline was successful Details	2026-05-16 08:46:48 -05:00
Eric Rakestraw	7995c41675	Update the audita integration documentation reference All checks were successful ci/woodpecker/tag/release Pipeline was successful Details	2026-05-16 08:02:18 -05:00
Eric Rakestraw	62551d43a0	Added filesystem-based secrets loading configuration	2026-05-16 07:56:22 -05:00
Eric Rakestraw	8395c12dd3	Update documentation to include an implementation roadmap for the archive stage	2026-05-16 07:36:25 -05:00
Eric Rakestraw	dc8e1040f2	Rationalize config file locations and update documentation All checks were successful ci/woodpecker/tag/release Pipeline was successful Details	2026-05-14 21:02:06 -05:00