# Clade Desk

> Paste a FASTA alignment, its Newick or NHX tree and a few lines of run notes.
> A free in-browser reader parses both files, draws the tree and measures it.
> Then one of three lanes turns those measurements into a review: alignment
> quality control, a tree and support audit, or a journal figure specification.

Live at https://clade-desk.skillsafe.ai/ · API tutorial at /api.html · token panel at /tokens.html

## What problem it solves

A finished phylogeny is three artefacts - an alignment, a tree, and the notes
saying what produced them - and the mistakes that reach reviewers are almost
always in the gaps between them. The tree's taxon set does not match the
alignment's. The support values were graded against 70 when the run used
ultrafast bootstrap, whose threshold is 95. A ragged 5' end contributes columns
where only four of eighteen sequences have residues. A terminal branch eight
times the median length is a paralogue nobody looked at. The figure shows a
weakly supported clade as a solid coloured group.

Clade Desk reads all three artefacts together, measures what can be measured in
the browser for free, and then holds a model review accountable to those
measurements.

## The three lanes

One work object - the same alignment, tree and notes - and one `task` field
routes between them.

| `task` | What it produces |
| --- | --- |
| `align-qc` | 1-based column ranges to keep and drop, a per-taxon keep / trim / drop / resequence call, and a trimming recipe. |
| `tree-audit` | Rooting and outgroup assessment, a per-node solid / weak / collapse call, topology flags, and a support statement using the correct threshold. |
| `figure-spec` | Panel sizes in millimetres for the target journal, a colourblind-safe palette with hex values, display rules, typography, scale bar and a caption. |

Each lane's result panel carries a button that carries the finding into the next
lane over the same files, without a page reload.

## What the free in-browser pass measures

No account, no credits, no network. This is a real reader, not a character count.

**Newick and NHX.** A recursive-descent tokenizer that handles quoted labels
containing parentheses and commas, `[bracketed comments]`, `[&&NHX:...]`
annotations, negative and scientific-notation branch lengths, an internal support
label sitting at the very end of the string (`(A,B)100;` and even `(A,B)100` with
the semicolon missing), polytomies, and a degree-three root meaning the tree is
unrooted. IQ-TREE's combined `SH-aLRT/UFBoot` labels - `98.7/100` - are read as
**two** series and graded against **two** thresholds, because taking only the
first number reports one metric under the other's bar.

Derived: tip and internal node counts, root degree, total tree length, missing /
zero / negative branch lengths, polytomies, duplicate tip labels, tip labels that
break common viewers, the support distribution per series with its scale
(`0-1` or `0-100`) and threshold, ultrametricity, and the longest terminal branch
as a ratio to the median.

**FASTA.** Per-column occupancy, all-gap columns, constant / variable /
parsimony-informative site counts, per-taxon gap and ambiguity fractions,
characters outside the inferred alphabet **with their 1-based positions**,
internal stop codons distinguished from a correct terminal stop, duplicate
identifiers, sequences identical once gaps are removed, lower-case soft masking,
and whether the sequences are aligned at all. The alphabet is inferred from
composition and can be overridden.

**Concordance.** Tree tip labels against alignment identifiers, in both
directions - and a normalised comparison that separates a genuinely missing taxon
from a label that differs only by an underscore or a space. A rename and a redo
are not the same problem, and they are not graded the same.

**The run notes, in three states rather than two.** `bootstrap: n/a`,
`no bootstrap` and `bootstrap was not run` all read as **absent**;
`support: UFBoot, no gaps trimmed` reads as **present**, because the trailing
"no" belongs to the gaps; saying nothing at all reads as **unstated** and is
reported as such rather than guessed at. Replicate counts are only read where a
bootstrap token vouches for them, so `IQ-TREE 2.2.0` can never be reported as two
replicates, and `1,000 replicates` parses as 1000.

**The drawing.** A rectangular phylogram with a scale bar when every branch has a
length, and a rectangular cladogram - with the scale bar suppressed and a note
saying horizontal distance means nothing - when any length is missing. Never a
phylogram with invented lengths, because a drawn branch is a claim about
evolutionary distance. Support labels below the threshold are marked. Exportable
as a standalone SVG.

