gapit 0.5.2__tar.gz → 0.5.4__tar.gz

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

@@ -79,6 +79,7 @@ gapit/
 │   ├── db_ops.py        # db use-cases: fetch + list (shared CLI + MCP; no typer)
 │   ├── 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)
+│   ├── db_build_meta.py # `db build --tsv` metadata sidecar: parse + merge (shared by the build use-case)
 │   ├── 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

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

@@ -5,6 +5,60 @@ 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.4] - 2026-10-03
+
+### Added
+
+- **Rich progress bar on long batch runs** (stderr only; modeled on the gmlst UX).
+  Multi-file contig screening, the positional-FASTQ wildcard batch, and
+  `gapit db fetch all` now show a spinner + bar + M/N + percent + elapsed bar on an
+  interactive stderr, with the description tracking the current file/sample/database and
+  replacing the per-file stderr notes while it runs. Under `--quiet` or a non-TTY stderr
+  (pipes, CI) the bar is disabled and today's plain notes print byte-identically; stdout
+  data streams are untouched in every case (the bar never captures stdout — rich's Live
+  redirection is pinned off), so output bytes are identical with the bar on or off.
+
+## [0.5.3] - 2026-10-03
+
+### Added
+
+- **Build-time exact-duplicate dedup for gene databases.** `gapit db build` (CLI and MCP)
+  and bundled materialization now drop records whose `(gene, sequence)` pair repeats an
+  earlier one — the FIRST copy is kept, a stderr note counts the drops when not
+  `--quiet`, and the build receipt gains an additive `duplicates_dropped` field (omitted
+  when 0, so no-duplicate receipts stay byte-identical). Records with identical sequences
+  under DIFFERENT gene names are kept (possible aliases); the provider fetch pipeline is
+  untouched (it already deduplicates upstream).
+
+### Fixed
+
+- **Bundled `ecoli_dec` regenerated 17 → 16 records (the 26ECO0094 `sth` divergence).**
+  The panel carried `estA3` (M18346.1) and `estA4` (J03311.1) as byte-identical 219 bp
+  `sth` sequences, so reads mode — which aggregates per record — reported two `sth` rows
+  while the blastn contig path's `-culling_limit 1` kept one. Build-time dedup drops the
+  `estA4` copy; both surfaces now agree on the single `estA3` `sth` row (verified on
+  26ECO0094 reads and assembly; `astA`/`uidA` unchanged).
+
+### Docs
+
+- Audited docs refresh (no behavior change): README and FAQ now state the shipped
+  stance — the abricate-compatible contig surface is a frozen baseline and the parity
+  harness is a regression reference, not a release gate; the false "nothing is bundled"
+  claims in FAQ/installation are replaced with the six in-wheel audited bundles
+  (materialized on first use). The `gapit typing` TSV column order in every example is
+  corrected to `FILE SCHEME PHENOTYPE GENES CONFIDENCE SCORE RUNNER_UP NOTES`; summary
+  examples now paste the real default `+`/`-` cells; schema rosters add `floors`
+  (eleven documents) and the `gapit.dblist/1` field table gains `kind`; the database
+  catalog is described as its real 21-row self (12 gene + 7 kaptive cluster + the
+  `ecoli_dec`/`lm_doumith` bundles); the quickstart gains a "Type your samples"
+  tutorial (two-stage designation, the screen|typing pipe, wildcard-FASTQ auto-pairing)
+  and uses `gapit setupdb` as the bootstrap path; `gapit screen` docs list
+  `--min-identity`/`-I` and `--min-mapq`/`-M`; the `gapit db build` reference lists
+  `--kind`/`-k`, `--typing`/`-T`, and `--floors`/`-F`. New FAQ entries: two-stage
+  typing designation, per-gene identity floors (the `pic` case), wildcard-FASTQ
+  auto-pairing. All fixes applied to the English pages and their `.zh.md` mirrors; all
+  replacement examples re-run against the real CLI.
+
 ## [0.5.2] - 2026-10-03
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gapit
-Version: 0.5.2
+Version: 0.5.4
 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/
@@ -37,9 +37,11 @@ JSON and Markdown.
 
 ## Why gapit
 
