Install and configure Notarius

README.md

@@ -1,3 +1,78 @@
-# ansible-role-notarius
+# Ansible Role: Notarius
 
-Ansible role to install the Notarius application.
+Installs and configures [Notarius](https://gitea.maximumdirect.net/eric/notarius)
+from source on Ubuntu 26.04 (`x86_64` or `aarch64`). The role requires gathered
+facts and uses privilege escalation only for dependency installation and
+root-owned application state.
+
+## Variables
+
+```yaml
+notarius_version: v0.6.0
+notarius_repository_url: https://gitea.maximumdirect.net/eric/notarius.git
+notarius_source_dir: /usr/local/src/notarius
+notarius_binary_path: /usr/local/bin/notarius
+notarius_manage_build_dependencies: true
+notarius_go_snap_channel: 1.26/stable
+notarius_go_binary: /snap/bin/go
+notarius_config_path: /usr/local/etc/notarius/config.yml
+notarius_config_version: 4
+notarius_promptkit_profile_dir: null
+notarius_promptkit_profile_file: null
+notarius_promptkit_local_backend_endpoint: null
+notarius_promptkit_local_backend_concurrency_limit: null
+notarius_pipelines: null
+notarius_concurrency_total_llm: null
+notarius_concurrency_stage_workers_extract: null
+notarius_output_directory: null
+notarius_cache_chunk_plans_mode: null
+notarius_cache_chunk_plans_directory: null
+notarius_cache_checkpoints_enabled: null
+notarius_cache_checkpoints_directory: null
+notarius_debug_directory: null
+```
+
+When `notarius_manage_build_dependencies` is `false`, Git and the executable
+selected by `notarius_go_binary` must already be available. Otherwise, the role
+installs Git with APT and the classic Go Snap from `notarius_go_snap_channel`.
+It checks out `notarius_version` authoritatively, builds `./cmd/notarius`
+directly to `notarius_binary_path`, and rebuilds only when that checkout changes
+or the binary is absent. The source tree is recursively owned by `root:root`;
+the binary is `root:root` mode `0755`.
+
+Configuration variables map directly to Notarius's versioned YAML fields.
+Every optional value defaults to `null`, so it and any empty parent section are
+omitted and Notarius retains ownership of its built-in defaults. The role always
+emits `notarius_config_version` as `version` and writes the file as `root:root`
+mode `0644`. `notarius_pipelines` is the native mapping supplied by the caller;
+the role does not merge or rewrite it. For example, inventory can compose
+fragments in the ordinary way:
+
+```yaml
+notarius_pipelines: "{{ notarius_pipeline_group_one | combine(notarius_pipeline_group_two) }}"
+```
+
+PromptKit profile values identify profile sources or a local backend endpoint;
+they never contain credentials. Supply any credential environment variables
+outside this role.
+
+## Example
+
+```yaml
+- hosts: notarius_hosts
+  roles:
+    - role: ansible-role-notarius
+```
+
+## Validation
+
+The repository-local integration suite installs its pinned collection, runs
+syntax checking and production-profile lint, verifies the default release,
+ownership, executable output, minimal configuration, native configuration
+validation, and immediate idempotence. It mutates only the managed source,
+binary, configuration, and a private temporary directory, then leaves the
+default release and minimal configuration installed.
+
+```sh
+tests/integration
+```