Install and configure Narratio

README.md

@@ -1,3 +1,154 @@
-# ansible-role-narratio
+# Ansible Role: Narratio
 
-Ansible role to install the Narratio D&D transcript and session report generation suite.
+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: v2.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_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_llm_api_key: null
+narratio_audita_modules: null
+narratio_audita_base_url: null
+narratio_audita_model: null
+narratio_audita_total_llm_concurrency: null
+narratio_audita_proposal_llm_concurrency: null
+narratio_audita_validation_model: null
+narratio_audita_validation_llm_concurrency: null
+narratio_audita_transcript_description: null
+narratio_audita_config_path: null
+narratio_audita_output_schema: null
+narratio_audita_work_dir_retention: null
+narratio_audita_report: 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_pipeline_id: null
+narratio_notarius_timeout: null
+narratio_notarius_working_directory: 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. The configuration
+directory is `root:narratio` mode `0750`, and the pipeline is mode `0640`.
+
+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 fields name
+environment variables only; credential values remain outside this role.
+ConfigKit imports and profile overlays are externally managed, and this role
+does not install the downstream applications, campaign content, or suite policy.
+
+## 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, runs
+syntax checking and production-profile lint, validates a baseline managed
+pipeline through Narratio as its application account, and requires immediate
+clean repeated convergence. It restores the baseline deployment during cleanup.
+
+```sh
+tests/integration
+```
+
+Ansible role to install the Narratio D&D transcript and session report generation suite.