narratio/report-gemma4.md

Narratio UX Evaluation Report

1. Executive Summary

Narratio has a functional core pipeline with robust S3 integration for input and output, but it currently falls short of the intended "minimalist" operator UX. The primary gaps are the lack of session configuration discovery, the absence of session template support (and the --session-id flag), and the missing local cleanup logic. While the pipeline runs successfully, the operator must currently provide explicit session file paths for every run.

2. Feature Matrix

Feature	Status	Evidence	Tests	Documentation	Notes
Pipeline Config Discovery	Implemented	internal/app/pipeline_config_path_test.go	Yes	Accurate	Checks /usr/local/etc and /etc.
Session Config Discovery	Missing	internal/app/run.go:30	N/A	Stale	--session is mandatory.
Session Templates	Missing	internal/config/load.go	N/A	Missing	No variable interpolation in session.yml.
--session-id CLI Flag	Missing	cmd/narratio	N/A	Missing	Not implemented in CLI.
Minimal Seriatim Config	Implemented	internal/config/load.go	Yes	Accurate	Defaults for timeout/schema provided.
Minimal Audita Config	Implemented	internal/config/load.go	Yes	Accurate	Defaults for base_url/model provided.
S3 Audio Input	Implemented	internal/stage/prepare.go	Yes	Accurate	Supports .flac downloads from S3.
S3 Archive & Promotion	Implemented	internal/stage/archive.go	Yes	Accurate	Correct paths and commit markers.
Local Cleanup	Missing	architecture.md:136	No	Stale	Config exists, logic is not implemented.

3. Current Happy Path

The shortest command that works today is: narratio run --session <path_to_session.yml> (Assuming pipeline.yml is present in /etc/narratio/ or /usr/local/etc/narratio/).

4. Gaps to Intended UX

1. Session Discovery & Templates (High): The requirement to pass --session and the inability to use --session-id with a template is the largest friction point for operators.
2. Local Cleanup (Medium): Spool and work directories are not cleaned up after successful archival, leading to local disk growth.
3. Local Pipeline Config (Low): Narratio does not check ./pipeline.yml, requiring users to use --config or move files to system directories.

5. Recommended Next Implementation Prompt

"Implement session configuration discovery and template support. Specifically: 1) Add a search order for session.yml (e.g., ./session.yml, /etc/narratio/session.yml) if --session is omitted. 2) Implement the --session-id CLI flag. 3) Add variable interpolation to session.yml so that {{session_id}} can be replaced by the value from the flag or the discovered session config before YAML decoding."