# Ansible Role: Narratio

Installs and configures [Narratio](https://gitea.maximumdirect.net/eric/narratio)
from source on Ubuntu 26.04 (`x86_64` or `aarch64`). The role requires gathered
facts and uses task-level privilege escalation for dependencies and managed
application state.

## Variables

```yaml
narratio_version: v3.0.0
narratio_repository_url: https://gitea.maximumdirect.net/eric/narratio.git
narratio_source_dir: /usr/local/src/narratio
narratio_binary_path: /usr/local/bin/narratio
narratio_manage_build_dependencies: true
narratio_go_snap_channel: 1.26/stable
narratio_go_binary: /snap/bin/go
narratio_user: narratio
narratio_group: narratio
narratio_config_path: /usr/local/etc/narratio/pipeline.yml
narratio_config_owner: root
narratio_config_group: narratio
narratio_config_directory_mode: "0750"
narratio_config_file_mode: "0640"
narratio_workspace_root: /var/lib/narratio
narratio_campaigns_root: /usr/local/share/narratio/campaigns
narratio_spool_root: /var/spool/narratio
narratio_cache_root: /var/cache/narratio
```

`narratio_whisperx_transcribe_url` is required and must be an absolute HTTP or
HTTPS URL. Every other pipeline setting is optional and defaults to `null`:

```yaml
narratio_configkit_imports: null
narratio_workspace_cleanup_after_publish: null
narratio_campaigns_default_campaign_id: null
narratio_storage_backend: null
narratio_storage_s3_bucket: null
narratio_storage_s3_root_prefix: null
narratio_storage_s3_region: null
narratio_storage_s3_endpoint: null
narratio_storage_s3_force_path_style: null
narratio_storage_s3_access_key_id: null
narratio_storage_s3_secret_access_key: null
narratio_spool_delete_audio_after_publish: null
narratio_cache_s3_audio: null
narratio_publish_enabled: null
narratio_publish_upload_run: null
narratio_publish_outputs: null
narratio_whisperx_language: null
narratio_whisperx_timeout: null
narratio_whisperx_retries: null
narratio_whisperx_retry_delay: null
narratio_whisperx_concurrency: null
narratio_seriatim_binary: null
narratio_seriatim_timeout: null
narratio_seriatim_output_schema: null
narratio_seriatim_coalesce_gap: null
narratio_seriatim_report: null
narratio_seriatim_env_overlap_word_run_gap: null
narratio_seriatim_env_overlap_word_run_reorder_window: null
narratio_seriatim_env_backchannel_max_duration: null
narratio_seriatim_env_filler_max_duration: null
narratio_audita_binary: null
narratio_audita_timeout: null
narratio_audita_credentials: null
narratio_audita_modules: null
narratio_audita_overlay: null
narratio_audita_proposal_profile: null
narratio_audita_validation_profile: null
narratio_audita_transcript_description: null
narratio_audita_config_path: null
narratio_audita_output_schema: null
narratio_normalize_output_path: null
narratio_normalize_output_schema: null
narratio_normalize_report: null
narratio_trim_enabled: null
narratio_trim_output_path: null
narratio_trim_bounds_prompt_id: null
narratio_trim_bounds_profile_id: null
narratio_trim_bounds_transcript_input_name: null
narratio_trim_bounds_output_path: null
narratio_trim_bounds_timeout: null
narratio_trim_bounds_render_debug: null
narratio_trim_bounds_render_output_path: null
narratio_trim_seriatim_report: null
narratio_render_enabled: null
narratio_render_format: null
narratio_render_title: null
narratio_render_include_timestamps: null
narratio_render_include_segment_ids: null
narratio_render_include_metadata: null
narratio_scriptorium_binary: null
narratio_scriptorium_config_path: null
narratio_scriptorium_timeout: null
narratio_scriptorium_render_debug: null
narratio_scriptorium_artifacts: null
narratio_scriptorium_artifact_families: null
narratio_notarius_enabled: null
narratio_notarius_binary: null
narratio_notarius_config_path: null
narratio_notarius_config_overlay: null
narratio_notarius_pipeline_id: null
narratio_notarius_timeout: null
narratio_notarius_working_directory: null
narratio_notarius_credentials: null
narratio_notarius_resume: null
narratio_notarius_chunk_cache: null
narratio_notarius_references: null
narratio_notarius_outputs: null
narratio_notification_mode: null
```

With dependency management enabled, the role installs Git and the classic Go
Snap from `narratio_go_snap_channel`. When disabled, Git and the executable at
`narratio_go_binary` must already be available. The role checks out
`narratio_version`, builds `./cmd/narratio` to `narratio_binary_path`, and
rebuilds only when the checkout changes or the binary is absent.

The `narratio` account owns the workspace, spool, and cache roots, which are
group-writable setgid directories. The campaign registry is `root:narratio`
and operator-readable; its content remains caller-managed. Configuration
ownership and modes are independently configurable: the standalone defaults
are `root:narratio`, mode `0750` for the directory and `0640` for the managed
pipeline file. Composing roles may override these inputs without changing the
writable-root policy.

Null pipeline values and their empty parent mappings are omitted; non-null
falsey values are preserved. `narratio_publish_outputs`,
`narratio_notarius_references`, `narratio_notarius_outputs`,
`narratio_scriptorium_artifacts`, and `narratio_scriptorium_artifact_families`
are complete native caller values, so callers may compose them before assigning
them and the role does not merge or rewrite them. Credential lists contain
environment-variable names only; credential values remain outside this role
and are the caller's responsibility. The optional
`narratio_notarius_config_overlay` selects a Notarius ConfigKit overlay without
coupling it to Narratio's own overlay name. The optional `narratio_notarius_resume`
and `narratio_notarius_chunk_cache` settings expose Narratio's native extraction
and chunk-plan choices; this generic role assigns no D&D-specific credential or
cache policy.
ConfigKit imports and selected overlays are externally managed, and this role
does not install the downstream applications, campaign content, or suite policy.

Narratio v3 removes the old Audita tuning, report, retention, and singular-key
role variables. It also replaces `narratio_notarius_llm_api_key` with
`narratio_notarius_credentials` and renames
`narratio_notarius_config_profile` to `narratio_notarius_config_overlay`.
Existing deployments that cannot migrate these inputs should retain their
previous Narratio role pin.

## Example

```yaml
- hosts: narratio_hosts
  roles:
    - role: ansible-role-narratio
      vars:
        narratio_whisperx_transcribe_url: https://whisperx.example.test/transcribe
```

## Validation

The repository-local integration suite installs its pinned collection and runs
syntax checking and production-profile lint. It validates a baseline managed
pipeline through Narratio as its application account and requires immediate
clean repeated convergence. It explicitly selects `v2.1.0` and checks native
version output, then combines missing-binary recovery with a caller-supplied Go
executable while dependency management is disabled. A representative pipeline
checks null omission, falsey values, caller-composed native collections, and
the native Notarius credential-reference, `resume`, and chunk-cache fields
before native validation and a clean repeat. The suite restores the baseline
deployment during cleanup.

```sh
tests/integration
```