-- **Drop-in abricate replacement.** Same BLAST pipeline, same hit rules, abricate-format
-  TSV on stdout. Parity with abricate 1.4.0 is a release gate, checked by diffing gene
-  calls against real abricate (`pixi run -e parity parity`).
+- **Frozen abricate-compatible baseline.** Contig screening keeps the same BLAST
+  pipeline, hit rules, and abricate-format TSV as a frozen baseline surface for existing
+  pipelines. From v0.5.0 gapit pursues its own contract; abricate parity is no longer a
+  release gate — the parity harness (`pixi run -e parity parity`) remains a regression
+  reference for that frozen surface.
 - **Machine-readable by design.** Versioned output schemas (`gapit.report/1`,
   `gapit.reads/1`, `gapit.summary/1`), self-describing via `gapit schema`, typed JSON error
   envelopes on stderr, documented exit codes. An agent can discover the whole contract
@@ -109,12 +111,16 @@ presence defaults to 90% alignment breadth (`--min-breadth 90`).
 ## Databases
 
 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
-six content-provenance-audited exceptions that ship inside the package (`ecoli_dec` and
+`~/.local/share/gapit/db` (override per call with `--datadir`). Twenty-one databases are
+built into the catalog — twelve gene providers, seven kaptive cluster providers, and the
+two typed bundles `ecoli_dec` and `lm_doumith`. All of them build on `gapit db fetch`,
+which downloads from upstream — and six content-provenance-audited ones also 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
+BSD-3-Clause / MIT), materialized into the datadir on first use with zero network; the
+bundled `ecoli_dec` additionally carries per-gene identity floors (`floors.json`, `pic`
+at 90%) that reads mode applies before presence calls. 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
 — and `db fetch <name>` always refreshes a bundled name from the latest upstream.
@@ -128,8 +134,10 @@ redistribution inside an MIT-licensed distribution, so everything else is fetch-
 | `plasmidfinder` | CGE PlasmidFinder replicons | nucl |
 | `megares` | MEGARes antimicrobial resistance genes | nucl |
 | `ecoh` | E. coli O and H antigens (srst2 EcOH) | nucl |
+| `ecoli_dec` | Diarrheagenic E. coli marker panel (GB 4789.6 + risk-monitoring designation) | nucl |
 | `vfdb` | VFDB virulence factors (set A, nucleotide) | nucl |
 | `ecoli_vf` | E. coli virulence factors | nucl |
+| `lm_doumith` | Listeria monocytogenes serogrouping (Doumith 2004) | nucl |
 | `bacmet2` | BacMet2 biocide/resistance genes (protein) | prot |
 | `victors` | Victors virulence factors | nucl |
 | `upec_expec_vf` | UPEC/ExPEC virulence genes | nucl |

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

@@ -7,9 +7,11 @@ JSON and Markdown.
 
 ## Why gapit
 
-- **Drop-in abricate replacement.** Same BLAST pipeline, same hit rules, abricate-format
-  TSV on stdout. Parity with abricate 1.4.0 is a release gate, checked by diffing gene
-  calls against real abricate (`pixi run -e parity parity`).
+- **Frozen abricate-compatible baseline.** Contig screening keeps the same BLAST
+  pipeline, hit rules, and abricate-format TSV as a frozen baseline surface for existing
+  pipelines. From v0.5.0 gapit pursues its own contract; abricate parity is no longer a
+  release gate — the parity harness (`pixi run -e parity parity`) remains a regression
+  reference for that frozen surface.
 - **Machine-readable by design.** Versioned output schemas (`gapit.report/1`,
   `gapit.reads/1`, `gapit.summary/1`), self-describing via `gapit schema`, typed JSON error
   envelopes on stderr, documented exit codes. An agent can discover the whole contract
@@ -79,12 +81,16 @@ presence defaults to 90% alignment breadth (`--min-breadth 90`).
 ## Databases
 
 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
-six content-provenance-audited exceptions that ship inside the package (`ecoli_dec` and
+`~/.local/share/gapit/db` (override per call with `--datadir`). Twenty-one databases are
+built into the catalog — twelve gene providers, seven kaptive cluster providers, and the
+two typed bundles `ecoli_dec` and `lm_doumith`. All of them build on `gapit db fetch`,
+which downloads from upstream — and six content-provenance-audited ones also 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
+BSD-3-Clause / MIT), materialized into the datadir on first use with zero network; the
+bundled `ecoli_dec` additionally carries per-gene identity floors (`floors.json`, `pic`
+at 90%) that reads mode applies before presence calls. 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
 — and `db fetch <name>` always refreshes a bundled name from the latest upstream.
