Workflow package contract
=========================

RAFT workflow configuration repositories can provide more than the execution
``.config`` file. A complete workflow package can define how RAFT creates a
project, guides manifest creation, builds reports, and checks project status.

Recommended files
-----------------

For a workflow package such as ``lens-human-fastqs``, use these filenames:

.. code-block:: text

  lens.human.fastqs.config
  lens.human.fastqs.json
  lens.human.fastqs.manifest-ui.json
  lens.human.fastqs.report-ui.json
  lens.human.fastqs.status.json
  README.md

Execution config
----------------

``<workflow>.<species>.<input>.config`` contains default Nextflow parameters
and container settings copied into generated projects.

``<workflow>.<species>.<input>.json`` tells RAFT which modules, workflow steps,
references, post-processing commands, and text replacements are needed to build
the project.

Manifest UI config
------------------

``<workflow>.<species>.<input>.manifest-ui.json`` customizes the manifest
generator. It should define:

- required and optional columns
- allowed values
- sample type conventions
- workflow-specific requirements

For LENS, this is where columns such as ``Group`` and ``Alleles`` should be
explained for users.

Report UI config
----------------

``<workflow>.<species>.<input>.report-ui.json`` customizes the report viewer
and report bundle. It should define:

- report sections
- file patterns to include
- renderers
- table columns
- QC sections

Use narrow file patterns so report bundles include final review files instead
of large intermediate tables.

Status config
-------------

``<workflow>.<species>.<input>.status.json`` customizes
``raft project-status``. It can define:

- expected output paths
- globbed output families with minimum counts
- final report patterns
- required report columns
- value-count summaries
- all-blank column warnings

The command remains read-only. Status configs should warn about suspicious or
missing outputs; they should not repair or modify project files.

Project README
--------------

RAFT writes a generated ``README.md`` into each project directory. Workflow
packages can still include their own repository ``README.md`` to document
workflow-specific inputs, outputs, and interpretation.

Maintenance checklist
---------------------

When updating a workflow package:

- keep execution config and metadata JSON in sync
- update manifest UI columns when workflow inputs change
- update report UI patterns when output filenames change
- update status checks when final reports or required columns change
- run ``raft available-workflows --workflow <workflow> --species <species> --input <input>``
  to inspect what RAFT sees
- run ``raft project-status`` on a completed example project