docs/registry/README.md

# Markdown Capability Registry

This directory stores composable Markdown capability cards. A card is a small
human-readable configuration unit with YAML front matter and operational notes.

Cards are intentionally separated by concern:

- `elements/`: target feature or object type, such as green tide, ship, oil spill, sea ice.
- `satellites/`: satellite/platform assumptions.
- `sensors/`: sensor or product type assumptions.
- `resolutions/`: spatial-resolution policies.

Extraction and training jobs should compose the cards they need instead of using
a single fixed class list. For example:

```powershell
python scripts/compose_task_profile.py `
  --element green_tide `
  --satellite GF6 `
  --sensor PMS `
  --resolution 2m `
  --output configs/profiles/gf6_green_tide_2m.json
```

For already fused GF6-like products, inject a fused product card:

```powershell
python scripts/compose_task_profile.py `
  --element green_tide `
  --satellite GF6 `
  --sensor PMS `
  --fusion FUSED_OPTICAL `
  --resolution 2m `
  --output configs/profiles/gf6_green_tide_fused_2m.json
```

For raw PAN+MSS products where fusion should happen tile by tile during
inference, inject the streaming fusion card:

```powershell
python scripts/compose_task_profile.py `
  --element green_tide `
  --satellite GF2 `
  --sensor PMS `
  --fusion STREAM_FUSION `
  --resolution 2m `
  --output configs/profiles/gf2_green_tide_stream_fusion_2m.json
```

## Card Format

Each card starts with YAML front matter:

```markdown
---
id: green_tide
type: element
task_types: [semantic_segmentation]
preferred_heads: [validity, context, semantic_segmentation]
label_formats: [mask, polygon]
---

# Green Tide

Human-readable notes, rules, constraints, and known failure modes.
```

The front matter is parsed by `scripts/compose_task_profile.py`. The Markdown body
is kept in the output profile so that training/inference logs preserve the
reasoning and caveats behind the selected cards.

## Fused Image Expression

Fused imagery is represented as a derived observation, not as a plain
multispectral image and not as a boolean flag. The selected profile and dataset
manifest must keep a `fusion` object with:

- `state`: `none`, `fused_product`, `runtime_fusion`, or `unknown`.
- `method`: known method, implementation method, or `unknown_vendor_product`.
- `sources`: source roles and paths such as PAN and MSS.
- `target_resolution_m`: output grid resolution.
- `native_multispectral_resolution_m`: original multispectral resolution.
- `persisted`: whether the fused image exists on disk.
- `reproducible`: whether the source data and method can reproduce it.
- `spectral_preservation`: known or estimated spectral preservation risk.

This keeps GF6 supplied fused rasters, GF1/GF2 tile-wise fusion, and future
fusion algorithms comparable without pretending they are identical inputs.

## Hard Constraint

Do not assume coastline vectors, land-mask vectors, or external GIS layers are
available. If a task needs land, water, invalid, or cloud handling, it must be
expressed as context labels, hard-negative samples, validity rules, or model
heads.