@@ -98,8 +104,10 @@ redistribution inside an MIT-licensed distribution, so everything else is fetch-
 | `plasmidfinder` | CGE PlasmidFinder replicons | nucl |
 | `megares` | MEGARes antimicrobial resistance genes | nucl |
 | `ecoh` | E. coli O and H antigens (srst2 EcOH) | nucl |
+| `ecoli_dec` | Diarrheagenic E. coli marker panel (GB 4789.6 + risk-monitoring designation) | nucl |
 | `vfdb` | VFDB virulence factors (set A, nucleotide) | nucl |
 | `ecoli_vf` | E. coli virulence factors | nucl |
+| `lm_doumith` | Listeria monocytogenes serogrouping (Doumith 2004) | nucl |
 | `bacmet2` | BacMet2 biocide/resistance genes (protein) | prot |
 | `victors` | Victors virulence factors | nucl |
 | `upec_expec_vf` | UPEC/ExPEC virulence genes | nucl |

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

@@ -13,12 +13,12 @@ Version, as one JSON line:
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.5.2"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.5.4"}
 ```
 
-Output schemas. Ten documents are introspectable: `report`, `typing_result`, `reads`,
+Output schemas. Eleven documents are introspectable: `report`, `typing_result`, `reads`,
 `reads2`, `cluster`, `summary`, `error`, `version`, plus the database-side
-documents `features` and `typing`. Each prints its full JSON Schema:
+documents `features`, `typing`, and `floors`. Each prints its full JSON Schema:
 
 ```console
 $ gapit schema report          # gapit.report/1 (contig screening)
@@ -31,6 +31,7 @@ $ gapit schema error           # gapit.error/1
 $ gapit schema version         # gapit.version/1
 $ gapit schema features        # gapit.features/1 (cluster db feature table)
 $ gapit schema typing          # gapit.typing/2 (db scoring spec; /1 still reads)
+$ gapit schema floors          # gapit.floors/1 (per-gene identity floors, reads mode)
 ```
 
 For example, `gapit schema version` (real output):
@@ -62,7 +63,7 @@ For example, `gapit schema version` (real output):
 ```
 
 Databases: the database catalog and install state (`gapit db list --json`; real output,
-first two of twelve shown, trimmed):
+first two of twenty-one shown, trimmed):
 
 ```console
 $ gapit db list --json

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

@@ -12,11 +12,11 @@ gapit 生来就是被程序驱动的。每个输出都以机器可读为设计
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.5.2"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.5.4"}
 ```
 
-输出 schema。十个文档可自省：`report`、`typing_result`、`reads`、`reads2`、`cluster`、
-`summary`、`error`、`version`，外加数据库侧文档 `features` 和 `typing`。每个都打印完整的
+输出 schema。十一个文档可自省：`report`、`typing_result`、`reads`、`reads2`、`cluster`、
+`summary`、`error`、`version`，外加数据库侧文档 `features`、`typing` 和 `floors`。每个都打印完整的
 JSON Schema：
 
 ```console
@@ -30,6 +30,7 @@ $ gapit schema error           # gapit.error/1
 $ gapit schema version         # gapit.version/1
 $ gapit schema features        # gapit.features/1 (cluster db feature table)
 $ gapit schema typing          # gapit.typing/2 (db scoring spec; /1 still reads)
+$ gapit schema floors          # gapit.floors/1 (per-gene identity floors, reads mode)
 ```
 
 例如 `gapit schema version`（真实输出）：
@@ -60,7 +61,7 @@ $ gapit schema typing          # gapit.typing/2 (db scoring spec; /1 still reads
 }
 ```
 
-数据库：数据库目录与安装状态（`gapit db list --json`；真实输出，十二个中的前两
+数据库：数据库目录与安装状态（`gapit db list --json`；真实输出，二十一个中的前两
 个，有删节）：
 
 ```console

{gapit-0.5.2 → gapit-0.5.4}/docs/custom-db.md

