gapit 0.5.0__tar.gz → 0.5.2__tar.gz

{gapit-0.5.0 → gapit-0.5.2}/AGENTS.md

@@ -1,15 +1,18 @@
 # AGENTS.md — gapit
 
-> Python reimplementation of [abricate](https://github.com/tseemann/abricate): mass screening of
-> contigs and reads for known genes. **Agent-first**: every output is
-> machine-readable (JSON / Markdown) by design, not as an afterthought.
+> Python tool for mass screening of contigs and reads for known genes, with gene-cluster
+> typing and phenotype designation. Originally a reimplementation of
+> [abricate](https://github.com/tseemann/abricate); **from v0.5.0 onward gapit pursues its
+> own contract** — abricate parity is no longer a design goal. **Agent-first**: every
+> output is machine-readable (JSON / Markdown) by design, not as an afterthought.
 
 ## 1. Mission
 
 `gapit` answers one question: **which known genes are present in this assembly, and how confident
-are we?** It replaces abricate (Perl) with a modern, typed, testable Python tool that:
+are we?** A modern, typed, testable Python tool that:
 
-1. Produces byte-compatible TSV with abricate (drop-in replacement for existing pipelines).
+1. Ships an abricate-compatible contig TSV as the historical baseline surface (frozen
+   behavior, kept for existing pipelines), while new development follows gapit's own design.
 2. Adds first-class **JSON** and **Markdown** outputs so LLM agents and humans can consume
    results without parsing tab-delimited text.
 3. Exposes stable, versioned output contracts (schemas, exit codes, error envelopes) that
@@ -52,7 +55,7 @@ Every change must leave `lint`, `typecheck`, and `test` green.
 gapit/
 ├── AGENTS.md            # this file
 ├── PLAN.md              # development roadmap (phase-gated)
-├── SPEC.md              # distilled abricate behavior spec (source of truth for parity)
+├── SPEC.md              # frozen contract for the baseline surface (distilled from abricate)
 ├── pixi.toml
 ├── recipe/
 │   └── meta.yaml        # conda recipe (submission deferred)
@@ -77,6 +80,7 @@ gapit/
 │   ├── db_query_ops.py  # db use-cases: search + outdated over installed DBs (shared CLI + MCP)
 │   ├── db_build_ops.py  # db use-case: custom FASTA+TSV → gene db, GBK/GFF → cluster db (shared CLI + MCP)
 │   ├── gbfeatures.py    # GenBank FEATURES/ORIGIN parser → LocusFeatures/GeneFeature + gapit.features/1
+│   ├── gene_floors.py   # gapit.floors/1 per-gene identity floors: model, loader, build validation, reads gate
 │   ├── gffparse.py      # GFF3 parser (embedded ##FASTA or sidecar) → the same locus/gene models
 │   ├── typing_models.py # gapit.typing schema (rules + named schemes; /1 degrades to one default scheme)
 │   ├── typing_rules.py  # gapit.typing rule models (weighted_genes/exact_set/cluster_match/learned_linear) + reference checks
@@ -101,6 +105,7 @@ gapit/
 │   ├── reads.py          # FASTQ mode: minimap2 PAF parsing, coverage breadth/depth, presence
 │   ├── summary.py       # summary core: parse report tables into a gene matrix
 │   ├── cmd_screen.py    # `gapit screen` CLI (registered from cli.py)
+│   ├── cmd_screen_positionals.py # screen positional guard: db-name-as-file usage error
 │   ├── cmd_screen_reads_args.py # reads-mode CLI arg rules (comma split + flag rejects)
 │   ├── cmd_summary.py   # `gapit summary` CLI (registered from cli.py)
 │   ├── cmd_typing.py    # `gapit typing` CLI (registered from cli.py)
@@ -156,7 +161,7 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
 - **Formats**: `--format tsv|csv|json|md` (default `tsv` for abricate compatibility).
 - **JSON**: top-level `"schema": "gapit.report/1"`; schema introspectable via
   `gapit schema report | reads | reads2 | summary | list | error | version` (plus
-  `cluster | features | typing | typing_result`). Keys are snake_case,
+  `cluster | features | typing | typing_result | floors`). Keys are snake_case,
   units explicit (`identity_pct`, `coverage_pct`). Semver the schema; never rename or
   retype a field in a minor bump.
 - **Markdown**: YAML frontmatter (tool version, db, params, ISO-8601 UTC timestamp) + tables a
@@ -173,12 +178,12 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
   database fetch from the provider catalog (every provider downloads from upstream at fetch
   time — nothing catalog-side is bundled inside the wheel beyond the sanctioned exceptions,
   a license-compliance requirement: CARD/VFDB terms are non-commercial and Kaptive is GPL,
-  so none of those may ride an MIT distribution; the sanctioned exceptions are the five
+  so none of those may ride an MIT distribution; the sanctioned exceptions are the six
   content-provenance-audited bundles under `src/gapit/data/dbs/` — the public-domain
-  `ecoli_dec` panel plus four permissively licensed provider snapshots (`ncbi` public
-  domain, `resfinder` Apache-2.0, `ecoh` BSD-3-Clause, `upec_expec_vf` MIT; GPL/NC content
-  is never bundled) — materialized into the datadir on first use via `bundled.py`, with
-  `db fetch <name>` still the fresh-upstream refresh path),
+  `ecoli_dec` and `lm_doumith` panels plus four permissively licensed provider snapshots
+  (`ncbi` public domain, `resfinder` Apache-2.0, `ecoh` BSD-3-Clause, `upec_expec_vf`
+  MIT; GPL/NC content is never bundled) — materialized into the datadir on first use via
+  `bundled.py`, with `db fetch <name>` still the fresh-upstream refresh path),
   database listing,
   records.jsonl gene search, staleness
   report, custom FASTA→native-db build, GBK/GFF→cluster-db build (`--typing` installs a
@@ -200,7 +205,9 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
   committed files deliberately and review diffs like code.
 - **Parity harness**: `pixi run -e parity parity` (and `summary-parity`) runs real abricate
   (conda) and gapit over a small genome corpus and diffs the gene calls byte-for-byte (file,
-  gene, %identity, %coverage). Parity on the corpus is the release gate for v1.0.
+  gene, %identity, %coverage). **From v0.5.0 this is a regression reference for the frozen
+  baseline surface, not a release gate for new work** — new features need not check abricate
+  and may diverge deliberately.
 - Full suite + CI matrix 3.11/3.13/3.14; parity byte-diff is opt-in via the `parity` pixi env.
   Offline tests stay fast.
 
