Configuration Schema
====================

Schema V2
---------

``schema_version``
   Must be integer ``2``.

``project_name``
   Required project identifier.

``output_dir``
   Optional output root, relative to the config file when not absolute.
   Defaults to ``.``.

``samples``
   Required path to the strict TSV sample sheet, relative to the config file
   when not absolute.

``assay`` and ``genome``
   Default to ``twist_human_methylome`` and ``hg38``. Both must exactly match
   the selected profile manifest.

``reference_mode``
   ``local`` resolves an installed profile. ``managed`` acquires a profile from
   the validated registry and is the default for new projects.

``reference_root``
   Root containing profile directories. ``CFTK_REFERENCE_ROOT`` overrides this
   value at runtime for portability.

``reference_profile``
   A profile ID string or an object containing ``id`` and optional ``version``.
   When version is omitted, exactly one installed version must exist.

``fragmentomics_scope``
   Optional advanced fragmentomics scope: ``auto``, ``panel``, or ``genome``.
   ``auto`` selects panel-overlapping reads and regions for the default Twist
   Human Methylome targeted assay and genome-wide inputs for other assays.
   ``panel`` is useful for a custom capture profile; ``genome`` is an expert
   override and should be used only with validated whole-genome inputs.

``process``
   Optional compact object with positive integer ``cores``,
   ``parallel_samples``, and ``min_depth`` values. Defaults are 20, 1, and 10.
   ``cores`` is one total workflow CPU budget. Concurrent sample commands
   receive ``floor(cores / effective_parallel_samples)`` threads each, and
   ``parallel_samples`` cannot exceed ``cores``. When fewer samples remain than
   requested, CFTK recalculates the per-sample share from the effective number.
   Duplicate marking uses ``sambamba`` by default. Advanced users may set
   ``duplicate_marking_tool`` to ``picard`` or ``samblaster`` when their
   environment or validation protocol requires it.
   The optional ``picard_java_memory`` value uses JVM size notation such as
   ``8g`` or ``4096m`` and defaults to ``8g``.

Sample Sheet Schema
-------------------

The required columns are ``sample``, ``group``, ``role``, ``input_type``,
``r1``, ``r2``, and ``bam``. Schema v2 supports one or two groups. A one-group
project is processing/QC-only and may use a ``control`` or ``case`` role. A
two-group project requires exactly one ``control`` group and one ``case``
group. FASTQ samples require R1 and R2; BAM samples require a BAM path. Rows and
group insertion order are preserved.

Resolved Contract
-----------------

CFTK resolves schema v2 internally into the legacy nested keys expected by
existing commands: ``comparison``, grouped ``samples``, ``reference_data``,
``process``, and ``analysis``. The profile ``target_bed`` is used for Picard
coverage. For WPS, occupancy, and DELFI, the default Twist ``auto`` scope also
uses it to restrict reads and reported intervals to panel overlap; it does not
filter methylation calling or other downstream analyses.
For a one-group project, ``comparison`` is unset and comparative commands
require a two-group project rather than inferring or duplicating a group.

Legacy Schema
-------------

Configs without ``schema_version: 2`` retain the established requirements:
``project_name``, ``output_dir``, ``comparison``, ``samples``,
``reference_data``, ``process``, and ``analysis``. Required references are
``genome_fa``, ``genome_2bit``, and ``chrom_sizes``. Legacy behavior and field
names are preserved.