@pikaa-ai/pikaa 0.3.23 → 0.3.25

package/skills/omero-integration/SKILL.md

@@ -1,222 +0,0 @@
----
-name: omero-integration
-description: Securely inspect and automate microscopy data workflows against OMERO.server with omero-py, BlitzGateway, OMERO CLI, tables, annotations, ROIs, rendering, and documented OMERO.web APIs. Use for scoped OMERO inventory, metadata export, import/export planning, or reviewed write workflows.
-license: MIT
-compatibility: >-
-  Requires network access to a user-selected OMERO.server for remote operations.
-  The 2026-07-23 snapshot uses OMERO.py 5.22.1 with ZeroC IcePy 3.6.5;
-  OMERO supports Python 3.10-3.12 (3.12 recommended) while 3.13-3.14 remain
-  upcoming in its support matrix. Bundled local planners require Python 3.10+
-  and read only named OMERO_* variables; they never load .env files.
-metadata:
-  version: "1.3"
-  skill-author: K-Dense Inc.
-  openclaw:
-    envVars:
-      - name: OMERO_HOST
-        required: true
-        description: OMERO.server hostname.
-      - name: OMERO_PORT
-        required: false
-        description: OMERO SSL router port; default 4064.
-      - name: OMERO_USER
-        required: false
-        description: Username when not reusing a session.
-      - name: OMERO_PASSWORD
-        required: false
-        description: Password when not reusing a session.
-      - name: OMERO_SESSION_KEY
-        required: false
-        description: Existing session key as an alternative credential.
-      - name: OMERO_SECURE
-        required: false
-        description: Secure transport toggle; default true.
----
-
-# OMERO Integration
-
-Use current OME documentation and the smallest explicit data scope. OMERO data
-may contain unpublished images, identifiers, annotations, original files, and
-derived measurements.
-
-## Verified Baseline
-
-This skill was refreshed on **2026-07-23**:
-
-- **OMERO.server 5.6.18** (May 2026) is the current documented stable server.
-- It was tested by OME with **OMERO.py/omero-py 5.22.1** and
-  **OMERO.web 5.31.0**.
-- `omero-py==5.22.1` requires Python 3.10 or newer. The OMERO support matrix
-  supports 3.10 and 3.11, recommends 3.12, and still labels 3.13/3.14
-  “upcoming.”
-- OMERO 5.6 uses **IcePy 3.6**, with 3.6.5 prebuilt client wheels documented
-  for Python versions through 3.12.
-
-The pin above is a reproducible skill snapshot, not a promise that every
-OMERO.server release accepts that client. For another server version, consult
-its release entry and use the OMERO.py version tested with it. See
-[`references/sources.md`](references/sources.md).
-
-## Operating Contract
-
-1. Start with local validation or a dry run. Do not connect until the user has
-   selected the host, group, object type, IDs, and result limit.
-2. Read credentials only from the named `OMERO_*` variables in the frontmatter.
-   Never search parent directories or load `.env` files.
-3. Never place a password or session key in command arguments, source code,
-   output JSON, logs, tracebacks, or chat. A session key is a bearer credential.
-4. Default to `secure=True`. OMERO encrypts login by default, but post-login
-   data and the session ID may otherwise travel unencrypted. `secure=True` does
-   not by itself guarantee certificate hostname verification.
-5. Bound every list, page, ROI, shape, annotation, table row, pixel plane, and
-   local file scan. Do not turn an object request into a group-wide or
-   cross-group export without explicit approval.
-6. Treat all writes separately: annotation/link creation, rendering-default
-   saves, image creation, imports, script uploads, table writes, ownership or
-   group changes, and deletion require an exact reviewed target.
-7. Close `BlitzGateway`, table handles, raw stores, thumbnail stores, rendering
-   engines, script clients, and other stateful services in `finally` blocks or
-   documented context-manager patterns.
-8. Never connect to a real server merely to “test” examples.
-
-## Choose the Interface
-
-- **BlitzGateway (`omero-py`)**: primary Python client for object traversal,
-  pixels, annotations, ROIs, rendering, and services.
-- **OMERO CLI**: sessions, import scanning/import, OME-TIFF or XML export,
-  scripts, and administrative plugins. Most client commands are remote; import
-  also needs the matching server-side Java libraries through `OMERODIR`.
-- **OMERO.web `api` and `webgateway`**: the only OMERO.web apps that official
-  documentation calls stable public APIs. The documented JSON API is
-  version-discovered and has limited object coverage; it is not evidence that
-  every webclient URL is a supported REST endpoint.
-- **OMERO.server scripts**: uploaded plugins executed by server infrastructure.
-  They are different from the bundled local client helpers in `scripts/`.
-
-## Install a Reproducible Client
-
-Create a Python 3.12 environment:
-
-```bash
-uv venv --python 3.12 .venv
-source .venv/bin/activate
-```
-
-Install the exact IcePy 3.6.5 wheel matching the interpreter, OS, architecture,
-and wheel tags, then OMERO.py:
-
-```bash
-# Download the matching 3.6.5 wheel from the official OMERO-linked matrix.
-uv pip install "/absolute/path/to/zeroc_ice-3.6.5-<matching-tags>.whl"
-uv pip install "omero-py==5.22.1"
-```
-
-Do not substitute Ice 3.7: the OMERO 5.6 support matrix marks Ice 3.6 as
-recommended and 3.7 as unsupported. A plain install may attempt to compile
-IcePy from source; prefer a reviewed matching wheel. The upstream package is
-GPL-2.0-or-later; this skill’s own files are MIT.
-
-For import/admin commands only, `OMERODIR` must point to a compatible extracted
-OMERO.server directory. A normal remote BlitzGateway client does not require
-that server tree. Read [`references/connection.md`](references/connection.md)
-before installation or authentication work.
-
-## Credentials and Connection
-
-Set named variables in the calling environment or secret manager. Do not put
-the password on an `omero` CLI command:
-
-```bash
-export OMERO_HOST="omero.example.org"
-export OMERO_PORT="4064"
-export OMERO_USER="researcher"
-export OMERO_SECURE="true"
-# Supply OMERO_PASSWORD through the environment/secret manager, or use
-# OMERO_SESSION_KEY as an alternative. Do not echo either value.
-```
-
-A password-authenticated, exception-safe read pattern is:
-
-```python
-import os
-from omero.gateway import BlitzGateway
-
-conn = None
-try:
-    conn = BlitzGateway(
-        os.environ["OMERO_USER"],
-        os.environ["OMERO_PASSWORD"],
-        host=os.environ["OMERO_HOST"],
-        port=int(os.environ.get("OMERO_PORT", "4064")),
-        secure=True,
-    )
-    if not conn.connect():
-        raise RuntimeError("OMERO connection failed")
-
-    images = conn.getObjects(
-        "Image",
-        opts={"limit": 25, "offset": 0, "order_by": "obj.id"},
-    )
-    for image in images:
-        print(image.getId())  # Do not print names unless requested.
-finally:
-    if conn is not None:
-        conn.close()
-```
-
-For existing-session and CLI prompt patterns, certificate verification,
-group context, and cleanup details, read
-[`references/connection.md`](references/connection.md).
-
-## Bundled Safe Helpers
-
-All helpers use `argparse`; `--help` works without OMERO installed. Remote
-helpers are dry-run by default and require `--execute`.
-
-```bash
-python -B scripts/validate_config.py --help
-python -B scripts/inventory.py --help
-python -B scripts/export_image_metadata.py --help
-python -B scripts/plan_transfer.py --help
-```
-
-- `validate_config.py`: validates only named endpoint/auth variables locally;
-  optional DNS resolution still does not contact OMERO.
-- `inventory.py`: bounded, read-only object inventory with paged JSON output.
-- `export_image_metadata.py`: explicit-image annotation/ROI JSON export with
-  redaction defaults and per-category limits; it never downloads file bytes or
-  pixels.
-- `plan_transfer.py`: local-only import scan or per-image export plan; it never
-  invokes OMERO and never emits credential flags.
-
-Read [`references/scripts.md`](references/scripts.md) before using them.
-
-## Capability Guide
-
-- Connection, sessions, groups, TLS:
-  [`references/connection.md`](references/connection.md)
-- Hierarchies, pagination, screening data, import/export:
-  [`references/data_access.md`](references/data_access.md)
-- Tags, map/file/comment annotations, namespaces:
-  [`references/metadata.md`](references/metadata.md)
-- Raw planes, tiles, thumbnails, rendering:
-  [`references/image_processing.md`](references/image_processing.md)
-- ROI model, shape export, statistics caveat:
-  [`references/rois.md`](references/rois.md)
-- Bounded table creation, paging, querying, closure:
-  [`references/tables.md`](references/tables.md)
-- Local helpers and OMERO.server scripts:
-  [`references/scripts.md`](references/scripts.md)
-- Permissions, filesets, web/public links, destructive operations:
-  [`references/advanced.md`](references/advanced.md)
-
-## Final Review Before Remote Work
-
-- Confirm server version and its tested OMERO.py pairing.
-- Confirm target host, SSL router port, user/session, and one group.
-- Confirm exact object IDs/types and hard limits.
-- Confirm whether names, annotation values, file names, ROI labels, owner names,
-  pixels, or original files may leave the server.
-- Show the proposed output path and refuse overwrite unless explicitly allowed.
-- For a write, show the mutation and target IDs separately from any read plan.
-- Close every connection/service even after partial failure.

package/skills/onekgpd/SKILL.md

@@ -1,371 +0,0 @@
----
-name: onekgpd
-description: >
-  Query the 1000 Genomes Project dataset (3,202 whole-genome-sequenced
-  individuals, GRCh38) at the level of individual participants.
-  Use when a question is about individuals or variants in the 1000 Genomes
-  Project cohort: which individuals carry variants matching specific criteria
-  in a gene or region, which individuals are homozygous-reference at a position,
-  which variants exist in the dataset or carried by specified individuals
-  in a gene or region, the relatedness between two specified individuals.
-  Variants are returned with 1000 Genomes allele frequencies (AF),
-  gnomAD v4.1 exome and genome AF, AlphaMissense score, and HGVSp annotations.
-license: MIT
-compatibility: Requires Python >=3.11. Variant and sample queries require outbound network access to the public 1000 Genomes query endpoint over TLS; the sample/population metadata commands run fully offline over a data file bundled in the skill. No credentials, API keys, or environment variables are used.
-allowed-tools: Write Bash
-metadata:
-  version: "1.2"
-  skill-author: Dnaerys
----
-
-# OneKGPd: Individual-Level Queries over the 1000 Genomes Project
-
-## Scope
-
-This skill queries the 1000 Genomes Project dataset — the extended high-coverage cohort
-of 3,202 whole-genome-sequenced individuals, on the GRCh38 assembly. All results
-are drawn from this cohort, and sample names returned by the skill (for example
-`HG00096` or `NA21130`) identify its participants.
-
-Queries resolve against the cohort's per-individual genotype data. This supports
-two complementary classes of question: selecting **variants** carried within a
-region (across the whole cohort or within a specified set of individuals), and
-selecting the **individuals** who carry variants matching given criteria.
-Variant selection can be filtered by allele frequency, predicted consequence,
-clinical significance, AlphaMissense classification, and the other annotation
-axes listed below. Relatedness between two named individuals is also available.
-
-The genotype state in which a variant is carried — heterozygous or homozygous —
-is a criterion that queries may specify; results are returned as variants or as
-sample names, not as raw genotypes.
-
-## When to Use
-
-**Use this skill when you need to:**
-
--   Find **variants** carried in a region or set of regions matching some criteria
-    across the whole cohort (`select-variants`).
--   Find **variants** carried in a region or set of regions matching some criteria
-    in specific set of individuals (`select-variants-in-samples`).
--   Find **which 1000 Genomes individuals** carry variants matching some criteria
-    in a region or set of regions (`select-samples`).
--   Count how many individuals carry specific variants (`count-samples`).
--   Restrict any variant query to **heterozygous-only or homozygous-only**
-    carriage, or query both together (default).
--   Identify which individuals are **homozygous reference** at a single position
-    (`select-samples-hom-ref`).
--   Determine the **relatedness** between two named 1000 Genomes individuals —
-    both the degree (twin / 1st / 2nd / 3rd / unrelated) and the KING kinship
-    coefficient (`kinship`).
--   Get **dataset totals** — sample count, sex split, variant count, assembly
-    (`dataset-info`).
--   Variant selection can be specified by KGP allele frequency, gnomAD 4.1 exome and
-    gnomAD 4.1 genome allele frequency, AlphaMissense Score and AlphaMissense Class,
-    ClinVar significance (202502), and VEP annotations (impact, biotype, feature type,
-    variant class, consequences).
-
-**Do NOT use this skill for:**
-
--   Resolving a gene symbol, rsID, or transcript to coordinates, or fetching
-    reference sequence. Resolve coordinates first (see Coordinate Provenance
-    below), then query this skill with the resolved GRCh38 region.
--   Any cohort other than the 1000 Genomes Project — this skill serves only that
-    dataset.
-
-## Prerequisites
-
-1.  **`uv`**: This skill's script is run with `uv run`, which reads the script's
-    inline dependency metadata and provisions an ephemeral environment. Ensure
-    `uv` is installed and on PATH (https://docs.astral.sh/uv/).
-2.  **Data use terms**: The 1000 Genomes Project data is open; users should be
-    aware of the 1000 Genomes Project / IGSR data-use terms
-    (https://www.internationalgenome.org/data).
-3.  **Access constraints**: There is no API key, no `.env` file, and no
-    rate-limit token to configure.
-4.  **No credentials required**
-
-## Core Rules
-
--   **Use the Wrappers**: ALWAYS execute the provided helper scripts rather than
-    constructing your own client calls or network requests. Use
-    `scripts/onekgpd_api.py` for variant/sample/kinship queries (it handles the
-    connection, streaming, pagination, and JSON serialization), and
-    `scripts/onekgpd_meta.py` for sample/population metadata (offline, see
-    [Sample & population metadata](#sample--population-metadata-offline)).
--   **Coordinates MUST be resolved against an authoritative source first** — see
-    [Coordinate Provenance](#coordinate-provenance-mandatory-first-step). This
-    is mandatory, not advisory.
--   **Count before you select**: every variant and sample selection has a paired
-    counting command. Call the count command FIRST to size the result set, then
-    select only if the count is manageable.
--   **Zygosity defaults to both**: selection and counting commands include both
-    heterozygous and homozygous carriage by default. Narrow with `--het-only`
-    or `--hom-only` when the question is specifically about one state. (You do
-    not need to pass anything to get both.)
--   **Output**: scripts write full JSON to a file (`--output`, default under
-    `/tmp/`) and print a concise summary to stdout. Do not read large JSON files
-    into context — use `jq` or a small disposable `uv run python` snippet to
-    extract fields.
-
-## Coordinate Provenance (MANDATORY FIRST STEP)
-
-Before any region-based query, resolve the gene or feature to **GRCh38**
-coordinates against an authoritative source (for example Ensembl), and query
-with those resolved coordinates. The assembly must be explicit, and a gene-range
-must be resolved to precise positions before use. This is structural, not
-advisory: there is no source-side guardrail that would catch a misplaced region,
-so an unverified coordinate produces results for an unintended location with no
-error.
-
-```bash
-# Resolve gene symbol -> GRCh38 region with an authoritative source FIRST,
-# then pass the verified coordinates to the OneKGPd query below.
-```
-
-> [!CAUTION]
-> The dataset is GRCh38. A GRCh37 coordinate, or any region that does not
-> correctly correspond to the intended feature on GRCh38, will return
-> results for an unintended location without raising an error. Verify the
-> assembly and the resolved coordinates before querying.
-
-## Command Selection Guide
-
-Match the question to the command. Counting commands are cheap and should
-precede their selection counterpart.
-
--   Which individuals carry matching variants in a region → `count-samples`
-    then `select-samples`
--   Which variants are carried in a region, cohort-wide → `count-variants`
-    then `select-variants`
--   Which variants are carried in a region, within a named set of individuals →
-    `count-variants-in-samples` then `select-variants-in-samples`
--   Who is homozygous-reference at a single position → `count-samples-hom-ref`
-    then `select-samples-hom-ref`
--   Relatedness (degree + coefficient) between two named individuals →
-    `kinship`
--   Dataset totals (sample count, sex split, variant total, assembly) →
-    `dataset-info`
-
-## Annotation filters (shared across variant and sample selection/counting)
-
-All variant- and sample-selection commands (`count-variants`,
-`select-variants`, their `-in-samples` forms, `count-samples`, `select-samples`)
-accept the same annotation filters. Different filter fields are combined with
-**AND**; multiple values within one field are combined with **OR**. Enum values
-are case-insensitive (e.g. `missense_variant` or `MISSENSE_VARIANT`).
-
-These are selection criteria applied on the server. The fields returned on a
-selected variant are listed under
-[Variant-returning commands](#variant-returning-commands); a criterion used for
-filtering is not necessarily echoed back on the returned variant.
-
--   `--af-lt` / `--af-gt`: 1000 Genomes dataset allele frequency bounds
--   `--gnomad-exomes-af-lt` / `--gnomad-exomes-af-gt`: gnomAD v4.1 exome AF bounds
--   `--gnomad-genomes-af-lt` / `--gnomad-genomes-af-gt`: gnomAD v4.1 genome AF bounds
--   `--clin-significance`: ClinVar significance terms, CSV (e.g. `PATHOGENIC,LIKELY_PATHOGENIC`)
--   `--consequence`: Sequence Ontology consequence terms, CSV (e.g. `MISSENSE_VARIANT,STOP_GAINED`)
--   `--impact`: VEP impact, CSV (`HIGH,MODERATE,LOW,MODIFIER`)
--   `--variant-type`, `--feature-type`, `--bio-type`: SO variant class / VEP feature / VEP biotype, CSV
--   `--alpha-missense-class`: `AM_LIKELY_BENIGN,AM_LIKELY_PATHOGENIC,AM_AMBIGUOUS` (CSV)
--   `--alpha-missense-score-lt` / `--alpha-missense-score-gt`: AlphaMissense score bounds
--   `--biallelic-only` / `--multiallelic-only`
--   `--exclude-males` / `--exclude-females`
--   `--min-len-bp` / `--max-len-bp`: alternate-allele length bounds (bp)
-
-> [!NOTE]
-> `--alpha-missense-class` and `--alpha-missense-score-*` are mutually exclusive
-> (the engine ignores the class when a score bound is set). `--biallelic-only`
-> and `--multiallelic-only` are mutually exclusive. `--exclude-males` and
-> `--exclude-females` are mutually exclusive. Setting a `*-gt` bound greater than
-> or equal to its matching `*-lt` bound defines an empty range and will return
-> nothing.
-
-> [!NOTE]
-> Allele-frequency fields use `0.0` to mean "not present in that source." So
-> `--gnomad-exomes-af-gt 0` selects variants that *are* in gnomAD exomes; a
-> returned `gnomad_exomes_af` of `0.0` means the variant is absent from gnomAD
-> exomes. The same convention for gnomAD genomes AF.
-> Conversely, `--gnomad-exomes-af-lt` / `--gnomad-genomes-af-lt` bounds **include**
-unannotated variants: "AF < X in gnomAD" includes variants with gnomAD AF = 0,
-i.e. unannotated; pair it with `--gnomad-*-af-gt 0` to require presence in gnomAD.
-
-> [!NOTE]
-> `am_score` of `0.0` means not scored or not annotated by AlphaMissense - it does not mean `benign`.
-> A real AlphaMissense score is always greater than 0.
-
-## Quick Start
-
-```bash
-# Step 1. Resolve coordinates against an authoritative source — see Coordinate Provenance.
-#    example: BRCA1: chr17:43044292-43170245
-# Step 2. Size the result set: how many individuals carry predicted likely-pathogenic
-#    missense variants in this region?
-uv run scripts/onekgpd_api.py count-samples \
-  --chrom chr17 --start 43044292 --end 43170245 \
-  --consequence MISSENSE_VARIANT \
-  --alpha-missense-class AM_LIKELY_PATHOGENIC \
-  --output /tmp/count.json
-# Step 3. If the count is manageable, list those individuals.
-uv run scripts/onekgpd_api.py select-samples \
-  --chrom chr17 --start 43044292 --end 43170245 \
-  --consequence MISSENSE_VARIANT \
-  --alpha-missense-class AM_LIKELY_PATHOGENIC \
-  --output /tmp/samples.json
-# Step 4: For that set of individuals, see the actual variants they carry.
-uv run scripts/onekgpd_api.py select-variants-in-samples \
-  --chrom chr17 --start 43044292 --end 43170245 \
-  --samples HG03169,NA20506 \
-  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
-  --output /tmp/variants.json
-```
-
-## Commands
-
-Each command writes full JSON to a file (`--output PATH`, default a temp file)
-and prints a concise stdout summary. All region/sample commands share: the
-region input (`--chrom`/`--start`/`--end` with optional `--ref`/`--alt`, or one
-or more repeated `--region CHR:START-END`), the zygosity flags
-(`--het-only`/`--hom-only`, default both), and the annotation filters above.
-The full per-flag tables live in
-[references/onekgpd_commands.md](references/onekgpd_commands.md).
-
-### Variant-returning commands
-
-`select-*` return matching variants; `count-*` return an integer count.
-
--   `count-variants` — count variants in a region, cohort-wide.
--   `select-variants` — select variants in a region, cohort-wide. Use `--limit N`
-    (hard cap, default 200) **or** `--page-size N` (retrieve the full set in
-    pages); the two are mutually exclusive. The summary flags `truncated` when
-    the cap is reached.
--   `count-variants-in-samples` — as `count-variants`, restricted to
-    `--samples NAME1,NAME2,...` (required).
--   `select-variants-in-samples` — as `select-variants`, restricted to
-    `--samples NAME1,NAME2,...` (required).
-
-Each returned variant carries these 22 keys: `chr`, `start`, `end`, `ref`,
-`alt`, `af`, `ac`, `an`, `hom_samples`, `het_samples`, `mis_samples`,
-`hom_samples_fx`, `het_samples_fx`, `mis_samples_fx`, `hom_samples_mxy`,
-`het_samples_mxy`, `mis_samples_mxy`, `gnomad_exomes_af`, `gnomad_genomes_af`,
-`am_score`, `amino_acids`, `biallelic`.
-ClinVar significance and VEP consequence are filter criteria only and are not
-returned. Full schema:
-[references/onekgpd_commands.md](references/onekgpd_commands.md).
-
-### Sample-returning commands
-
--   `count-samples` — count individuals carrying a matching variant in a region.
--   `select-samples` — list the names of individuals carrying a matching variant.
-    Supports `--skip N` and `--limit N`. Returns names only; to see which
-    variants qualified an individual, feed the names into
-    `select-variants-in-samples`.
-
-### Homozygous-reference commands
-
-Single position via `--chrom` + `--position` (not a region).
-
--   `count-samples-hom-ref` — count individuals with a 0/0 call at the position.
-    The count is a sentinel: `-1` = no variant exists at that position at all;
-    `0` = a variant exists but no individual is homozygous reference; `>0` = the
-    number of homozygous-reference individuals. The summary states which case.
--   `select-samples-hom-ref` — list the individuals with a 0/0 call at the position.
-
-### Relatedness command
-
--   `kinship --sample1 NAME --sample2 NAME` — relatedness between two named
-    individuals: the degree (`TWINS_MONOZYGOTIC` / `FIRST_DEGREE` /
-    `SECOND_DEGREE` / `THIRD_DEGREE` / `UNRELATED`) and the KING kinship
-    coefficient (`phi_bwf`).
-
-### Dataset metadata command
-
--   `dataset-info` — dataset totals: `samples_total` (3,202), female/male split,
-    `variants_total`, `assembly` (GRCh38), and the cohort breakdown. No region
-    required; doubles as a connectivity check.
-
-## Sample & population metadata (offline)
-
-Population, sex, pedigree, and superpopulation questions are answered by a second
-script, `scripts/onekgpd_meta.py`, from a data file bundled in the skill — **no
-network, no credentials, no coordinates**. The sample IDs are the same names the
-variant commands use, so the two layers compose (e.g. pick a cohort by population,
-then query its variants). Run `uv run scripts/onekgpd_meta.py <command>`.
-
-The cohort has 5 superpopulations (`AFR`, `AMR`, `EAS`, `EUR`, `SAS`) and 26
-populations. Population/superpopulation values match **case-insensitively** by
-short code or full name; **sample IDs are case-sensitive**.
-
--   `sample-metadata --samples NA19240,HG00096` — family, gender, parents,
-    children, population, superpopulation, and phase3 status for the given samples.
--   `list-populations` — all 26 populations with superpopulation and sample count
-    (use to discover valid values).
--   `list-superpopulations` — the 5 superpopulations with sample count and
-    constituent populations.
--   `population-stats --populations YRI [--populations CHS …]` — per-population sex
-    split, phase3 count, and trio membership. Repeat `--populations` for multiple
-    values (full names contain commas, so they are not comma-separated).
--   `superpopulation-summary --superpopulations EAS [--superpopulations EUR …]` —
-    per-superpopulation totals with a per-population breakdown.
--   `select-samples-by-population --population YRI` and/or `--superpopulation AFR`,
-    with optional `--skip`/`--limit` (default 0 / 50, max 3202) — the sample IDs in
-    a population and/or superpopulation; both given intersects. Feed the names into
-    `select-variants-in-samples` to see their variants.
-
-See [references/onekgpd_commands.md](references/onekgpd_commands.md) for full
-argument tables and JSON output schemas.
-
-## Typical Workflows
-
-### Which individuals, then which variants they carry
-
-```bash
-# Step 1: resolve gene -> verified GRCh38 region (authoritative source).
-# Step 2: count individuals carrying a qualifying variant in the region.
-uv run scripts/onekgpd_api.py count-samples \
-  --chrom <chr> --start <start> --end <end> \
-  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
-  --output /tmp/n.json
-# Step 3: list those individuals.
-uv run scripts/onekgpd_api.py select-samples \
-  --chrom <chr> --start <start> --end <end> \
-  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
-  --output /tmp/who.json
-# Step 4: for that set of individuals, see the actual variants they carry.
-uv run scripts/onekgpd_api.py select-variants-in-samples \
-  --chrom <chr> --start <start> --end <end> \
-  --samples <name1,name2,...> \
-  --consequence MISSENSE_VARIANT --alpha-missense-class AM_LIKELY_PATHOGENIC \
-  --output /tmp/variants.json
-```
-
-### Homozygous-reference carriers at a position of interest
-
-```bash
-# After identifying a position of interest (verified coordinate):
-uv run scripts/onekgpd_api.py count-samples-hom-ref \
-  --chrom <chr> --position <pos> --output /tmp/homref_n.json
-uv run scripts/onekgpd_api.py select-samples-hom-ref \
-  --chrom <chr> --position <pos> --output /tmp/homref.json
-```
-
-## Common Mistakes
-
--   **Mistake:** Querying with an unverified coordinate.
-    **Fix:** Always resolve gene/feature → GRCh38 against an authoritative
-    source first.
-    A misplaced region returns results for an unintended location without error.
--   **Mistake:** Calling a selection command before its counting command.
-    **Fix:** Count first; selection result sets can be large.
--   **Mistake:** Assuming a GRCh37 coordinate will work.
-    **Fix:** The dataset is GRCh38 only.
-
-## References
-
--   [references/onekgpd_commands.md](references/onekgpd_commands.md) — full
-    per-command argument tables and the returned-variant output schema.
--   [references/annotation_vocabularies.md](references/annotation_vocabularies.md)
-    — the controlled-vocabulary terms accepted by the CSV filter flags
-    (consequence, impact, biotype, feature type, ClinVar significance,
-    AlphaMissense class, variant class).
--   1000 Genomes Project / IGSR: https://www.internationalgenome.org/
--   1000 Genomes Project dataset online: https://dnaerys.org/online/