@@ -216,13 +223,15 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
   query contigs against one db → 15-field
   tabular hits → filter by identity / coverage thresholds → **dedup hits sharing identical
   `(contig, qstart, qend)`** (first/best BLAST row wins) → one TSV row per surviving hit.
-  abricate   does **not** merge overlapping intervals — do not "improve" this on the default path (the
-  opt-in `--merge-fragments` cross-contig extension is the one sanctioned exception:
-  `fragments.py`).
+  The default path does **not** merge overlapping intervals (frozen baseline behavior;
+  the opt-in `--merge-fragments` cross-contic extension in `fragments.py` is the sanctioned
+  exception).
 - Key computed fields: `%COVERAGE = 100*(length-gaps)/slen` (filtered unrounded, displayed
   `%.2f`), `%IDENTITY` (BLAST pident, never post-filtered), `COVERAGE_MAP` (15-char minimap),
-  `GAPS`. Exact formulas, the dedup rule, and the minimap arithmetic live in `SPEC.md` — when
-  abricate and intuition disagree, **abricate wins** (parity is a feature).
+  `GAPS`. Exact formulas, the dedup rule, and the minimap arithmetic live in `SPEC.md` — they
+  are **gapit's frozen contract** for the baseline surface: do not change them silently. New
+  surfaces (reads, cluster, typing) follow their own documented contracts and may diverge from
+  abricate by design.
 
 ## 8. Git & workflow
 

{gapit-0.5.0 → gapit-0.5.2}/CHANGELOG.md