## How the free lane and the paid lane are tied together

Everything measured above is sent to the model as `prescan_facts`, and every flag
in it must be reconciled exactly once in the model's `reconciliation` array. The
result page shows both directions of failure: a flag the review never mentioned,
and an id the review reconciled that the prescan never sent. Counts are derived
from the arrays they describe in the same pass, so a total can never contradict
its own list, and a taxon flagged twice is counted once.

Severity moves with the mitigating facts already computed. Weak support confined
to terminal sister pairs is graded one step below weak support on the backbone.
A gappy alignment the notes say was trimmed with trimAl is graded one step below
an untrimmed one. Negative branch lengths of tiny magnitude from a distance
method are graded below negative branch lengths in a maximum-likelihood tree. A
taxon-set mismatch fully explained by underscore-versus-space naming is a rename,
not missing data.

The prescan and the model share one three-word verdict vocabulary - `clean`,
`attention`, `blocking` - so a clean result can never render as a bad one.

## Output contract

One JSON object. Common envelope across every lane: `lane`, `subject`, `verdict`,
`headline`, `summary[]`, `findings[]` (`id`, `title`, `severity`, `where`,
`evidence`, `why`, `fix`, `prescan_ids[]`), `reconciliation[]` (`fact_id`,
`addressed`, `note`), `assumptions[]`, `open_questions[]`, `methods_sentence`.
Severity is `critical` / `high` / `medium` / `low`; verdict is `clean` /
`attention` / `blocking`.

Lane bodies: `align-qc` adds `sites`, `taxa_actions` and `trim_recipe`;
`tree-audit` adds `rooting`, `nodes`, `topology_flags` and `support_statement`;
`figure-spec` adds `panels`, `display_rules`, `palette`, `typography`,
`scale_bar`, `caption` and `export_checklist`.

## Other behaviour worth knowing

- **Everything free stays free at a zero balance.** The prescan, the drawing, the
  SVG export, the prescan download and both bundled examples - including their
  saved model runs, one per lane - work signed out and with no credits. Only the
  review itself is metered, and only that button is gated on the balance.
- **Clipping is announced.** Sequences are cut on whole-record boundaries, chosen
  by a low-discrepancy golden-ratio draw rather than an every-k-th stride, and
  the first record, the last record and every taxon carrying a finding are always
  kept. Wide alignments drop the middle columns with the cut stated. A Newick
  string over budget is **withheld rather than truncated**, because a cut Newick
  string parses as a different tree.
- **History belongs to the account.** Audits are written to a declared `audits`
  collection and mirrored in the browser, filterable by lane, restorable with or
  without the files that produced them, and honest when the stored copy was
  trimmed to fit the record size cap.
- **Export.** Markdown, JSON, a findings CSV, the prescan as Markdown, the tree
  as SVG, and print.
- **What it does not do.** It does not run an aligner, infer a tree, or check
  sequences against a database. It reads what you give it.

## Sources

Derived from three agent skills on SkillSafe:

- https://skillsafe.ai/skill/@k-dense-ai/etetoolkit/ - phylogenetic tree toolkit
  (ETE): Newick and NHX manipulation, evolutionary event detection, orthology and
  paralogy, NCBI taxonomy, visualisation.
- https://skillsafe.ai/skill/@k-dense-ai/scikit-bio/ - biological data toolkit:
  sequence analysis, alignments, phylogenetic trees, diversity metrics, FASTA and
  Newick I/O.
- https://skillsafe.ai/skill/@k-dense-ai/scientific-visualization/ -
  publication-ready figures: multi-panel layouts, significance annotations,
  colourblind-safe palettes, journal formatting.

This is a derived work. It is not affiliated with those skills' authors, nor with
the ETE, scikit-bio, MAFFT, trimAl, ClipKIT, IQ-TREE, RAxML, FastTree or MrBayes
projects, nor with Nature, Science, Cell, PLOS, BMC or any other journal named in
the figure lane.

Model: `gpt-terra` (currently `gpt-5.6-terra`). Publisher markup 1000 bps.