@@ -20,6 +20,9 @@ gapit db build NAME FASTA [OPTIONS]
 | `FASTA` (argument) | path | Input FASTA: plain, abricate `~~~`, or `gapit\|` headers, detected per record (`.gz`/`.bz2` accepted). |
 | `--tsv` | path | Metadata TSV: header row with `gene`/`accession`/`function` columns. |
 | `--dbtype` | `nucl` or `prot` | Force the molecule type (default: auto-detect from the sequences). |
+| `--kind` / `-k` | `gene` or `cluster` | Force the database kind (default: auto-detect from the input suffix; a disagreement is a usage error). |
+| `--typing` / `-T` | path | `gapit.typing/1` or `/2` scoring spec: validated, copied into the db as `typing.json`, recorded in its manifest. |
+| `--floors` / `-F` | path | `gapit.floors/1` per-gene identity floors for reads-mode presence: validated, copied into the db as `floors.json` (gene builds only). |
 | `--datadir` | path | Database directory (default: `$GAPIT_DATADIR`, then `~/.local/share/gapit/db`). |
 | `--description` | text | Default product for records whose FASTA header has no description text. |
 | `--force` | flag | Overwrite the database if it already exists. |
@@ -293,8 +296,8 @@ $ cat sample2.tsv
 sample2.fa	SAM002	16	255	+	labcur2	1-240/240	===============	0/0	100.00	100.00	labmeta	LAB-0002	synthetic macrolide esterase	macrolide
 $ gapit summary sample1.tsv sample2.tsv
 #FILE	NUM_FOUND	labcur1	labcur2
-sample1.tsv	1	100.00	.
-sample2.tsv	1	.	100.00
+sample1.tsv	1	+	-
+sample2.tsv	1	-	+
 ```
 
 ## Rules and edge behavior

{gapit-0.5.2 → gapit-0.5.4}/docs/custom-db.zh.md

@@ -22,6 +22,9 @@ gapit db build NAME FASTA [OPTIONS]
 | `FASTA`（位置参数） | path | 输入 FASTA：plain、abricate `~~~` 或 `gapit\|` 表头，逐记录检测（接受 `.gz`/`.bz2`）。 |
 | `--tsv` | path | 元数据 TSV：带 `gene`/`accession`/`function` 列的表头行。 |
 | `--dbtype` | `nucl` 或 `prot` | 强制分子类型（默认：从序列自动检测）。 |
+| `--kind` / `-k` | `gene` 或 `cluster` | 强制数据库类型（默认：从输入后缀自动检测；与后缀不一致是用法错误）。 |
+| `--typing` / `-T` | path | `gapit.typing/1` 或 `/2` 评分规范：先校验，再复制进数据库成为 `typing.json`，并记入其 manifest。 |
+| `--floors` / `-F` | path | `gapit.floors/1` 逐基因一致性下限，用于 reads 模式的存在判定：先校验，再复制进数据库成为 `floors.json`（仅限基因库构建）。 |
 | `--datadir` | path | 数据库目录（默认：`$GAPIT_DATADIR`，然后 `~/.local/share/gapit/db`）。 |
 | `--description` | 文本 | FASTA 表头没有描述文本的记录的默认产物。 |
 | `--force` | 开关 | 数据库已存在时覆盖。 |
@@ -320,8 +323,8 @@ $ cat sample2.tsv
 sample2.fa	SAM002	16	255	+	labcur2	1-240/240	===============	0/0	100.00	100.00	labmeta	LAB-0002	synthetic macrolide esterase	macrolide
 $ gapit summary sample1.tsv sample2.tsv
 #FILE	NUM_FOUND	labcur1	labcur2
-sample1.tsv	1	100.00	.
-sample2.tsv	1	.	100.00
+sample1.tsv	1	+	-
+sample2.tsv	1	-	+
 ```
 
 ## 规则与边缘行为

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

@@ -78,6 +78,7 @@ $ gapit db list --json
       "description": "ARG-ANNOT acquired resistance genes",
       "dbtype": "nucl",
       "installed": true,
+      "kind": "gene",
       "records": 2224
     },
     {
@@ -86,6 +87,7 @@ $ gapit db list --json
       "description": "BacMet2 experimentally confirmed biocide/resistance genes (protein)",
       "dbtype": "prot",
       "installed": true,
+      "kind": "gene",
       "records": 746
     },
     {
@@ -94,6 +96,7 @@ $ gapit db list --json
       "description": "CARD protein homolog resistance models",
       "dbtype": "nucl",
       "installed": true,
+      "kind": "gene",
       "records": 6059
     }
   ]
@@ -108,6 +111,7 @@ $ gapit db list --json
 | `providers[].vendor` | string | Upstream maintainer organisation (NCBI, DTU CGE, Kaptive (klebgenomics), ...) |
 | `providers[].description` | string | Short content summary |
 | `providers[].dbtype` | string | `nucl` (screened with blastn) or `prot` (screened with blastx) |
+| `providers[].kind` | string | `gene` (per-gene BLAST screening) or `cluster` (minimap2 locus screening, [screen.md](./screen.md#cluster-databases-kind-cluster)) |
 | `providers[].installed` | boolean | True when a manifest exists in the datadir |
 | `providers[].records` | integer | Record count, omitted when the database isn't installed |
 | `providers[].license` | string | Upstream content license, omitted unless the provider pins one (card, vfdb, ecoli_vf, kaptive) |
@@ -130,7 +134,7 @@ accept: a bundled database works out of the box.
 | Name | Content | Snapshot | Typed |
 |---|---|---|---|
 | `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`) |
+| `ecoli_dec` | Diarrheagenic E. coli marker panel (16 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 | — |
@@ -139,7 +143,9 @@ 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 `lm_doumith` panel was extracted the same
+and replaced during the 2026-10 audit, and the byte-identical `estA4` (J03311.1) copy of
+`estA3` (M18346.1) — one `sth` gene, one sequence — was dropped by the build pipeline's
+exact-duplicate dedup in the 2026-10 rebuild, leaving 16 records. 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
@@ -161,14 +167,16 @@ drift — comparing the wheel snapshots against latest upstream is future work.)
 
 **How materialization works.** The first `gapit screen ... --db <bundled-name>` against
 a datadir that does not hold the database builds it there automatically — one stderr note
-(`gapit: materializing bundled database ecoli_dec (17 records) into <datadir>`,
+(`gapit: materializing bundled database ecoli_dec (16 records) into <datadir>`,
 silenced by `--quiet`), then the standard gene-build pipeline: `records.jsonl`, the
 `sequences` FASTA with gapit/v1 headers, the BLAST index, the `typing.json` copy when the
-bundle ships one, and a manifest stamped `source: "bundled"`. Deterministic, zero
+bundle ships one, and a manifest stamped `source: "bundled"`. That pipeline — shared with
+`gapit db build` — drops exact `(gene, sequence)` duplicate records at build time (first
+kept; a stderr note and the receipt's `duplicates_dropped` count the drops). Deterministic, zero
 network. A missing datadir is created on this path only; `gapit setupdb` materializes
 every bundled database alongside indexing; re-running either is a no-op once the
 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
+`installed (16)` after — on all four listing surfaces (TSV, rich table, `--json`, MCP
 `db_list`).
 
 ### Listeria serogrouping (`lm_doumith`)
@@ -204,7 +212,7 @@ honest answer for everything the five markers cannot resolve.
 ## Checking database freshness
 
 `gapit db outdated` reports every installed database's age against the staleness
-threshold. Against a fully installed datadir (output trimmed to three of twelve rows):
+threshold. Against a fully installed datadir (output trimmed to three of twenty-one rows):
 
 ```console
 $ gapit db outdated --days 30
@@ -488,7 +496,7 @@ versions. A real one, from the plasmidfinder database:
   "upstream_version": "",
   "tool": {
     "name": "gapit",
-    "version": "0.5.2"
+    "version": "0.5.4"
   },
   "makeblastdb_version": "blastn: 2.17.0+",
   "minimap2_version": "2.31-r1302"

{gapit-0.5.2 → gapit-0.5.4}/docs/databases.zh.md

@@ -76,6 +76,7 @@ $ gapit db list --json
       "description": "ARG-ANNOT acquired resistance genes",
       "dbtype": "nucl",
       "installed": true,
+      "kind": "gene",
       "records": 2224
     },
     {
@@ -84,6 +85,7 @@ $ gapit db list --json
       "description": "BacMet2 experimentally confirmed biocide/resistance genes (protein)",
       "dbtype": "prot",
       "installed": true,
+      "kind": "gene",
       "records": 746
     },
     {
@@ -92,6 +94,7 @@ $ gapit db list --json
       "description": "CARD protein homolog resistance models",
       "dbtype": "nucl",
       "installed": true,
+      "kind": "gene",
       "records": 6059
     }
   ]
@@ -106,6 +109,7 @@ $ gapit db list --json
 | `providers[].vendor` | string | 上游维护机构（NCBI、DTU CGE、Kaptive (klebgenomics) 等） |
 | `providers[].description` | string | 内容简述 |
 | `providers[].dbtype` | string | `nucl`（用 blastn 筛查）或 `prot`（用 blastx 筛查） |
+| `providers[].kind` | string | `gene`（逐基因 BLAST 筛查）或 `cluster`（minimap2 位点筛查，见 [screen.md](./screen.md)） |
 | `providers[].installed` | boolean | 数据目录里存在 manifest 时为 true |
 | `providers[].records` | integer | 记录数，数据库未安装时省略 |
 | `providers[].license` | string | 上游内容许可证，仅提供商声明时出现（card、vfdb、ecoli_vf、kaptive） |
@@ -125,7 +129,7 @@ abricate `--list` 的逐字节一致性。）见 [outputs.md](./outputs.md)。
 | 名称 | 内容 | 快照日期 | 分型 |
 |---|---|---|---|
 | `ecoh` | 大肠杆菌 O/H 抗原基因（597 条记录，srst2 EcOH） | 2026-10-02 | — |
-| `ecoli_dec` | 致腹泻大肠杆菌标志基因面板（17 条记录，GB 4789.6 + 风险监测判定） | 2026-10-02 | `gapit.typing/2`（`gb4789_6`、`risk_monitoring` 双方案） |
+| `ecoli_dec` | 致腹泻大肠杆菌标志基因面板（16 条记录，GB 4789.6 + 风险监测判定） | 2026-10-02 | `gapit.typing/2`（`gb4789_6`、`risk_monitoring` 双方案） |
 | `lm_doumith` | 单核细胞增生李斯特菌血清群分型（5 条记录，Doumith 2004 标记） | 2026-10-03 | `gapit.typing/2`（方案 `doumith_serogroup`） |
 | `ncbi` | NCBI AMRFinderPlus 精选 AMR（8373 条记录） | 2026-10-02 | — |
 | `resfinder` | CGE ResFinder 获得性耐药基因（3206 条记录） | 2026-10-02 | — |
@@ -133,7 +137,9 @@ abricate `--list` 的逐字节一致性。）见 [outputs.md](./outputs.md)。
 
 **许可证来源声明。** `ecoli_dec` 的每条记录都取自公共领域的一级提交（NCBI
 RefSeq/GenBank/DDBJ 收录号，与权利方面板等位相同）；2026-10 审计中发现原面板里
-混入的两条 VFDB 来源记录已被移除并替换。`lm_doumith` 面板以同样方式取自公共领域
+混入的两条 VFDB 来源记录已被移除并替换；2026-10 重建时，构建管线的精确去重又丢弃了
+与 `estA3`（M18346.1）逐字节相同的 `estA4`（J03311.1）副本 —— 同一个 `sth` 基因、
+同一序列 —— 面板因此为 16 条记录。`lm_doumith` 面板以同样方式取自公共领域
 的 INSDC 记录（收录号见每条头部；反向互补标记已做链向校正，`lmo0737` 经与 EGD-e
 比对验证 100% 一致）。四个提供商快照（`ecoh`、`ncbi`、`resfinder`、
 `upec_expec_vf`）通过了 2026-10 对**全部**记录的内容级审计：
@@ -152,12 +158,14 @@ MIT —— 四者均允许随 MIT 许可的 wheel 再分发。回归测试锁定
 
 **物化机制。** 第一次 `gapit screen ... --db <内置库名>` 发现数据目录里没有该库
 时，会自动构建它 —— stderr 一行提示（`gapit: materializing bundled database
-ecoli_dec (17 records) into <datadir>`，`--quiet` 可静默），随后走标准基因库
+ecoli_dec (16 records) into <datadir>`，`--quiet` 可静默），随后走标准基因库
 构建管线：`records.jsonl`、gapit/v1 头部的 `sequences`、BLAST 索引、（库自带时）
-`typing.json` 副本，以及盖上 `source: "bundled"` 的 manifest。全程确定性、零
+`typing.json` 副本，以及盖上 `source: "bundled"` 的 manifest。该管线与
+`gapit db build` 共享，会在构建时丢弃精确重复的（基因, 序列）记录（保留首条；
+stderr 提示与回执中的 `duplicates_dropped` 计数）。全程确定性、零
 网络。仅这条路径会在数据目录缺失时自动创建它；`gapit setupdb` 在建索引的同时
 物化全部内置库；manifest 一旦存在，两者重跑都是无操作。`db list` 在物化前显示
-`bundled`、物化后显示 `installed (17)` —— 四个列表入口（TSV、rich 表格、
+`bundled`、物化后显示 `installed (16)` —— 四个列表入口（TSV、rich 表格、
 `--json`、MCP `db_list`）一致。
 
 ### 李斯特菌血清群分型（`lm_doumith`）
@@ -192,7 +200,7 @@ table.tsv`。
 ## 检查数据库新鲜度
 
 `gapit db outdated` 报告每个已安装数据库相对于过期阈值的年龄。对装满的数据
-目录（输出裁剪到十二行中的三行）：
+目录（输出裁剪到二十一行中的三行）：
 
 ```console
 $ gapit db outdated --days 30
@@ -466,7 +474,7 @@ manifest，来自 plasmidfinder 数据库：
   "upstream_version": "",
   "tool": {
     "name": "gapit",
-    "version": "0.5.2"
+    "version": "0.5.4"
   },
   "makeblastdb_version": "blastn: 2.17.0+",
   "minimap2_version": "2.31-r1302"

{gapit-0.5.2 → gapit-0.5.4}/docs/faq.md

@@ -5,11 +5,14 @@ the source or a live run.
 
 ## Is gapit a drop-in abricate replacement?
 
-For contig screening, yes: same BLAST pipeline, same hit rules, abricate-format
-TSV on stdout, byte-parity checked against real abricate on a corpus. It reads
-abricate-format databases (legacy `~~~` headers) as-is. The reverse does not
-hold: gapit-native databases (`gapit/v1` tagged headers) cannot be read by
-abricate. Details: `./databases.md`.
+Contig screening keeps the abricate surface on purpose: same BLAST pipeline, same hit
+rules, abricate-format TSV on stdout, byte-checked against real abricate on a corpus.
+From v0.5.0 that baseline is frozen rather than a release gate — gapit pursues its own
+contract (native JSON/Markdown, reads and cluster engines, typing), and the parity
+harness (`pixi run -e parity parity`) serves as a regression reference for the frozen
+surface. gapit reads abricate-format databases (legacy `~~~` headers) as-is. The
+reverse does not hold: gapit-native databases (`gapit/v1` tagged headers) cannot be
+read by abricate. Details: `./databases.md`.
 
 ## Why does a hit showing 80.00% coverage get filtered?
 
@@ -75,6 +78,15 @@ minimap2 cluster engine and reports one best-locus call per file, with
 per-gene verdicts and, on typed databases, a phenotype. Details:
 `./screen.md` and `./databases.md`.
 
+## How do I designate a pathotype or serogroup?
+
+Designation is two-stage on gene databases: screen with a typed database, then read
+the table back. The bundled `ecoli_dec` panel carries the dual-scheme DEC designation:
+`gapit screen -d ecoli_dec sample.fna -o result.tsv`, then `gapit typing result.tsv`
+— or pipe one straight into the other. Cluster databases are the exception: their
+designation is integrated into the screen itself (the `PHENOTYPE` column). Details:
+`./typing.md`.
+
 ## What is the difference between `--threads` and `--jobs`?
 
 `--threads` is BLAST worker threads inside one screening run (passed to
@@ -90,15 +102,35 @@ puts the sample key in the first `#SAMPLE` column; `--format json` (or `md`) giv
 versioned `gapit.reads/1` document instead:
 
 ```console
-$ gapit screen --r1 reads.fq --read-type sr --db tinyamr
-#SAMPLE	GENE	BREADTH%	DEPTH	READS	PRESENT	DATABASE	ACCESSION	PRODUCT	RESISTANCE
-reads.fq	tetX	97.70	2.09	12	yes	tinyamr	SYN-001	extended resistance determinant tetX	TETRACYCLINE
-$ gapit screen --r1 reads.fq --read-type sr --db tinyamr --format json
+$ gapit screen --r1 tests/data/reads/tetx_full.fq --read-type sr --db tinyreads
+#SAMPLE	GENE	BREADTH%	DEPTH	READS	PRESENT	DATABASE	ACCESSION	PRODUCT
+tests/data/reads/tetx_full.fq	tetX	100.00	2.30	12	yes	tinyreads	SYN-001	extended resistance determinant tetX
+$ gapit screen --r1 tests/data/reads/tetx_full.fq --read-type sr --db tinyreads --format json
 {"schema": "gapit.reads/1", ...}
 ```
 
 Reads mode: `./reads.md`.
 
+## Can I screen a wildcard of FASTQ files?
+
+Yes: when every positional file is FASTQ, `gapit screen` enters reads mode and
+auto-pairs samples from the filenames (`_R1`/`_R2`, `_1`/`_2` conventions), so
+`gapit screen -d ecoli_dec *.fq.gz -j 4` screens all samples concurrently with one
+command. Mixing FASTA and FASTQ positionals is a usage error; the pairing conventions
+and the per-sample output are documented in `./reads.md`.
+
+## What are per-gene identity floors?
+
+A database-side `floors.json` (`gapit.floors/1`) declares a minimum alignment identity
+per gene for reads-mode presence: alignments below the floor are dropped before
+breadth and depth are aggregated, so a close-but-not-exact homolog no longer over-calls
+the gene. The real case that motivated it: the SPATE-homolog `pic` in the bundled
+`ecoli_dec` panel read about 86.6% identity at 97.6% breadth and crossed the 90%
+presence threshold, while the blastn contig path correctly rejected it; the shipped
+floor (`pic` at 90) makes reads mode agree. Install one with `gapit db build --floors
+FILE` or by dropping the file into the db directory; a database without one screens
+byte-identically to before. Details: `./reads.md` and `./databases.md`.
+
 ## What is this "MISSING_DEPENDENCY" error?
 
 An external binary (blastn, makeblastdb, blastdbcmd, minimap2) is
@@ -113,16 +145,20 @@ PATH.
 
 ## What licenses apply to the databases?
 
-gapit itself is MIT-licensed. No database content ships inside the package: every
-provider downloads from upstream at fetch time, and the content keeps its original
-licenses (NCBI public domain, CARD's McMaster non-commercial terms, VFDB's CC BY-NC,
+gapit itself is MIT-licensed. Six audited, permissively licensed bundles ship inside
+the wheel (the public-domain `ecoli_dec` and `lm_doumith` panels plus the `ncbi`,
+`resfinder`, `ecoh`, `upec_expec_vf` snapshots: Apache-2.0 / BSD-3-Clause / MIT) and
+materialize into the datadir on first use; every other provider downloads from upstream
+at fetch time, and the content keeps its original
+licenses (CARD's McMaster non-commercial terms, VFDB's CC BY-NC,
 CGE, Kaptive's GPL-3.0, and so on); gapit does not relicense it. Providers that pin a
-license expose it in `gapit db list --json`. Details in SPEC.md §9.
+license expose it in `gapit db list --json`. Details in SPEC.md §9 and the
+[bundled section](./databases.md#bundled-databases-install-time-ready).
 
 ## How do I add a new database to the default set?
 
 Write a provider module and fetch it by name: every provider downloads from its
-upstream source at fetch time, transforms the records, and builds locally — nothing is
-ever bundled (upstream licenses such as CARD's or VFDB's forbid redistribution inside an
-MIT-licensed distribution). The header format, transforms, and build pipeline are
-specified in SPEC.md §11.
+upstream source at fetch time, transforms the records, and builds locally. Nothing
+beyond the six audited bundles ships in the wheel (upstream licenses such as CARD's or
+VFDB's forbid redistribution inside an MIT-licensed distribution). The header format,
+transforms, and build pipeline are specified in SPEC.md §11.