@@ -5,6 +5,164 @@ All notable changes to gapit are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.2] - 2026-10-03
+
+### Added
+
+- **Per-gene identity floors for reads-mode presence (`gapit.floors/1`) — the db-driven
+  fix for the 26ECO0084 `pic` SPATE false positive.** A gene database may carry an
+  optional `floors.json` sidecar declaring a minimum alignment identity (%) per gene:
+  in reads mode, alignments to a floored gene below its floor are dropped BEFORE
+  aggregation, so breadth is recomputed from the surviving rows (a ~86.6%-identity,
+  97.59%-breadth SPATE homolog collapses below the presence threshold instead of
+  over-calling `pic`, matching the blastn contig verdict). **Strictly opt-in via
+  DATABASE metadata, not a CLI change**: a database without the sidecar screens
+  byte-identically to before, existing databases need nothing, and the blastn contig
+  path never reads floors (`--minid` already gates it). Floors compose conjunctively
+  with `gapit.reads/2` `--min-identity` (a row must clear both); `gapit.reads/1`
+  output shape is untouched (presence/breadth changes only for floored genes). New
+  module `gapit.gene_floors` (model registered as `gapit schema floors`), `gapit db
+  build NAME.fa --floors FILE` (gene builds only; cluster inputs reject it) installs a
+  validated copy — every listed gene must exist in the FASTA (`FLOORS_UNKNOWN_GENE`),
+  values in [0, 100] and structure per the schema (`FLOORS_MALFORMED`); dropping the
+  file into an existing db directory works too. The bundled `ecoli_dec` now ships
+  `{"genes": {"pic": 90.0}}` (true `pic` ≥95%; `astA` deliberately unfloored — true
+  alleles at 90.4–91% leave no margin), materialized with the bundle; MCP `screen_reads`
+  inherits the gate through the shared use-case.
+
+- **Bundled `lm_doumith`: Listeria monocytogenes serogrouping (Doumith 2004) — the sixth
+  bundled database.** Five markers extracted from public-domain INSDC records (`prs`,
+  `lmo0737`, `lmo1118`, `ORF2819`, `ORF2110`; strand-corrected, `lmo0737` verified against
+  EGD-e) behind the `gapit.typing/2` scheme `doumith_serogroup` (95/95 floors, `prs`
+  control gene, cutoff 1.0 / margin 0.0). Rules follow Doumith's multiplex-PCR table
+  (IIa = 1/2a·3a, IIc = 1/2c·3c, IIb = 1/2b·3b·7, IVb = 4b·4d·4e) extended with Huang
+  2011's 4b variant (`IVb-v`, declared before `IVb` so an lmo0737-carrying 4b profile
+  resolves to the variant); fallback `untypeable (4a/4c, atypical profile, or non-Lm
+  Listeria)`. Materializes on first screen like every bundle (zero network);
+  `tests/test_lm_doumith.py` pins the synthetic marker-subset matrix, the control gate,
+  the two-stage golden, and the bundled integration — the bundled roster grows to six
+  (discovery, red-flag scan, `db list`, and `setupdb` pins updated). Uppercase gene ids
+  (`ORF2819`/`ORF2110`) now ride a shipped database, locking that build/screen/typing
+   carry them verbatim.
+
+## [0.5.1] - 2026-10-03
+
+### Added
+
+- **Illumina FASTQ wildcard support: `gapit screen -d ecoli_dec *.gz` screens a shell glob
+  of reads without `--r1`/`--r2`** (rightsholder batch workflow). When every positional file
+  is FASTQ — a `.fastq`/`.fq` (± `.gz`) extension, or content sniffed as FASTQ when the
+  extension is ambiguous (via the existing `detect_read_kind`; known contig extensions and
+  garbage content keep today's contig pipeline untouched) — the command enters reads mode
+  and auto-pairs samples from filenames (`gapit.readpairs`, new): mate markers `_R1_001`/
+  `_R2_001` (bcl2fastq; an `_L00x` lane tag stays in the sample key), `_R1`/`_R2`, `_1`/`_2`,
+  `.1`/`.2`, all case-insensitive, longest suffix first, extensions `.fastq`/`.fq` ×
+  `.gz`/`.bz2` stripped before matching. The document carries one `files[]` entry per sample
+  (`reads[]` holds the sample key; per-gene metrics union over the sample's lanes; samples
+  sorted lexicographically). A file whose mate is missing, or with no detectable marker,
+  screens single-end with a quiet-respecting stderr `WARNING: no mate found for X —
+  screening single-end` — a warning, never an error. Duplicate identical basenames merge as
+  extra lanes of one sample. Mixing FASTA and FASTQ positionals is a usage error naming the
+  reads files; the reads-mode guards fire as on `--r1`/`--r2` (`--minid`/`--mincov`,
+  `--merge-fragments`, ... rejected), while `--min-identity`/`--min-mapq` now work on this
+  path (gapit.reads/2). `--read-type` keeps
+  the content-based preset resolution (`sr` for FASTQ). **`--jobs` is legal on this path
+  only** (the `--r1`/`--r2` single-sample invocation keeps the frozen rejection): samples
+  screen concurrently through a ThreadPoolExecutor whose positional yields keep output in
+  sample order byte-identical to `-j 1` (a failing sample raises at its position; the
+  `--jobs × --threads` oversubscription stderr note and the `--jobs >= 1` validation mirror
+   the contig path). **Output defaults to streaming tsv on this path**: the `#SAMPLE` header
+   leads, then each sample's gene rows land the moment its screening completes (`--format
+   csv` is the comma spelling), so a terminal shows per-sample results as they arrive; json
+   stays the opt-in single document written at the end (`--format json`; since the same
+   cycle's format-unification it is the opt-in on the `--r1`/`--r2` path too — see Changed).
+   md emits
+  a static frontmatter first (no run totals on this path — totals live in the JSON
+  document; the `--r1`/`--r2` render keeps its `files:`/`genes_found:` frontmatter
+  unchanged) then one `## <sample>` section per completed sample, head-of-line in sample
+  order under `--jobs`; `--output` writes the streamed chunks incrementally, so a
+  mid-batch failure persists samples 1..k-1 (tsv/md) and nothing at all (json). The
+  single-sample `--r1`/`--r2` path, the blastn contig path, and
+  the explicit `--aligner` routings are unchanged.
+- **`gapit typing` closes every TSV/MD row with a `GENES` column and `gapit.typing_result/1`
+  gains the additive per-file `genes` list** (schema stays `/1`; additive field, the
+  0.5.0 shape unchanged otherwise): the FILE's present gene names — the folded best hits the
+  designation ran on — sorted alphabetically and `;`-joined, repeated on each of the FILE's
+  scheme rows so each call is auditable against the hits that drove it. JSON carries the same
+  list as `files[].genes`.
+- **`gapit summary` reads its report table from stdin** — the pipe twin of `gapit typing`:
+  `gapit screen -d ecoli_dec *.fna --quiet | gapit summary` summarizes the batched screen
+  output straight off the pipe (a piped table is one input, so dutch mode applies — one row
+  per FILE value, byte-identical to summarizing the `-o`-written table). Stdin is read
+  whenever stdin is not a terminal; a bare invocation at a terminal keeps printing help;
+  `gapit summary -` is the explicit stdin marker (reads until EOF even under a terminal);
+  mixing `-` with file arguments is a usage error; non-UTF-8 stdin is the `SUMMARY_MALFORMED`
+  envelope naming `-`. The flag-but-no-file invocation (`summary --quiet` with a pipe) now
+  reads stdin instead of the former USAGE_ERROR.
+
+- **`--db` now also answers to the word-style alias `-db`** (on `gapit screen` and
+  `gapit db search`): `-db ecoli_dec` parses exactly like `--db ecoli_dec`, matching the
+  tar-style single-dash habit that previously misparsed as `-d b` + a positional. The
+  space-separated form is the supported one — click binds an attached `-dbecoli_dec` to
+  `-d` with value `becoli_dec` (the original failure), which the new guard below catches.
+
+### Fixed
+
+- **A positional argument that names a known database but is missing on disk now fails with
+  a targeted usage error (exit 2)** instead of the generic INPUT_NOT_FOUND (exit 5) plus a
+  starved downstream pipe: `gapit screen -d b ecoli_dec X.fna` (the stripped `-db` misparse
+  shape) reports `input file not found: 'ecoli_dec' — it is a database NAME; screen takes
+  databases via --db/-d/-db (e.g. --db ecoli_dec), positional arguments are genome files`.
+  Database names are matched against the provider catalog, bundled wheel content, and
+  installed datadir databases; ordinary missing files keep today's INPUT_NOT_FOUND.
+
+### Changed
+
+- **Breaking: `gapit screen` reads mode now defaults to streaming tsv on EVERY path** —
+  `--r1`/`--r2` and `--aligner minimap2` join the positional wildcard (and the blastn contig
+  path) with tsv as the human default; json/md are the explicit agent opt-ins. tsv is the
+  human default on every surface; json (`gapit.reads/1`/`2`) and md are the opt-ins for
+  agents. The default output is the same streaming `#SAMPLE` table the wildcard emits (one
+  chunk for the single sample; preamble + chunk compose exactly the buffered render);
+  `--format csv` is the comma spelling, `--format json`/`--format md` unchanged. The former
+  reads json default shipped ≤0.5.0 — invocations that relied on it must now pass
+  `--format json` (the tsv/csv reads-mode usage rejection is gone with it). The MCP
+  `screen`/`screen_reads` tools are unchanged: they pass `format` explicitly and still
+  return json by default (the agents' surface).
+
+### Added
+
+- `gapit summary --coverage` / `-c`: cells show %COVERAGE values (`;`-joined), reproducing the
+  classic abricate `--summary` cell shape byte-for-byte (the parity harness now runs in this
+  mode). `-ic` combines both metrics: each hit renders `identity/coverage`. `gapit typing` TSV/MD: the `GENES` column moved to follow `PHENOTYPE`
+  (was last; additive JSON `files[].genes` unchanged).
+
+### Changed
+
+- **Breaking**: `gapit summary` default cells are now the presence call (`+` / `-`) instead of
+  %COVERAGE values — pass `--coverage` to restore the previous cell shape.
+
+### Changed
+
+- **Project stance**: from v0.5.0 onward gapit pursues its own contract — abricate parity is no
+  longer a design goal. The contig TSV stays a frozen historical baseline (kept for existing
+  pipelines); the parity harness is a regression reference, not a release gate. New surfaces may
+  diverge from abricate by design. (AGENTS.md updated accordingly.)
+- Reads tables: the default lists present genes only (`--all-genes` / `-A` adds absent
+  calls) and the last column is `PRODUCT` (the `RESISTANCE` column is dropped from reads
+  tables; the contig table keeps it).
+
+### Fixed
+
+- **Reads-mode breadth accuracy (26ECO0071 astA)**: minimap2 now always runs with `--cs`
+  and the `sr` preset carries `-k11 -w6 -B2`. Two stacked defects silently dropped
+  diverged-allele genes from FASTQ screening (the assembly/BLAST path found astA, reads did
+  not): (1) the stock `sr` seed (k=21) finds no exact run on a ~90%-identity 117 bp gene —
+  zero alignments regardless of scoring; (2) minimap2's no-CIGAR mode emits clipped
+  alignment coordinates (57% vs 100% breadth on the same data). Presence calls and typing
+  inputs derived from reads screening change accordingly; the reads goldens were regenerated
+  deliberately.
+
 ## [0.5.0] - 2026-10-02
 
 ### Breaking

{gapit-0.5.0 → gapit-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gapit
-Version: 0.5.0
+Version: 0.5.2
 Summary: Mass screening of contigs and reads for known genes — agent-first Python reimplementation of abricate
 Project-URL: Homepage, https://github.com/indexofire/gapit
 Project-URL: Documentation, https://indexofire.github.io/gapit/
@@ -91,7 +91,7 @@ gapit screen --r1 ont_reads.fastq.gz --db ncbi --read-type map-ont --format json
 # Summarize report tables into a gene presence/absence matrix
 gapit summary *.tsv
 
-# Databases: five ship in-wheel and work instantly; the rest download from upstream on fetch
+# Databases: six ship in-wheel and work instantly; the rest download from upstream on fetch
 gapit db fetch all         # default set (card, vfdb)
 gapit db fetch ncbi
 gapit db list
@@ -111,8 +111,9 @@ presence defaults to 90% alignment breadth (`--min-breadth 90`).
 A database is a directory under the datadir, resolved from `$GAPIT_DATADIR`, then
 `~/.local/share/gapit/db` (override per call with `--datadir`). Twelve databases are built
 into the catalog; all of them download from upstream and build on `gapit db fetch` — with
-five content-provenance-audited exceptions that ship inside the package (`ecoli_dec` plus
-the `ncbi`, `resfinder`, `ecoh`, `upec_expec_vf` snapshots: public domain / Apache-2.0 /
+six content-provenance-audited exceptions that ship inside the package (`ecoli_dec` and
+`lm_doumith` plus the `ncbi`, `resfinder`, `ecoh`, `upec_expec_vf` snapshots: public
+domain / Apache-2.0 /
 BSD-3-Clause / MIT), materialized into the datadir on first use with zero network. Several
 upstream licenses (CARD's McMaster terms, VFDB's CC BY-NC, Kaptive's GPL-3.0) forbid
 redistribution inside an MIT-licensed distribution, so everything else is fetch-on-demand
@@ -204,6 +205,6 @@ guide, `CHANGELOG.md` the change history.
 
 gapit is MIT-licensed. It is a behavioral reimplementation of abricate (GPL-2.0) and
 copies no Perl code; abricate itself remains GPL-2.0. The only database content inside
-the package is the five audited, permissively licensed bundles under `src/gapit/data/dbs/`
+the package is the six audited, permissively licensed bundles under `src/gapit/data/dbs/`
 (public domain / Apache-2.0 / BSD-3-Clause / MIT); every other provider downloads from
 upstream at fetch time, under its own license (SPEC.md §9).

{gapit-0.5.0 → gapit-0.5.2}/README.md

@@ -61,7 +61,7 @@ gapit screen --r1 ont_reads.fastq.gz --db ncbi --read-type map-ont --format json
 # Summarize report tables into a gene presence/absence matrix
 gapit summary *.tsv
 
-# Databases: five ship in-wheel and work instantly; the rest download from upstream on fetch
+# Databases: six ship in-wheel and work instantly; the rest download from upstream on fetch
 gapit db fetch all         # default set (card, vfdb)
 gapit db fetch ncbi
 gapit db list
@@ -81,8 +81,9 @@ presence defaults to 90% alignment breadth (`--min-breadth 90`).
 A database is a directory under the datadir, resolved from `$GAPIT_DATADIR`, then
 `~/.local/share/gapit/db` (override per call with `--datadir`). Twelve databases are built
 into the catalog; all of them download from upstream and build on `gapit db fetch` — with
-five content-provenance-audited exceptions that ship inside the package (`ecoli_dec` plus
-the `ncbi`, `resfinder`, `ecoh`, `upec_expec_vf` snapshots: public domain / Apache-2.0 /
+six content-provenance-audited exceptions that ship inside the package (`ecoli_dec` and
+`lm_doumith` plus the `ncbi`, `resfinder`, `ecoh`, `upec_expec_vf` snapshots: public
+domain / Apache-2.0 /
 BSD-3-Clause / MIT), materialized into the datadir on first use with zero network. Several
 upstream licenses (CARD's McMaster terms, VFDB's CC BY-NC, Kaptive's GPL-3.0) forbid
 redistribution inside an MIT-licensed distribution, so everything else is fetch-on-demand
@@ -174,6 +175,6 @@ guide, `CHANGELOG.md` the change history.
 
 gapit is MIT-licensed. It is a behavioral reimplementation of abricate (GPL-2.0) and
 copies no Perl code; abricate itself remains GPL-2.0. The only database content inside
-the package is the five audited, permissively licensed bundles under `src/gapit/data/dbs/`
+the package is the six audited, permissively licensed bundles under `src/gapit/data/dbs/`
 (public domain / Apache-2.0 / BSD-3-Clause / MIT); every other provider downloads from
 upstream at fetch time, under its own license (SPEC.md §9).

{gapit-0.5.0 → gapit-0.5.2}/SPEC.md

@@ -265,8 +265,12 @@ preset resolution added 2026-09-19):
   `reads_mapped` = distinct query names with ≥1 primary alignment on the gene.
 - **Presence call**: `present = breadth_pct >= min_breadth`, `--min-breadth` default **90.0**
   (srst2-style). `--minid`/`--mincov` do NOT apply to reads mode.
-- **Output**: `--format json` (default in reads mode) emits `gapit.reads/1`; `--format md` the
-  Markdown form; `--format tsv|csv` in reads mode is a usage error (exit 2). Genes with zero
+- **Output**: the default (no `--format`) is the streaming **tsv** table (tsv is the human
+  default on every gapit surface; json/md are the agent opt-ins — breaking vs the ≤0.5.0
+  reads default, changed in the unreleased cycle; §10 describes gapit's own reads extension,
+  so this wording is normative for gapit only, not for the abricate parity path).
+  `--format json` emits `gapit.reads/1`; `--format md` the Markdown form; `--format csv` is
+  the comma spelling of the tsv table. Genes with zero
   mapped reads are omitted; entries sorted by `breadth_pct` descending, then gene name.
   `gapit.report/1` (contig mode) is unchanged and frozen. `gapit schema reads` introspects the
   new document.

{gapit-0.5.0 → gapit-0.5.2}/docs/agents.md

@@ -13,7 +13,7 @@ Version, as one JSON line:
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.5.0"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.5.2"}
 ```
 
 Output schemas. Ten documents are introspectable: `report`, `typing_result`, `reads`,

{gapit-0.5.0 → gapit-0.5.2}/docs/agents.zh.md

@@ -12,7 +12,7 @@ gapit 生来就是被程序驱动的。每个输出都以机器可读为设计
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.5.0"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.5.2"}
 ```
 
 输出 schema。十个文档可自省：`report`、`typing_result`、`reads`、`reads2`、`cluster`、

{gapit-0.5.0 → gapit-0.5.2}/docs/databases.md

@@ -44,6 +44,7 @@ vfdb	USTC (VFDB)	available	nucl	VFDB virulence factors (set A, nucleotide)
 victors	University of Chicago	available	nucl	Victors virulence factors
 ecoh	Holt lab (srst2)	bundled	nucl	E. coli O and H antigens (srst2 EcOH)
 ecoli_dec	gapit-curated (public-domain sources)	bundled	nucl	Diarrheagenic E. coli marker panel (GB 4789.6 + risk-monitoring designation)
+lm_doumith	gapit-curated (public-domain INSDC sources)	bundled	nucl	Listeria monocytogenes serogrouping (Doumith 2004)
 ncbi	NCBI	bundled	nucl	NCBI AMRFinderPlus (reference finder) curated AMR
 resfinder	DTU CGE	bundled	nucl	CGE ResFinder acquired resistance genes
 upec_expec_vf	FordeGenomics	bundled	nucl	UPEC/ExPEC virulence genes (FordeGenomics)
@@ -51,7 +52,7 @@ upec_expec_vf	FordeGenomics	bundled	nucl	UPEC/ExPEC virulence genes (FordeGenomi
 
 NAME is the database name you pass to `--db`; PROVIDER names the upstream maintainer
 organisation. STATUS reads `installed (N)` when `<datadir>/<name>/gapit-manifest.json`
-exists, with N the record count, otherwise `available`. The last five rows are the
+exists, with N the record count, otherwise `available`. The last six rows are the
 wheel-shipped [bundled](#bundled-databases-install-time-ready) databases, alphabetical:
 `bundled` before materialization, `installed (N)` after. Four of them (`ecoh`, `ncbi`,
 `resfinder`, `upec_expec_vf`) are also registry providers — such names render exactly
@@ -121,7 +122,7 @@ surface.) See [outputs.md](./outputs.md).
 
 Most databases download from upstream at `db fetch` time because their licenses forbid
 redistribution (see [Providers](#providers)). A small set of **bundled** databases ships
-inside the gapit wheel instead — five databases whose content provenance was audited
+inside the gapit wheel instead — six databases whose content provenance was audited
 record-by-record (public-domain sources, or Apache-2.0 / BSD-3-Clause / MIT panels;
 GPL and non-commercial content never rides the wheel). Nothing to download, nothing to
 accept: a bundled database works out of the box.
@@ -130,6 +131,7 @@ accept: a bundled database works out of the box.
 |---|---|---|---|
 | `ecoh` | E. coli O and H antigens (597 records, srst2 EcOH) | 2026-10-02 | — |
 | `ecoli_dec` | Diarrheagenic E. coli marker panel (17 records, GB 4789.6 + risk-monitoring designation) | 2026-10-02 | `gapit.typing/2` (schemes `gb4789_6`, `risk_monitoring`) |
+| `lm_doumith` | Listeria monocytogenes serogrouping (5 records, Doumith 2004 markers) | 2026-10-03 | `gapit.typing/2` (scheme `doumith_serogroup`) |
 | `ncbi` | NCBI AMRFinderPlus curated AMR (8373 records) | 2026-10-02 | — |
 | `resfinder` | CGE ResFinder acquired resistance genes (3206 records) | 2026-10-02 | — |
 | `upec_expec_vf` | UPEC/ExPEC virulence genes (77 records, FordeGenomics) | 2026-10-02 | — |
@@ -137,13 +139,15 @@ accept: a bundled database works out of the box.
 **License provenance.** Every `ecoli_dec` record was re-sourced from primary
 public-domain submissions (NCBI RefSeq/GenBank/DDBJ accessions, same alleles as the
 rightsholder panel); two VFDB-derived records found in the original panel were removed
-and replaced during the 2026-10 audit. The four provider snapshots (`ecoh`, `ncbi`,
-`resfinder`, `upec_expec_vf`) passed the 2026-10 content-level audit across **all**
-records: NCBI AMRFinderPlus content is public domain (US government work), the CGE
-ResFinder database is Apache-2.0, srst2's EcOH is BSD-3-Clause, and FordeGenomics'
-UPEC-ExPEC panel is MIT — all four permits redistribution inside the MIT-licensed wheel.
-A regression test pins that no `VF*` / `VFDB` / `ARO:` tags appear in any of the five
-bundles' headers.
+and replaced during the 2026-10 audit. The `lm_doumith` panel was extracted the same
+way from public-domain INSDC records (accessions in each header; reverse-complement
+markers strand-corrected, `lmo0737` verified 100% against EGD-e). The four provider
+snapshots (`ecoh`, `ncbi`, `resfinder`, `upec_expec_vf`) passed the 2026-10
+content-level audit across **all** records: NCBI AMRFinderPlus content is public
+domain (US government work), the CGE ResFinder database is Apache-2.0, srst2's EcOH
+is BSD-3-Clause, and FordeGenomics' UPEC-ExPEC panel is MIT — all four permits
+redistribution inside the MIT-licensed wheel. A regression test pins that no `VF*` /
+`VFDB` / `ARO:` tags appear in any of the six bundles' headers.
 
 **Snapshots are point-in-time.** Each snapshot's `sequences` file is byte-for-byte what
 `gapit db fetch <name>` produces from upstream on the snapshot date (a regression test
@@ -167,6 +171,36 @@ manifest exists. `db list` shows the database as `bundled` before that and
 `installed (17)` after — on all four listing surfaces (TSV, rich table, `--json`, MCP
 `db_list`).
 
+### Listeria serogrouping (`lm_doumith`)
+
+The typed bundle behind Listeria monocytogenes serogroup prediction: five markers —
+`prs`, `lmo0737`, `lmo1118`, `ORF2819`, `ORF2110` — screened with 95/95 identity and
+coverage floors and folded by the `doumith_serogroup` scheme into Doumith's multiplex-PCR
+groups (Doumith et al. 2004, J Clin Microbiol 42:3819), extended with the Huang 2011
+4b variant: `prs` gates the scheme as a genus-level control gene, `IIa` (1/2a or 3a),
+`IIc` (1/2c or 3c), `IIb` (1/2b, 3b or 7), `IVb` (4b, 4d or 4e), and `IVb-v` (the
+lmo0737-carrying 4b variant) — the same in-silico semantics as tools like LisSero.
+Designation runs through the two-stage pipeline: `gapit screen -o table.tsv --db
+lm_doumith`, then `gapit typing table.tsv`.
+
+Known limitations, carried on the calls as notes where relevant:
+
+- **4b/4d/4e are unresolvable at gene level** — the three serovars share every published
+  molecular marker; resolve by cgMLST or antisera.
+- **IVb-v is an emergent concern** — lmo0737 in an otherwise-4b profile (Huang 2011
+  "unusual 4b"; ST382/ST554 clones) is declared before IVb so the variant wins.
+- **EGD-e types as IIc** — the 1/2a reference genome carries lmo1118 and lands in IIc;
+  documented in Doumith 2004, not a tool artifact.
+- **Horizontal gene transfer cuts both ways** — the lineage-II lmo0737 cassette moves
+  between lineages, and rare HGT of the ORF markers can produce false IIb-looking
+  profiles; treat single-marker IIb calls in epidemiologically unlikely contexts with
+  care.
+- **`prs` is genus-level, not Lm-specific** — other Listeria species carry it; a prs+
+  isolate with no serogroup markers falls back rather than being called non-Listeria.
+
+The fallback call — `untypeable (4a/4c, atypical profile, or non-Lm Listeria)` — is the
+honest answer for everything the five markers cannot resolve.
+
 ## Checking database freshness
 
 `gapit db outdated` reports every installed database's age against the staleness
@@ -263,7 +297,7 @@ unknown `--db NAME` is a usage error (exit 2) listing what is installed.
 ## Providers
 
 Nineteen providers ship with gapit. Every one of them — `card` and `vfdb` included —
-downloads from its upstream source at fetch time: with the exception of the five
+downloads from its upstream source at fetch time: with the exception of the six
 audited, permissively licensed bundles above, nothing is bundled inside the package,
 because several upstream licenses (CARD's McMaster terms, VFDB's CC BY-NC, Kaptive's
 GPL-3.0) forbid redistribution inside an MIT-licensed distribution. The seven kaptive
@@ -410,6 +444,8 @@ $ gapit db install card.json \
   sequences             generated FASTA projection (gapit/v1 tagged headers)
   sequences.n*|p*       BLAST index built from sequences
   gapit-manifest.json   provenance sidecar, written last
+  typing.json           optional gapit.typing/1 or /2 scoring spec (typed dbs)
+  floors.json           optional gapit.floors/1 per-gene identity floors (reads mode)
 ```
 
 ### records.jsonl
@@ -452,7 +488,7 @@ versions. A real one, from the plasmidfinder database:
   "upstream_version": "",
   "tool": {
     "name": "gapit",
-    "version": "0.5.0"
+    "version": "0.5.2"
   },
   "makeblastdb_version": "blastn: 2.17.0+",
   "minimap2_version": "2.31-r1302"
@@ -479,6 +515,31 @@ versions. A real one, from the plasmidfinder database:
 `records.jsonl` and the manifest are file contracts. They never appear on stdout and are
 not registered with `gapit schema`.
 
+### floors.json — per-gene identity floors
+
+An optional sidecar declaring a MINIMUM alignment identity (%) per gene for reads-mode
+presence (schema `gapit.floors/1`, introspect with `gapit schema floors`; see
+[reads.md](./reads.md#per-gene-identity-floors-gapitfloors1-database-side) for the
+screening semantics and the `pic` worked example):
+
+```json
+{"schema": "gapit.floors/1", "default": null, "genes": {"pic": 90.0}}
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `schema` | string | Always `gapit.floors/1` |
+| `default` | number or null | Floor for genes not listed in `genes` (`null` = no floor) |
+| `genes` | object | `{gene: minimum identity %}`, values in [0, 100] |
+
+The file's presence IS the flag — no manifest field, no CLI switch. A database without
+the sidecar screens byte-identically to before (the floors are a db-driven opt-in, not a
+CLI contract change), and the blastn contig path never reads them. Built-in via
+`db build --floors` (next sections), or drop the file into an existing db directory; it
+is validated at screening time too (malformed content fails with `FLOORS_MALFORMED`,
+exit 4). The bundled `ecoli_dec` ships `{"genes": {"pic": 90.0}}` — the SPATE-homolog
+false-positive fix.
+
 ## Header formats and compatibility
 
 gapit reads two header formats and detects them per record:
@@ -581,6 +642,27 @@ gene	accession	function
 syn_betalac	SYN-0001	ampicillin;cephalosporin
 ```
 
+### Per-gene identity floors (`--floors`)
+
+`--floors FILE` installs a `gapit.floors/1` document as the database's `floors.json`
+sidecar — the per-gene minimum alignment identity for reads-mode presence (see
+[reads.md](./reads.md#per-gene-identity-floors-gapitfloors1-database-side)). The
+document is validated before any artifact is written: every gene in `genes` must exist
+in the FASTA (`FLOORS_UNKNOWN_GENE`, exit 4 — a floor for a missing gene is silently
+dead safety config), values must lie in [0, 100] and the structure parse
+(`FLOORS_MALFORMED`, exit 4). The file is then copied in byte-identical; the file's
+presence is the flag (no manifest field changes). Gene builds only — a GBK/GFF cluster
+input rejects `--floors` as a usage error.
+
+```console
+$ cat my_floors.json
+{"schema": "gapit.floors/1", "default": null, "genes": {"syn_betalac": 95.0}}
+$ gapit db build tinyamr my_genes.fa --datadir ./db --tsv my_meta.tsv --floors my_floors.json
+{"db":"tinyamr","records":2,"dbtype":"nucl","destination":"/tmp/opencode/gapit-build-demo/db/tinyamr"}
+$ cat ./db/tinyamr/floors.json
+{"schema": "gapit.floors/1", "default": null, "genes": {"syn_betalac": 95.0}}
+```
+
 ### Rebuilding
 
 Like `db fetch`, an existing database is never overwritten silently: