dsh-molbio-tools 0.22.2 → 0.24.1

package/index.mjs

@@ -2,9 +2,9 @@
  * dsh-molbio-tools/index.mjs
  *
  * DeepSeek Harness Cordis plugin: molecular-biology computation tools for the
- * model. Zero runtime dependencies — the only import is the sibling lib.mjs —
- * so the package is a pair of files that travel with an agent preset and can
- * be referenced by a relative plugin row (see README.md).
+ * model. Zero runtime dependencies — every import is a sibling module of this
+ * package — so the toolset travels with an agent preset and can be referenced
+ * by a package-name row (see README.md and rules.md rule 1).
  *
  * Every tool is pure computation: deterministic, no network, no filesystem.
  * The plugin publishes no service, so the preset row needs no isolate realm.
@@ -50,6 +50,8 @@ import {
 } from './cloning.mjs';
 import { readTraceFromBytes, verifySanger } from './sanger.mjs';
 import { CODON_HOSTS, codonOptimize, peptideDigest, proteinProperties } from './protein.mjs';
+import { chargeCurve, renderChargeCurve } from './protein-charge.mjs';
+import { dotplot, renderDotplot } from './dotplot.mjs';
 import { linearFit, renderBarChart, renderGel, renderScatterChart } from './plot.mjs';
 import {
   SERIES_COLORS,
@@ -65,7 +67,7 @@ import {
   renderVolcanoPlot,
   resolveTable,
 } from './charts.mjs';
-import { entryStats, parseFasta, parseFastq, toFasta } from './seqio.mjs';
+import { entryStats, parseFasta, parseFastq, toFasta, toFastq } from './seqio.mjs';
 import { addExperiment, addProtocol, loadRecords, recordPath, saveRecords, updateProtocol } from './records.mjs';
 import { toBibtex } from './papers.mjs';
 import { parseXml } from './snapgene.mjs';
@@ -123,6 +125,8 @@ import {
 import { openDefaultViewer } from './view.mjs';
 import { renderSvgToPng } from './svgpng.mjs';
 import { fastqQcReport, renderFastqQcReport } from './fastq-qc.mjs';
+import { screenContamination } from './contamination.mjs';
+import { trimFastq } from './fastq-trim.mjs';
 import { CODON_FREQUENCIES, codonUsageAnalysis } from './codon.mjs';
 import {
   DISTANCE_MODELS,
@@ -2140,7 +2144,7 @@ const plasmidMapTool = (ctx) => define({
   },
   // The map card in the transcript/panel reads this meta (see mapCardMeta).
   presentationMeta(_args, value) {
-    return mapCardMeta(value, rememberedMapSvg(value.svg_path));
+    return mapCardMeta(value, cardSvgFor(value.svg_path));
   },
   async execute(args, exec) {
     const sequence = normalizeSequence(args.sequence, 'plasmid sequence');
@@ -2182,7 +2186,7 @@ const plasmidMapTool = (ctx) => define({
       gc_skew: args.gc_skew === true,
     });
     const { file, viewed, attached } = await writeSvgFile(ctx, exec, args, svg, name);
-    rememberMapSvg(file, svg);
+    rememberCardSvg(file, svg);
     return mergeAttachedImage({
       svg_path: file,
       name,
@@ -2207,7 +2211,14 @@ function fsService(ctx) {
 
 async function readFileBytes(ctx, exec, path) {
   const fs = fsService(ctx);
-  const target = await fs.resolve(path);
+  // Resolve a model-supplied relative name against the SESSION workspace, not
+  // the provider's process cwd. `ctx.fs.resolve(path)` alone uses the backend
+  // default (process.cwd()), which is why tool-fs asks `workingDirectory` for
+  // the agent's cwd; the sandbox policy carries the same root here. Absolute
+  // paths are still accepted unchanged (workspaceFilePath leaves them alone).
+  const sandboxPolicyService = ctx.get('sandboxPolicy');
+  const policy = sandboxPolicyService?.resolve({ ...exec?.agent !== undefined ? { session: exec.agent.session } : {} });
+  const target = await fs.resolve(workspaceFilePath(path, exec, policy?.workspaceRoot), { signal: exec?.signal });
   return await fs.readBytes(target, exec?.signal, MAX_DNA_BYTES);
 }
 
@@ -2334,7 +2345,7 @@ const plasmidMapFileTool = (ctx) => define({
   },
   // The map card in the transcript/panel reads this meta (see mapCardMeta).
   presentationMeta(_args, value) {
-    return mapCardMeta(value, rememberedMapSvg(value.svg_path));
+    return mapCardMeta(value, cardSvgFor(value.svg_path));
   },
   async execute(args, exec) {
     const lower = args.path.toLowerCase();
@@ -2374,7 +2385,7 @@ const plasmidMapFileTool = (ctx) => define({
       gc_skew: args.gc_skew === true,
     });
     const { file, viewed, attached } = await writeSvgFile(ctx, exec, args, svg, name);
-    rememberMapSvg(file, svg);
+    rememberCardSvg(file, svg);
     return mergeAttachedImage({
       svg_path: file,
       name,
@@ -2423,22 +2434,40 @@ function mapCardMeta(value, svg) {
 }
 
 /**
- * Markup of the most recent maps, keyed by written path, so the card's
+ * Build the meta a figure card reads (sequence logo, gRNA map). Shared by both
+ * tools so the browser half has one shape to validate: `summary` is the header
+ * line, `extra` carries bounded presentation rows, and the markup travels only
+ * when it fits `CARD_SVG_MAX_BYTES`.
+ */
+function figureCardMeta({ figure, summary, svgPath, extra = {} }, svg) {
+  return {
+    kind: 'molbio-figure',
+    figure,
+    summary,
+    svg_path: svgPath,
+    svg_bytes: svg.length,
+    ...extra,
+    ...svg.length === 0 ? { svg_missing: true } : svg.length <= CARD_SVG_MAX_BYTES ? { svg } : { svg_omitted: true },
+  };
+}
+
+/**
+ * Markup of the most recent written figures, keyed by path, so a card's
  * projection never has to read a file back. Bounded on both axes — a handful of
- * maps, each at most `CARD_SVG_MAX_BYTES` — because this is a module-level
+ * figures, each at most `CARD_SVG_MAX_BYTES` — because this is a module-level
  * cache in a long-lived host process, not a store.
  */
-const recentMapSvg = new Map();
+const recentCardSvg = new Map();
 
-function rememberMapSvg(svgPath, svg) {
-  if (recentMapSvg.has(svgPath)) recentMapSvg.delete(svgPath);
-  recentMapSvg.set(svgPath, svg.length <= CARD_SVG_MAX_BYTES ? svg : '');
-  while (recentMapSvg.size > 8) recentMapSvg.delete(recentMapSvg.keys().next().value);
+function rememberCardSvg(svgPath, svg) {
+  if (recentCardSvg.has(svgPath)) recentCardSvg.delete(svgPath);
+  recentCardSvg.set(svgPath, svg.length <= CARD_SVG_MAX_BYTES ? svg : '');
+  while (recentCardSvg.size > 8) recentCardSvg.delete(recentCardSvg.keys().next().value);
 }
 
 /** The markup remembered for one written map ('' when it was too large or is gone). */
-function rememberedMapSvg(svgPath) {
-  return recentMapSvg.get(svgPath) ?? '';
+function cardSvgFor(svgPath) {
+  return recentCardSvg.get(svgPath) ?? '';
 }
 
 // ── cross-intron primer design ──────────────────────────────────────────────
@@ -2449,7 +2478,7 @@ const INTRON_MISMATCH_SCHEMA = {
   required: ['position', 'template_base', 'primer_base', 'spliced_position', 'genomic_position', 'distance_from_3prime'],
   properties: {
     position: { type: 'integer', description: '1-based position of the mismatch in the primer (5\'→3\').' },
-    template_base: { type: 'string', description: 'The base a perfectly matching primer would carry at this position on the spliced transcript.' },
+    template_base: { type: 'string', description: 'The base a perfectly matching primer would carry at this position: the spliced-transcript base for the forward primer, its complement for the reverse primer (which is reported as the molecule to order).' },
     primer_base: { type: 'string', description: 'The base the reported primer actually carries (primer_base !== template_base marks a real mismatch).' },
     spliced_position: { type: 'integer', description: '1-based position on the spliced transcript.' },
     genomic_position: { type: 'integer', description: '1-based position on the genomic sequence.' },
@@ -2501,7 +2530,7 @@ const INTRON_PRIMER_SCHEMA = {
 
 const intronPrimersTool = (ctx) => define({
   name: 'molbio_design_intron_primers',
-  description: 'Design qPCR primer pairs where the forward primer spans an exon-exon junction (>= min_junction_bases on each side) so genomic DNA cannot be amplified, and the reverse primer sits in a different exon. Provide the genomic sequence and the exon spans (1-based, inclusive). min_genomic_span enforces a minimal genomic distance between the primers (making gDNA amplification impossible or easily detectable). Coordinates come back both on the spliced transcript and on the genomic sequence. v12: Primer3-style structural filters (self-complementarity alignment scores, hairpin/dimer folding Tm at 47 °C defaults, end stability/end GC, GC clamp levels); pass max_mismatches > 0 to allow mismatched primers (never on the 3\'-terminal base) with spliced+genomic mismatch reports; pass check_mispriming: true to reject/penalize non-specific 3\'-tail annealing on the transcript.',
+  description: 'Design qPCR primer pairs where ONE primer spans an exon-exon junction (>= min_junction_bases on each side) so genomic DNA cannot be amplified. In the returned pair the junction is carried by the REVERSE primer (the assay sits 5\' of the junction): the forward primer is upstream inside a single exon, and the reverse sequence is the molecule to order (the reverse complement of its spliced site), so F is upstream of R and the pair amplifies as printed. Provide the genomic sequence and the exon spans (1-based, inclusive). min_genomic_span enforces a minimal genomic distance between the primers (making gDNA amplification impossible or easily detectable). Coordinates come back both on the spliced transcript and on the genomic sequence. v12: Primer3-style structural filters (self-complementarity alignment scores, hairpin/dimer folding Tm at 47 °C defaults, end stability/end GC, GC clamp levels); pass max_mismatches > 0 to allow mismatched primers (never on the 3\'-terminal base) with spliced+genomic mismatch reports; pass check_mispriming: true to reject/penalize non-specific 3\'-tail annealing on the transcript.',
   parameters: {
     type: 'object',
     required: ['exons'],
@@ -2621,7 +2650,7 @@ const intronPrimersTool = (ctx) => define({
     }
     const lines = [
       `Tm model conditions: ${value.conditions.na_mm} mM Na+ / ${value.conditions.mg_mm} mM Mg2+ / ${value.conditions.dntp_mm} mM dNTP / ${value.conditions.primer_nm} nM primer (SantaLucia 1998 NN — an estimate).`,
-      `${value.pairs.length} candidate pair(s); the forward primer spans an exon-exon junction (genomic DNA will not amplify):`,
+      `${value.pairs.length} candidate pair(s); the REVERSE primer spans an exon-exon junction, so genomic DNA will not amplify (forward is upstream of it):`,
     ];
     const mismatchLine = (label, primer) => {
       if (primer.mismatch_count > 0) {
@@ -2641,8 +2670,8 @@ const intronPrimersTool = (ctx) => define({
     };
     for (const [index, pair] of value.pairs.entries()) {
       lines.push(`#${index + 1} spliced amplicon ${pair.spliced_amplicon.start}-${pair.spliced_amplicon.end} (${pair.spliced_amplicon.length} bp), genomic span ${pair.genomic_amplicon_length} bp${pair.target_distance !== undefined ? `, nearer 3' end ${pair.target_distance} spliced bp from target_position` : ''}, penalty ${pair.penalty}`);
-      lines.push(`  F ${pair.forward.sequence}  (spliced ${pair.forward.spliced_start}-${pair.forward.spliced_end}; genomic ${pair.forward.genomic_start}-${pair.forward.genomic_end}; exons ${pair.forward.exons.join('/')}, junction ${pair.forward.junction_left}+${pair.forward.junction_right} bp; Tm ${pair.forward.tm} °C, self ${pair.forward.self_any}/${pair.forward.self_end}, hairpin ${pair.forward.hairpin_tm} °C)`);
-      lines.push(`  R ${pair.reverse.sequence}  (spliced ${pair.reverse.spliced_start}-${pair.reverse.spliced_end}; genomic ${pair.reverse.genomic_start}-${pair.reverse.genomic_end}; exon ${pair.reverse.exon}; Tm ${pair.reverse.tm} °C, self ${pair.reverse.self_any}/${pair.reverse.self_end}, hairpin ${pair.reverse.hairpin_tm} °C)`);
+      lines.push(`  F ${pair.forward.sequence}  (spliced ${pair.forward.spliced_start}-${pair.forward.spliced_end}; genomic ${pair.forward.genomic_start}-${pair.forward.genomic_end}; exon ${pair.forward.exon}; Tm ${pair.forward.tm} °C, self ${pair.forward.self_any}/${pair.forward.self_end}, hairpin ${pair.forward.hairpin_tm} °C)`);
+      lines.push(`  R ${pair.reverse.sequence}  (spliced ${pair.reverse.spliced_start}-${pair.reverse.spliced_end}; genomic ${pair.reverse.genomic_start}-${pair.reverse.genomic_end}; exons ${pair.reverse.exons.join('/')}, junction ${pair.reverse.junction_left}+${pair.reverse.junction_right} bp; Tm ${pair.reverse.tm} °C, self ${pair.reverse.self_any}/${pair.reverse.self_end}, hairpin ${pair.reverse.hairpin_tm} °C)`);
       mismatchLine('F', pair.forward);
       mismatchLine('R', pair.reverse);
       misprimingLine('F', pair.forward);
@@ -3524,6 +3553,145 @@ const proteinPropsTool = define({
   },
 });
 
+const proteinChargeTool = (ctx) => define({
+  // Always writes protein-charge.svg and may open a viewer.
+  safe: false,
+  name: 'molbio_protein_charge',
+  description: 'Plot a protein\'s net charge across a pH range and report the isoelectric point on the same curve (Henderson-Hasselbalch summation over the terminal groups, K/R/H positive and D/E/C/Y negative). pka_set selects the pK table: bjellqvist (the set molbio_protein_props uses, so the pI matches) or emboss (the Epk.dat values). The SVG is written to the workspace and opened with the OS default viewer (auto_view, default true); the sampled curve and the charge at pH 7.4 are returned too. pI is an estimate and is only meaningful together with the named pK set.',
+  parameters: {
+    type: 'object',
+    required: ['sequence'],
+    properties: {
+      sequence: requiredString('Protein sequence (one-letter amino acid codes).'),
+      pka_set: { type: 'string', enum: ['bjellqvist', 'emboss'], description: 'pK table: bjellqvist (default, matches molbio_protein_props) or emboss (Epk.dat).' },
+      ph_min: { type: 'number', description: 'Lowest pH sampled (0-14, default 0).' },
+      ph_max: { type: 'number', description: 'Highest pH sampled (0-14, default 14).' },
+      steps: { type: 'integer', description: 'Number of sampled points including both ends (2-141, default 29 = 0.5 pH).' },
+      title: { type: 'string', description: 'Title drawn on the SVG (default "Net charge vs pH").' },
+      output_path: { type: 'string', description: 'Optional SVG file path; default protein-charge.svg in the session workspace.' },
+      auto_view: { type: 'boolean', description: 'Open the SVG automatically with the OS default application (default true).' },
+      ...ATTACH_IMAGE_PARAM,
+    },
+  },
+  outputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['length', 'pka_set', 'pka_label', 'pI', 'charge_at_7_4', 'charge_min', 'charge_max', 'ph_min', 'ph_max', 'steps', 'points', 'svg_path', 'auto_viewed'],
+    properties: {
+      length: { type: 'integer' },
+      pka_set: { type: 'string', enum: ['bjellqvist', 'emboss'] },
+      pka_label: { type: 'string' },
+      pI: { type: 'number', description: 'Isoelectric point on the sampled pK set.' },
+      charge_at_7_4: { type: 'number', description: 'Net charge at pH 7.4 (e).' },
+      charge_min: { type: 'number' },
+      charge_max: { type: 'number' },
+      ph_min: { type: 'number' },
+      ph_max: { type: 'number' },
+      steps: { type: 'integer' },
+      points: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['ph', 'charge'],
+          properties: {
+            ph: { type: 'number' },
+            charge: { type: 'number' },
+          },
+        },
+      },
+      svg_path: { type: 'string' },
+      auto_viewed: { type: 'boolean' },
+      image: ATTACHED_IMAGE_SCHEMA,
+      image_note: { type: 'string' },
+    },
+  },
+  render(value) {
+    const direction = value.charge_at_7_4 > 0 ? 'net positive' : value.charge_at_7_4 < 0 ? 'net negative' : 'neutral';
+    return [
+      value.length + ' aa · ' + value.pka_label + ' pK set · pI ' + value.pI + ' · charge at pH 7.4 ' + value.charge_at_7_4 + ' e (' + direction + ')',
+      'Curve over pH ' + value.ph_min + '-' + value.ph_max + ' (' + value.steps + ' points; range ' + value.charge_min + ' .. ' + value.charge_max + ' e), SVG written to ' + value.svg_path + (value.auto_viewed === true ? ' and opened automatically' : '') + '.',
+      'Henderson-Hasselbalch estimate: the pI belongs to the named pK set and is not interchangeable with another calculator.',
+      imageNote(value).trim(),
+    ].filter((line) => line !== '').join('\n');
+  },
+  async execute(args, exec) {
+    const curve = chargeCurve(args.sequence, {
+      pkaSet: args.pka_set ?? 'bjellqvist',
+      phMin: args.ph_min,
+      phMax: args.ph_max,
+      steps: args.steps,
+    });
+    const svg = renderChargeCurve(curve, { title: args.title });
+    const { file, viewed, attached } = await writeSvgFile(ctx, exec, args, svg, 'protein-charge.svg');
+    return mergeAttachedImage({ ...curve, svg_path: file, auto_viewed: viewed }, attached);
+  },
+});
+
+const dotplotTool = (ctx) => define({
+  // Always writes dotplot.svg and may open a viewer.
+  safe: false,
+  name: 'molbio_dotplot',
+  description: 'Compute and draw a self-comparison dotplot of a DNA sequence by exact word matching: a black cell at (i,j) means the k-mer at i equals the k-mer at j (direct repeat); a red cell means it equals the REVERSE COMPLEMENT of the k-mer at j (inverted repeat). word defaults to 8 (4-12); lower words find shorter repeats and produce more dots. The plot is binned to a fixed grid so a repetitive sequence cannot produce an enormous file; direct/inverted match counts and any scan/plot caps are reported. The SVG is written and opened with the OS default viewer (auto_view, default true). Exact k-mer view — not a windowed identity/scoring dotplot.',
+  parameters: {
+    type: 'object',
+    required: ['sequence'],
+    properties: {
+      sequence: requiredString('DNA sequence (IUPAC; ambiguous k-mers are skipped and counted).'),
+      word: { type: 'integer', description: 'Word (k-mer) length, 4-12 (default 8).' },
+      mode: { type: 'string', enum: ['both', 'direct', 'inverted'], description: 'Which repeats to plot: both (default), direct only, or inverted only.' },
+      title: { type: 'string', description: 'Title drawn on the SVG (default "Sequence dotplot").' },
+      output_path: { type: 'string', description: 'Optional SVG file path; default dotplot.svg in the session workspace.' },
+      auto_view: { type: 'boolean', description: 'Open the SVG automatically with the OS default application (default true).' },
+      ...ATTACH_IMAGE_PARAM,
+    },
+  },
+  outputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['length', 'word', 'mode', 'direct_matches', 'inverted_matches', 'direct_cells', 'inverted_cells', 'ambiguous_bases', 'truncated', 'plot_truncated', 'svg_path', 'auto_viewed'],
+    properties: {
+      length: { type: 'integer' },
+      word: { type: 'integer' },
+      mode: { type: 'string', enum: ['both', 'direct', 'inverted'] },
+      direct_matches: { type: 'integer' },
+      inverted_matches: { type: 'integer' },
+      direct_cells: { type: 'integer', description: 'Occupied grid cells for direct repeats (the plotted count, not the match count).' },
+      inverted_cells: { type: 'integer' },
+      ambiguous_bases: { type: 'integer', description: 'Ambiguous k-mers skipped (IUPAC bases other than A/C/G/T).' },
+      truncated: { type: 'boolean', description: 'The match scan hit the work cap; counts are lower bounds.' },
+      plot_truncated: { type: 'boolean', description: 'The grid hit the cell cap; some dots are not drawn.' },
+      grid: { type: 'integer', description: 'Grid resolution used for binning the plot (cells per axis).' },
+      svg_path: { type: 'string' },
+      auto_viewed: { type: 'boolean' },
+      image: ATTACHED_IMAGE_SCHEMA,
+      image_note: { type: 'string' },
+    },
+  },
+  render(value) {
+    const lines = [
+      value.length + ' bp · word ' + value.word + ' · ' + value.direct_matches + ' direct / ' + value.inverted_matches + ' inverted match(es); ' + value.direct_cells + ' + ' + value.inverted_cells + ' occupied cell(s)',
+      'SVG written to ' + value.svg_path + (value.auto_viewed === true ? ' and opened automatically' : '') + '.',
+    ];
+    if (value.ambiguous_bases > 0) lines.push(value.ambiguous_bases + ' ambiguous k-mer(s) skipped (IUPAC bases other than A/C/G/T).');
+    if (value.truncated) lines.push('The match scan hit its work cap: the counts are lower bounds. Raise word to focus on longer, rarer repeats.');
+    if (value.plot_truncated) lines.push('The plotted grid hit its cell cap: some dots are not drawn.');
+    lines.push('Exact k-mer view (black = direct, red = inverted); the diagonal is the sequence against itself.');
+    if (imageNote(value) !== '') lines.push(imageNote(value).trim());
+    return lines.join('\n');
+  },
+  async execute(args, exec) {
+    const data = dotplot(args.sequence, {
+      word: args.word ?? 8,
+      mode: args.mode ?? 'both',
+    });
+    const svg = renderDotplot(data, { title: args.title });
+    const { file, viewed, attached } = await writeSvgFile(ctx, exec, args, svg, 'dotplot.svg');
+    const { directGrid, invertedGrid, ...stats } = data;
+    return mergeAttachedImage({ ...stats, svg_path: file, auto_viewed: viewed }, attached);
+  },
+});
+
 const peptideDigestTool = define({
   name: 'molbio_peptide_digest',
   description: 'In silico protease digestion for mass spectrometry: trypsin, chymotrypsin, LysC or GluC cleavage rules (no cleavage before proline where applicable), optional missed cleavages (0-3), monoisotopic or average [M+H]+ peptide masses, and optional mass-range filtering.',
@@ -3646,7 +3814,9 @@ const WHEEL_RESIDUE_SCHEMA = {
 };
 
 const helicalWheelTool = (ctx) => define({
-  safe: (args) => args.output_path === undefined || args.output_path === '',
+  // It always writes the SVG (output_path only chooses the name), so it is
+  // never concurrency-safe; the old predicate marked the common case safe.
+  safe: false,
   name: 'molbio_helical_wheel',
   description: 'Draw the helical wheel (Schiffer-Edmundson projection) of a peptide or protein stretch and analyse it: residues are placed 100° apart on the circle (3.6 residues per turn of an ideal alpha-helix), coloured by residue class (hydrophobic/polar/acidic/basic), with the Eisenberg hydrophobic moment μH of the stretch and the maximum μH over every window of moment_window residues (11 by default). An amphipathic helix shows one hydrophobic face and one polar face. The tool WRITES an SVG file and opens it with the OS default viewer (auto_view, default true); all values are sequence-propensity estimates from published scales, not a structure prediction.',
   parameters: {
@@ -3765,7 +3935,8 @@ const HYDROPATHY_PEAK_SCHEMA = {
 };
 
 const hydropathyTool = (ctx) => define({
-  safe: (args) => args.output_path === undefined || args.output_path === '',
+  // Always writes the SVG; see the helical-wheel note.
+  safe: false,
   name: 'molbio_hydropathy_plot',
   description: 'Plot the Kyte-Doolittle hydropathy profile of a protein: a sliding-window average (window, default 9; use 19-21 for transmembrane spans), the GRAVY value, and every peak whose window average reaches the threshold (default 1.6, the classic membrane-spanning cutoff). The tool WRITES an SVG file and opens it with the OS default viewer (auto_view, default true); the per-residue profile is also returned so it can feed further analysis. Values are the Kyte-Doolittle propensity scale, not a topology prediction.',
   parameters: {
@@ -4907,6 +5078,7 @@ const sequenceLogoTool = (ctx) => define({
       smallSample: args.small_sample !== false,
     });
     const { file, viewed, attached } = await writeSvgFile(ctx, exec, args, svg, 'logo.svg');
+    rememberCardSvg(file, svg);
     const total = compositions.reduce((sum, column) => sum + column.bits, 0);
     const best = compositions.reduce((top, column) => (column.bits > top.bits ? column : top), compositions[0]);
     const round2 = (x) => Math.round(x * 100) / 100;
@@ -4924,6 +5096,17 @@ const sequenceLogoTool = (ctx) => define({
       auto_viewed: viewed,
     }, attached);
   },
+  // The transcript card draws the logo instead of asking the reader to open the
+  // file. The meta is a projection: cheap, total, and bounded (the markup is
+  // dropped when it exceeds CARD_SVG_MAX_BYTES).
+  presentationMeta(args, value) {
+    return figureCardMeta({
+      figure: 'logo',
+      summary: `Sequence logo · ${value.sequence_count} sequences × ${value.columns} columns · ${value.total_bits} bits (${value.score_type})`,
+      svgPath: value.svg_path,
+      extra: { title: args?.title ?? 'Sequence logo' },
+    }, cardSvgFor(value.svg_path));
+  },
 });
 
 /**
@@ -5199,6 +5382,7 @@ const grnaDesignTool = (ctx) => define({
       mapPath = written.file;
       viewed = written.viewed;
       attached = written.attached;
+      rememberCardSvg(written.file, svg);
     }
     return mergeAttachedImage({
       target_name: name,
@@ -5224,6 +5408,36 @@ const grnaDesignTool = (ctx) => define({
       auto_viewed: viewed,
     }, attached);
   },
+  // The transcript card shows the ranked guides (top five) and, when the caller
+  // asked for map_path, the map itself. The summary is built here so the card
+  // stays a pure function of this projection.
+  presentationMeta(_args, value) {
+    const guides = value.guides.slice(0, 5).map((guide) => ({
+      rank: guide.rank,
+      sequence: guide.sequence,
+      pam: guide.pam,
+      strand: guide.strand,
+      start: guide.start,
+      end: guide.end,
+      score: guide.score,
+      off_target_count: guide.off_target_count ?? 0,
+    }));
+    const recognition = value.pam === '' ? 'no PAM (Cas13)' : value.pam + ' PAM';
+    return figureCardMeta({
+      figure: 'grna',
+      summary: `${value.cas_label} · ${value.guides.length} of ${value.candidate_count} guide(s) · ${recognition} · ${value.target_name} (${value.target_length} bp)`,
+      svgPath: value.map_path,
+      extra: {
+        guides,
+        guide_count: value.guides.length,
+        candidate_count: value.candidate_count,
+        csv_path: value.saved_to,
+        map_path: value.map_path,
+        cas_family: value.cas_family,
+        pam: value.pam,
+      },
+    }, value.map_path === '' ? '' : cardSvgFor(value.map_path));
+  },
 });
 
 /** CSV of the returned guides, for pasting into an ordering sheet. */
@@ -5284,7 +5498,10 @@ function validateGrnaOptions(args) {
 }
 
 const fastaFastqTool = (ctx) => define({
-  safe: (args) => args.action !== 'convert' && args.action !== 'extract',
+  // convert always writes; extract writes only when output_path is given, so
+  // stats/qc (and extract without a path) are the pure cases.
+  safe: (args) => !(args.action === 'convert'
+    || (args.action === 'extract' && args.output_path !== undefined && args.output_path !== '')),
   name: 'molbio_fasta_fastq',
   description: 'Work with FASTA/FASTQ files in the workspace. action=stats: per-entry and overall statistics (length/GC). action=extract: pull entries by id (exact or substring) and optionally write them to a FASTA file. action=convert: FASTQ → FASTA (output_path required). action=qc: FASTQ quality statistics (mean/min/max Phred, low-quality fraction, per-position means).',
   parameters: {
@@ -5452,13 +5669,22 @@ async function batchFileList(ctx, exec, args, policy, root) {
   const files = [];
   let truncated = false;
   if (Array.isArray(args.paths) && args.paths.length > 0) {
-    for (const supplied of args.paths) {
+    // The directory walk enforces max_files; the explicit list must too, or the
+    // documented 1-500 bound disappears for the easier input form.
+    const maxFiles = Math.min(args.max_files ?? 50, BATCH_LIMITS.maxFiles);
+    for (const supplied of args.paths.slice(0, maxFiles)) {
       const absolute = workspaceFilePath(supplied, exec, root);
-      const target = await fs.resolve(absolute);
       const label = relative(root, absolute).split(sep).join('/');
-      files.push({ target, label });
+      try {
+        const target = await fs.resolve(absolute);
+        files.push({ target, label });
+      } catch (error) {
+        // A bad explicit path is one error ROW, not a failed batch: the same
+        // contract the directory walk provides for files it cannot parse.
+        files.push({ label, resolveError: error instanceof Error ? error.message : String(error) });
+      }
     }
-    return { fs, files, truncated, maxBytes };
+    return { fs, files, truncated: args.paths.length > files.length, maxBytes };
   }
   if (typeof fs.listDir !== 'function') {
     throw new MolbioInputError('this harness fs service has no listDir; pass an explicit paths array instead of a directory');
@@ -5618,6 +5844,10 @@ const batchAnalyzeTool = (ctx) => define({
     const rows = [];
     for (const file of files) {
       const format = detectBatchFormat(file.label, '');
+      if (file.resolveError !== undefined) {
+        rows.push(batchErrorRow(file.label, format, file.resolveError));
+        continue;
+      }
       try {
         const info = file.size === undefined ? await fs.stat(file.target) : { size: file.size };
         if (info?.size !== undefined && info.size > maxBytes) {
@@ -6481,6 +6711,248 @@ const fastqQcTool = (ctx) => define({
   },
 });
 
+
+const contaminationScreenTool = (ctx) => define({
+  name: 'molbio_contamination_screen',
+  description: 'Screen a DNA sequence, or every entry in a FASTA/FASTQ file, for common vector-backbone/promoter/origin and Illumina/Nextera adapter signatures. The signature table is SHORT and embedded (no reference database, no network): a hit is evidence worth following up, and a negative result does NOT prove the sample is clean. Matching is both-strand and substitution-only (no gaps); max_mismatches adds a seed-and-verify search (0-2). Reports per-signature read counts, the best example position/strand, and the criteria that produced them. Use it for "is this assembly contaminated with vector backbone or adapter" — not as a BLAST replacement.',
+  parameters: {
+    type: 'object',
+    properties: {
+      sequence: { type: 'string', description: 'Inline DNA sequence to screen. Provide exactly one of sequence or path.' },
+      path: { type: 'string', description: 'Path to a FASTA/FASTQ file, or a plain sequence file. Provide exactly one of sequence or path.' },
+      max_mismatches: { type: 'integer', description: 'Substitutions allowed per signature (0-2, default 0). A hit still needs one exact seed chunk.' },
+      max_reads: { type: 'integer', description: 'Scan at most this many entries (default 0 = all, capped at 200000).' },
+      kinds: { type: 'string', enum: ['both', 'adapter', 'vector'], description: 'Restrict the table to adapters, vectors, or both (default both).' },
+    },
+  },
+  outputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['input_type', 'total_entries', 'scanned_entries', 'bases', 'ambiguous_bases', 'hits', 'hit_count', 'reads_with_hit', 'truncated', 'criteria'],
+    properties: {
+      input_type: { type: 'string', enum: ['sequence', 'fasta', 'fastq'] },
+      total_entries: { type: 'integer' },
+      scanned_entries: { type: 'integer' },
+      bases: { type: 'integer' },
+      ambiguous_bases: { type: 'integer' },
+      hits: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['name', 'kind', 'category', 'signature', 'reads', 'percent', 'best_mismatches', 'example'],
+          properties: {
+            name: { type: 'string' },
+            kind: { type: 'string', enum: ['adapter', 'vector'] },
+            category: { type: 'string' },
+            signature: { type: 'string' },
+            reads: { type: 'integer' },
+            percent: { type: 'number' },
+            best_mismatches: { type: 'integer' },
+            example: {
+              type: 'object',
+              additionalProperties: false,
+              required: ['id', 'start', 'end', 'strand', 'mismatches'],
+              properties: {
+                id: { type: 'string' },
+                start: { type: 'integer' },
+                end: { type: 'integer' },
+                strand: { type: 'string', enum: ['+', '-'] },
+                mismatches: { type: 'integer' },
+              },
+            },
+          },
+        },
+      },
+      hit_count: { type: 'integer' },
+      reads_with_hit: { type: 'integer' },
+      truncated: { type: 'boolean' },
+      criteria: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['max_mismatches', 'kinds', 'signature_count', 'max_reads', 'match_basis'],
+        properties: {
+          max_mismatches: { type: 'integer' },
+          kinds: { type: 'string', enum: ['both', 'adapter', 'vector'] },
+          signature_count: { type: 'integer' },
+          max_reads: { type: 'integer' },
+          match_basis: { type: 'string' },
+        },
+      },
+    },
+  },
+  render(value) {
+    const lines = [
+      value.input_type + ' input: ' + value.scanned_entries + ' of ' + value.total_entries + ' entr' + (value.total_entries === 1 ? 'y' : 'ies') + ', ' + value.bases + ' bp; ' + value.hit_count + ' signature(s) hit, ' + value.reads_with_hit + ' entr' + (value.total_entries === 1 ? 'y' : 'ies') + ' with a hit.',
+    ];
+    if (value.hits.length === 0) {
+      lines.push('No embedded vector/adapter signature matched.');
+    } else {
+      for (const hit of value.hits) {
+        lines.push('  ' + hit.name + ' [' + hit.kind + '/' + hit.category + '] ' + hit.reads + '/' + value.scanned_entries + ' (' + hit.percent + '%), best ' + hit.best_mismatches + ' mismatch(es); e.g. ' + hit.example.id + ' ' + hit.example.start + '-' + hit.example.end + ' (' + hit.example.strand + ')');
+      }
+    }
+    if (value.ambiguous_bases > 0) lines.push(value.ambiguous_bases + ' ambiguous base(s) were scanned literally (they can only match a signature at an unambiguous position).');
+    if (value.truncated) lines.push('Only the first ' + value.scanned_entries + ' entr' + (value.scanned_entries === 1 ? 'y was' : 'ies were') + ' scanned; max_reads capped the input.');
+    lines.push('Short embedded signatures, both strands, substitutions only (no gaps). A negative result does not prove the sample is clean.');
+    return lines.join('\n');
+  },
+  async execute(args, exec) {
+    const hasSequence = typeof args.sequence === 'string' && args.sequence !== '';
+    const hasPath = typeof args.path === 'string' && args.path !== '';
+    if (hasSequence === hasPath) throw new MolbioInputError('provide exactly one of sequence or path');
+    let entries;
+    let inputType;
+    if (hasSequence) {
+      entries = [{ id: 'input', sequence: normalizeSequence(args.sequence, 'sequence') }];
+      inputType = 'sequence';
+    } else {
+      const bytes = await readFileBytes(ctx, exec, args.path);
+      const text = new TextDecoder().decode(bytes).replace(/^\uFEFF/, '');
+      const first = text.trimStart();
+      if (first.startsWith('@')) {
+        entries = parseFastq(text);
+        inputType = 'fastq';
+      } else if (first.startsWith('>')) {
+        entries = parseFasta(text);
+        inputType = 'fasta';
+      } else {
+        entries = [{ id: 'input', sequence: normalizeSequence(text, 'sequence') }];
+        inputType = 'sequence';
+      }
+    }
+    const result = screenContamination(entries, {
+      maxMismatches: args.max_mismatches,
+      maxReads: args.max_reads,
+      kinds: args.kinds,
+    });
+    return { input_type: inputType, ...result };
+  },
+});
+
+const FASTQ_TRIM_TOOL_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['reads_in', 'total_reads', 'reads_out', 'bases_in', 'bases_out', 'trimmed_reads', 'dropped_reads', 'trim_counts', 'drop_counts', 'truncated', 'criteria', 'saved_to', 'output_format'],
+  properties: {
+    reads_in: { type: 'integer' },
+    total_reads: { type: 'integer' },
+    reads_out: { type: 'integer' },
+    bases_in: { type: 'integer' },
+    bases_out: { type: 'integer' },
+    trimmed_reads: { type: 'integer' },
+    dropped_reads: { type: 'integer' },
+    trim_counts: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['quality', 'adapter', 'poly_g', 'poly_a', 'primer'],
+      properties: {
+        quality: { type: 'integer' },
+        adapter: { type: 'integer' },
+        poly_g: { type: 'integer' },
+        poly_a: { type: 'integer' },
+        primer: { type: 'integer' },
+      },
+    },
+    drop_counts: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['length', 'n'],
+      properties: {
+        length: { type: 'integer' },
+        n: { type: 'integer' },
+      },
+    },
+    truncated: { type: 'boolean' },
+    criteria: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['min_quality', 'quality_window', 'poly_min', 'min_length', 'max_n_percent', 'phred', 'max_reads', 'adapter', 'primer', 'poly_g', 'poly_a'],
+      properties: {
+        min_quality: { type: 'integer' },
+        quality_window: { type: 'integer' },
+        poly_min: { type: 'integer' },
+        min_length: { type: 'integer' },
+        max_n_percent: { type: 'number' },
+        phred: { type: 'integer', enum: [33, 64] },
+        max_reads: { type: 'integer' },
+        adapter: { type: 'string' },
+        primer: { type: 'string' },
+        poly_g: { type: 'boolean' },
+        poly_a: { type: 'boolean' },
+      },
+    },
+    saved_to: { type: 'string' },
+    output_format: { type: 'string', enum: ['fastq', 'fasta'] },
+  },
+};
+
+const fastqTrimTool = (ctx) => define({
+  safe: false,
+  name: 'molbio_fastq_trim',
+  description: 'Trim and filter a FASTQ file, then WRITE the surviving reads as FASTQ or FASTA. Supported operations, applied in this order: remove an exact 5\' primer, remove an exact 3\' adapter and everything after it, trim a low-quality 3\' tail with a sliding mean-quality window, trim a trailing poly-G or poly-A run, then drop reads below min_length or above max_n_percent. Phred+33 and Phred+64 are supported (quality characters are preserved). This is not a paired-end merger, not a semiglobal adapter aligner, and not a UMI pipeline; those are deliberately out of scope. Returns before/after counts, per-stage trim counts, and the written path.',
+  parameters: {
+    type: 'object',
+    required: ['path', 'output_path'],
+    properties: {
+      path: { type: 'string', description: 'Path to the input .fastq/.fq file.' },
+      output_path: { type: 'string', description: 'Path to write the trimmed reads (FASTQ or FASTA, per output_format).' },
+      output_format: { type: 'string', enum: ['fastq', 'fasta'], description: 'Output format (default fastq).' },
+      min_quality: { type: 'integer', description: 'Minimum mean Phred in the sliding window (0-60, default 20). Set 0 to disable quality trimming.' },
+      quality_window: { type: 'integer', description: 'Sliding-window width in bases (1-100, default 4).' },
+      poly_g: { type: 'boolean', description: 'Trim a trailing poly-G run (default false; useful for NovaSeq/NextSeq).' },
+      poly_a: { type: 'boolean', description: 'Trim a trailing poly-A run (default false).' },
+      poly_min: { type: 'integer', description: 'Minimum trailing run length to trim (2-100, default 8).' },
+      adapter: { type: 'string', description: 'Exact 3\' adapter sequence; it and everything after it are removed. Empty = no adapter trim.' },
+      primer: { type: 'string', description: 'Exact 5\' primer sequence; it is removed when the read starts with it. Empty = no primer trim.' },
+      min_length: { type: 'integer', description: 'Drop reads shorter than this after trimming (default 0).' },
+      max_n_percent: { type: 'number', description: 'Drop reads whose trimmed sequence has more than this percent of non-ACGT bases (0-100, default 100 = no filter).' },
+      phred: { type: 'integer', enum: [33, 64], description: 'Quality encoding of the input (33 = Sanger/Illumina 1.8+, 64 = old Illumina). Output keeps the same encoding.' },
+      max_reads: { type: 'integer', description: 'Process at most this many reads (default 0 = all, capped at 200000).' },
+    },
+  },
+  outputSchema: FASTQ_TRIM_TOOL_SCHEMA,
+  render(value) {
+    const counts = value.trim_counts;
+    const lines = [
+      'FASTQ trim: ' + value.reads_in + ' of ' + value.total_reads + ' read(s) scanned (' + value.bases_in + ' bases) -> ' + value.reads_out + ' read(s) (' + value.bases_out + ' bases); ' + value.trimmed_reads + ' trimmed, ' + value.dropped_reads + ' dropped.',
+      '  quality ' + counts.quality + ' · adapter ' + counts.adapter + ' · poly-G ' + counts.poly_g + ' · poly-A ' + counts.poly_a + ' · primer ' + counts.primer + '; dropped by length ' + value.drop_counts.length + ', by N ' + value.drop_counts.n,
+      'Saved ' + value.output_format.toUpperCase() + ' to ' + value.saved_to + '.',
+    ];
+    if (value.truncated) lines.push('Only the first ' + value.reads_in + ' read(s) were processed; max_reads capped the input.');
+    lines.push('Settings: Phred+' + value.criteria.phred + ', min Q' + value.criteria.min_quality + ' over ' + value.criteria.quality_window + ' base(s), poly >= ' + value.criteria.poly_min + ', min length ' + value.criteria.min_length + ', max N ' + value.criteria.max_n_percent + '%.');
+    if (value.criteria.adapter !== '') lines.push('Adapter: ' + value.criteria.adapter + '.');
+    if (value.criteria.primer !== '') lines.push('Primer: ' + value.criteria.primer + '.');
+    return lines.join('\n');
+  },
+  async execute(args, exec) {
+    const bytes = await readFileBytes(ctx, exec, args.path);
+    const text = new TextDecoder().decode(bytes).replace(/^\uFEFF/, '');
+    if (text.trimStart().startsWith('>')) throw new MolbioInputError('this looks like FASTA, not FASTQ: molbio_fastq_trim needs per-base quality strings');
+    const entries = parseFastq(text);
+    const trimmed = trimFastq(entries, {
+      minQuality: args.min_quality,
+      qualityWindow: args.quality_window,
+      polyG: args.poly_g,
+      polyA: args.poly_a,
+      polyMin: args.poly_min,
+      adapter: args.adapter,
+      primer: args.primer,
+      minLength: args.min_length,
+      maxNPercent: args.max_n_percent,
+      phred: args.phred,
+      maxReads: args.max_reads,
+    });
+    const outputFormat = args.output_format ?? 'fastq';
+    const fs = fsService(ctx);
+    const sandboxPolicyService = ctx.get('sandboxPolicy');
+    const policy = sandboxPolicyService?.resolve({ ...exec?.agent !== undefined ? { session: exec.agent.session } : {} });
+    const file = workspaceFilePath(args.output_path, exec, policy?.workspaceRoot);
+    await writeWorkspaceFile(fs, file, outputFormat === 'fasta' ? toFasta(trimmed.entries) : toFastq(trimmed.entries), policy);
+    return { ...trimmed.stats, saved_to: file, output_format: outputFormat };
+  },
+});
+
 const RARE_CODON_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -6999,7 +7471,14 @@ const pubmedAbstractTool = (ctx) => define({
     }
     const apiKey = await pubmedKey(args, ctx);
     const url = pubmedFetchUrl(pmids, apiKey);
-    const result = await web.fetch({ url }, exec?.signal);
+    let result;
+    try {
+      result = await web.fetch({ url }, exec?.signal);
+    } catch (error) {
+      // Same contract as eutilsRequest: a transport failure is a tool-input
+      // error the caller can report, not a raw exception escaping the tool.
+      throw new MolbioInputError(`PubMed efetch could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const body = result?.body?.content;
     if (typeof body !== 'string' || body === '') {
       throw new MolbioInputError(`efetch returned no content (status ${result?.statusCode ?? 'unknown'})`);
@@ -7059,9 +7538,13 @@ const bibtexTool = (ctx) => define({
     const { fs, path, policy } = paperServiceDeps(ctx, exec, args);
     const library = await loadLibrary(fs, path);
     const bibtex = toBibtex(library.papers, args.tag_filter);
+    // Never fall back to the LIBRARY path itself: a custom `file` without a
+    // .json suffix used to make this replace a no-op, so the export overwrote
+    // the library with BibTeX. Always derive a distinct .bib name.
+    const defaultOutput = /\.json$/i.test(path) ? path.replace(/\.json$/i, '.bib') : `${path}.bib`;
     const output = args.output_path !== undefined && args.output_path !== ''
       ? workspaceFilePath(args.output_path, exec, policy?.workspaceRoot)
-      : path.replace(/\.json$/i, '.bib');
+      : defaultOutput;
     await writeWorkspaceFile(fs, output, bibtex, policy);
     return { output_path: output, count: bibtex.trim() === '' ? 0 : library.papers.filter((paper) => args.tag_filter === undefined || args.tag_filter.length === 0 || (paper.tags !== undefined && args.tag_filter.some((tag) => paper.tags.includes(tag)))).length };
   },
@@ -7602,11 +8085,11 @@ const PROMPT_SECTION = `Molecular-biology tools (dsh-molbio-tools) are available
 - Proteins: molbio_protein_props (MW/pI/A280/GRAVY — estimates), molbio_peptide_digest (trypsin etc. for MS), molbio_codon_optimize (E. coli/yeast/human, can avoid restriction sites), molbio_helical_wheel (Schiffer-Edmundson wheel + Eisenberg hydrophobic moment, written as an SVG), molbio_hydropathy_plot (Kyte-Doolittle sliding-window profile with the 1.6 threshold peaks, written as an SVG).
 - Quantitation: molbio_qpcr_efficiency (standard curve + plot), molbio_plot (experiment-data charts written to files), molbio_virtual_gel (expected band pattern as an SVG gel image with a size ladder).
 - molbio_plot kinds: bar (labelled values + optional SD error bars) and scatter (x/y + optional least-squares line) take their arrays directly in the call; the table kinds read a workspace CSV/TSV — pass data_path plus columns naming which column plays which role, or pass data with the table text inline. Use a table kind whenever the numbers are already in a file: do NOT retype a column into the call. line = one series per group_column; histogram = distribution of one column (bins default to Freedman-Diaconis unless you pass bins); box = Q1-Q3 box, median, 1.5xIQR whiskers, outliers as dots; violin = the same samples as a kernel-density silhouette with the box summary inside (use it when the SHAPE matters, not just the five numbers); volcano = effect size against significance from a log2-fold-change column and a p column, with dashed thresholds — it computes no statistics of its own, so the p-values must already be in the table; heatmap = a row x column matrix, one cell per value plus a colour bar, accepting either a wide table (first column = row labels, the rest = samples) or the long form (columns.row/column/value), with scale row_zscore|log2 as an explicitly-reported DISPLAY transform. The result carries the computed statistics (medians, quartiles, outliers, bin counts, axis ranges, significance counts, matrix extent), so quote THOSE instead of estimating values off the picture.
-- Sequences & files: molbio_align (local alignment with a readable match line), molbio_msa_align (progressive multiple sequence alignment — pass an array of sequences or a workspace FASTA), molbio_conservation (consensus + per-column identity/conservation + variable positions; accepts aligned rows or raw sequences it aligns first), molbio_sequence_logo (draws the same alignment as a sequence logo SVG — pass the molbio_msa_align output rows as the alignment argument; letters are sized by per-position information content), molbio_fasta_fastq (FASTA/FASTQ stats/extract/convert/QC on workspace files), molbio_batch_analyze (run one summary/ORF/enzyme analysis over every matching FASTA/FASTQ/GenBank/.dna file in a directory and write one CSV/TSV table), molbio_extract_region (pull a CDS/promoter/region from a plasmid file by feature label or coordinates).
+- Sequences & files: molbio_align (local alignment with a readable match line), molbio_msa_align (progressive multiple sequence alignment — pass an array of sequences or a workspace FASTA), molbio_conservation (consensus + per-column identity/conservation + variable positions; accepts aligned rows or raw sequences it aligns first), molbio_sequence_logo (draws the same alignment as a sequence logo SVG — pass the molbio_msa_align output rows as the alignment argument; letters are sized by per-position information content), molbio_fasta_fastq (FASTA/FASTQ stats/extract/convert/QC on workspace files), molbio_contamination_screen (embedded short vector/adapter signatures, both strands, exact or 0-2 mismatches — a short-signature screen, not BLAST), molbio_batch_analyze (run one summary/ORF/enzyme analysis over every matching FASTA/FASTQ/GenBank/.dna file in a directory and write one CSV/TSV table), molbio_extract_region (pull a CDS/promoter/region from a plasmid file by feature label or coordinates).
 - CRISPR: molbio_grna_design (family-aware guide RNAs over a sequence or plasmid file: cas_family spcas9/sacas9/cas12a/cas13a/cas13b/cas13d selects the PAM side, crRNA length, seed and target type — Cas12a uses a 5' TTTV PAM and 23 nt crRNA; Cas13 targets RNA and reports a PFS preference rather than a PAM. Both strands are scanned for DNA families, the sense strand by default for Cas13; guides are filtered on GC/poly-T/self-complementarity and ranked, with a mismatch-tolerant off-target search over the same sequence — reaching a whole genome simply means passing it as the target). Pass the top candidates on for ordering with save_path (CSV) or map_path (SVG map); the ranking is a heuristic and says so, so present it as candidate ranking, never as a validated efficiency prediction.
 - Map extras: pass gc_skew: true for the GC skew ring, show_unique_cutters: true to mark single-cutting enzymes on the map.
 - Literature & records: molbio_pubmed_abstract (fetch abstracts by PMID — needs web fetch; an NCBI key comes from the api_key argument, the credential store's NCBI_API_KEY, or the environment), molbio_paper_export_bibtex (papers.json → .bib), molbio_protocol_add / molbio_protocol_list / molbio_protocol_update (protocols.json), molbio_experiment_log / molbio_experiment_list (experiments.json).
-- Bench analysis (v19): molbio_fastq_qc (read-level QC for a FASTQ file: per-base quality with quartiles, per-read quality, base content, GC distribution, length, exact duplication, over-represented sequences, adapter screen, plus a report SVG — use it for "is this run good"), molbio_codon_usage (CAI/RSCU/Nc/GC3, rare-codon list and CDS CpG against E. coli/yeast/human — use it for "will this gene express"; it explains, molbio_codon_optimize rewrites), molbio_phylogenetic_tree (distance method: p-distance/JC/K2P/Tamura-Nei, UPGMA or neighbour-joining, bootstrap support, consensus, Newick file and an SVG tree — it is NOT a maximum-likelihood or Bayesian analysis, and bootstrap percentages are not p-values), molbio_pcr_simulate (where a primer pair amplifies: product sizes and coordinates on both strands, mismatch detail, the 3'-end exact-match requirement, circular templates, screening other templates, and an expected gel — use it for "what band will I see"), molbio_gc_composition (sliding-window GC, CpG islands under the Gardiner-Garden or Takai criteria, GC/AT skew with the cumulative-skew origin/terminus indication, dinucleotide obs/exp, entropy, complexity, N50/L50, plus a figure — use it for "is this a promoter or an origin").
+- Bench analysis (v19): molbio_fastq_qc (read-level QC for a FASTQ file: per-base quality with quartiles, per-read quality, base content, GC distribution, length, exact duplication, over-represented sequences, adapter screen, plus a report SVG — use it for "is this run good"), molbio_codon_usage (CAI/RSCU/Nc/GC3, rare-codon list and CDS CpG against E. coli/yeast/human — use it for "will this gene express"; it explains, molbio_codon_optimize rewrites), molbio_phylogenetic_tree (distance method: p-distance/JC/K2P/Tamura-Nei, UPGMA or neighbour-joining, bootstrap support, consensus, Newick file and an SVG tree — it is NOT a maximum-likelihood or Bayesian analysis, and bootstrap percentages are not p-values), molbio_pcr_simulate (where a primer pair amplifies: product sizes and coordinates on both strands, mismatch detail, the 3'-end exact-match requirement, circular templates, screening other templates, and an expected gel — use it for "what band will I see"), molbio_gc_composition (sliding-window GC, CpG islands under the Gardiner-Garden or Takai criteria, GC/AT skew with the cumulative-skew origin/terminus indication, dinucleotide obs/exp, entropy, complexity, N50/L50, plus a figure — use it for "is this a promoter or an origin"), molbio_fastq_trim (trim low-quality 3' tails, exact adapters/primers, poly-G/poly-A, then filter by length/N and write FASTQ/FASTA — not a paired-end merger).
 - Literature: molbio_pubmed_search — with an NCBI API key (api_key argument, the credential store under NCBI_API_KEY / MOLBIO_NCBI_API_KEY, or the environment) it uses the official PubMed E-utilities API and returns PMIDs, titles, journal/year, authors and DOI; without a key it falls back to the harness web search. The reading library is molbio_paper_add / molbio_paper_list / molbio_paper_update / molbio_paper_remove (papers.json in the workspace).
 
 Cloning workflow rules (follow them to avoid slow re-derivation):
@@ -7650,6 +8133,7 @@ export function apply(ctx) {
     silentSiteTool,
     verifySangerTool(ctx),
     proteinPropsTool,
+    proteinChargeTool(ctx),
     peptideDigestTool,
     codonOptimizeTool,
     helicalWheelTool(ctx),
@@ -7666,10 +8150,13 @@ export function apply(ctx) {
     fastaFastqTool(ctx),
     batchAnalyzeTool(ctx),
     fastqQcTool(ctx),
+    contaminationScreenTool(ctx),
+    fastqTrimTool(ctx),
     codonUsageTool,
     phylogeneticTreeTool(ctx),
     pcrSimulateTool(ctx),
     gcCompositionTool(ctx),
+    dotplotTool(ctx),
     extractRegionTool(ctx),
     pubmedAbstractTool(ctx),
     bibtexTool(ctx),