@plantnet/planttaxomatcher 0.3.0 → 0.4.0

package/dist/index.js

@@ -251,6 +251,8 @@ var wcvpSnapshotSummarySchema = z4.object({
   importedAt: z4.string().datetime(),
   /** Newest OFFICIAL snapshot (derived ones never count as latest). */
   isLatest: z4.boolean(),
+  /** The version a job uses when none is named: the team's default if still visible, else the latest. */
+  isDefault: z4.boolean(),
   kind: z4.enum(["official", "derived"]),
   baseVersion: z4.string().nullable(),
   label: z4.string().nullable(),
@@ -1046,6 +1048,8 @@ var wfoSnapshotSummarySchema = z8.object({
   recordCount: z8.number().int().nonnegative(),
   importedAt: z8.string().datetime(),
   isLatest: z8.boolean(),
+  /** The version a job uses when none is named: the team's default if still visible, else the latest. */
+  isDefault: z8.boolean(),
   kind: snapshotKindSchema,
   baseVersion: z8.string().nullable(),
   label: z8.string().nullable(),
@@ -1358,6 +1362,87 @@ function parseEnvFlag(raw, fallback) {
 // ../shared/src/public-server.ts
 var DEFAULT_SERVER_URL = "https://planttaxomatcher.plantnet.org";
 
+// ../shared/src/export-columns.ts
+import { z as z11 } from "zod";
+var RESULT_COLUMN_DESCRIPTIONS = {
+  planttaxomatcher_job_id: "Id of the job this row belongs to.",
+  planttaxomatcher_input_normalized: "The input name as it was matched, after cleaning (spacing, case, qualifiers removed).",
+  planttaxomatcher_input_qualifier: "Identification qualifier found in the input: cf, aff, sensu_lato, sensu_stricto, aggregate, complex, sp, spp, indet, cultivar, hybrid_formula, informal. Empty when none.",
+  planttaxomatcher_parse_quality: "How cleanly the name parsed (gnparser): 1 clean, 2 minor issues, 3 significant issues, 4 badly formed; empty when unparsed.",
+  planttaxomatcher_match_status: "matched, ambiguous (several candidates, none chosen), no_match, error, or skipped (filtered out, or no usable name).",
+  planttaxomatcher_evidence_type: "How the match was found: local_exact, local_canonical_unique, local_fuzzy, external_validated, external_fuzzy, team_history, cross_backbone, llm.",
+  planttaxomatcher_grade: "A (confident, accepted automatically), B (plausible, needs review) or C (weakest: a language-model suggestion or genus only).",
+  planttaxomatcher_review_status: "not_required (grade A), pending (waiting for review), accepted, rejected, or overridden (a reviewer picked another taxon).",
+  planttaxomatcher_confidence: "Match score between 0 and 1.",
+  planttaxomatcher_score_breakdown: "JSON of the score components: canonical, author, rank and family similarity, provider agreement.",
+  planttaxomatcher_layer: "The cascade layer family that settled the row (same values as the evidence type).",
+  planttaxomatcher_reason: "One-line explanation of the decision.",
+  planttaxomatcher_flags: "Comma-separated reasons a match needs a look, e.g. author-unconfirmed, author-mismatch, genus-fallback.",
+  planttaxomatcher_matched_identifier_namespace: "Namespace of the matched name\u2019s identifier, e.g. wcvp:taxonID or wfo:taxonID.",
+  planttaxomatcher_matched_identifier: "Identifier of the matched name (possibly a synonym).",
+  planttaxomatcher_accepted_identifier_namespace: "Namespace of the accepted taxon\u2019s identifier: wcvp:acceptedNameUsageID or wfo:acceptedNameUsageID.",
+  planttaxomatcher_accepted_identifier: "Identifier of the accepted taxon, in the job\u2019s backbone (WCVP or WFO).",
+  plantnet_identifiable: "true when Pl@ntNet can identify the accepted taxon from photos (when Pl@ntNet is enabled).",
+  plantnet_id: "Pl@ntNet species id of the accepted taxon (when Pl@ntNet is enabled).",
+  wcvp_matched_name: "The backbone name the input matched, which may be a synonym.",
+  wcvp_matched_taxonomic_status: "Status of the matched name in the backbone, e.g. Accepted, Synonym or Illegitimate.",
+  wcvp_accepted_name: "The accepted name the match resolves to, without author.",
+  wcvp_accepted_author: "Author of the accepted name.",
+  wcvp_accepted_name_with_author: "The accepted name and its author in one cell, ready to cite, e.g. Calicotome spinosa (L.) Link. The column to hand back as the cleaned name.",
+  wcvp_accepted_taxon_id: "WCVP id (plant_name_id) of the accepted taxon. Empty for WFO jobs, whose id is in planttaxomatcher_accepted_identifier.",
+  wcvp_accepted_usage_id: "Same id as wcvp_accepted_taxon_id, under its Darwin Core name (acceptedNameUsageID).",
+  ipni_lsid: "IPNI LSID of the accepted name: urn:lsid:ipni.org:names: followed by its IPNI id.",
+  powo_url: "Plants of the World Online page of the accepted taxon.",
+  wcvp_family: "Family of the accepted taxon.",
+  wcvp_rank: "Rank of the accepted taxon, e.g. Species, Subspecies, Variety or Genus.",
+  planttaxomatcher_alternatives: "JSON list of the other candidates, mostly for ambiguous rows.",
+  planttaxomatcher_reviewed: "true when a person reviewed the row.",
+  planttaxomatcher_referential_version: "Backbone version the job matched against, e.g. wcvp-v14.",
+  planttaxomatcher_normalizer_version: "Version of the name normaliser, for reproducibility.",
+  planttaxomatcher_parser_version: "Version of the name parser, for reproducibility.",
+  planttaxomatcher_matcher_version: "Version of the matching cascade, for reproducibility.",
+  planttaxomatcher_scoring_version: "Version of the grading rules, for reproducibility."
+};
+var taxonLevelSchema = z11.enum(["all", "species_below", "species_only"]);
+var WCVP_EXTRA_DESCRIPTIONS = {
+  ipni_id: "IPNI id of the name (the part after urn:lsid:ipni.org:names:).",
+  powo_id: "Plants of the World Online id of the taxon.",
+  plant_name_id: "WCVP id of the record.",
+  accepted_plant_name_id: "WCVP id of the accepted name the record points to.",
+  basionym_plant_name_id: "WCVP id of the basionym (the original name this one is based on).",
+  parent_plant_name_id: "WCVP id of the parent taxon, e.g. the species of a variety.",
+  taxon_authors: "Full author string of the name.",
+  primary_author: "Author or authors who published the name.",
+  parenthetical_author: "Author of the basionym, shown in parentheses in the author string.",
+  publication_author: "Author of the book or article where the name was published, when different.",
+  first_published: "Year of first publication.",
+  place_of_publication: "Journal or book where the name was published.",
+  volume_and_page: "Volume and page of the publication.",
+  geographic_area: "Native distribution, as a short narrative statement.",
+  climate_description: "Habitat or climate type, from published habitat information.",
+  lifeform_description: "Life form, in a modified Raunki\xE6r system (e.g. phanerophyte).",
+  homotypic_synonym: "Whether the name is a homotypic synonym (same type as the accepted name).",
+  replaced_synonym_author: "Author of the replaced synonym, for a replacement name.",
+  nomenclatural_remarks: "Nomenclatural notes, e.g. nom. illeg.",
+  genus_hybrid: "Hybrid marker (\xD7) of the genus, when it is a hybrid.",
+  species_hybrid: "Hybrid marker (\xD7) of the species, when it is a hybrid.",
+  hybrid_formula: "Hybrid formula, e.g. Mentha aquatica \xD7 M. spicata.",
+  infraspecies: "Infraspecific epithet.",
+  infraspecific_rank: "Infraspecific rank, e.g. subsp., var. or f.",
+  species: "Species epithet.",
+  taxon_name: "Full name without author.",
+  reviewed: "Whether Kew has peer-reviewed the family of this taxon.",
+  pn_change: "Team-edited versions only: what the team changed on this record (codes such as re_accept;author).",
+  pn_source: "Team-edited versions only: source of the change.",
+  pn_taxon_id: "Team-edited versions only: the team\u2019s own taxon id.",
+  wcvp13_taxon_status: "Team-edited versions only: taxonomic status before the edit (WCVP v13).",
+  wcvp13_accepted_plant_name_id: "Team-edited versions only: accepted name id before the edit (WCVP v13).",
+  wcvp13_taxon_name: "Team-edited versions only: name before the edit (WCVP v13).",
+  wcvp13_taxon_authors: "Team-edited versions only: authors before the edit (WCVP v13).",
+  wcvp13_family: "Team-edited versions only: family before the edit (WCVP v13).",
+  wcvp13_genus: "Team-edited versions only: genus before the edit (WCVP v13)."
+};
+
 // src/errors.ts
 import { CommanderError } from "commander";
 var EXIT = {
@@ -1463,10 +1548,15 @@ function downloadFilename(contentDisposition, jobId, opts) {
   if (suggested && suggested !== "." && suggested !== "..") return suggested;
   return `planttaxomatcher_${jobId}.${opts.bundle ? "zip" : opts.format}`;
 }
+function filterParams(filters, params = new URLSearchParams()) {
+  if (filters.confirmedOnly) params.set("confirmedOnly", "true");
+  if (filters.resolvedOnly) params.set("notEmptyOnly", "true");
+  if (filters.dedupe) params.set("dedupe", "true");
+  if (filters.taxonLevel && filters.taxonLevel !== "all") params.set("taxonLevel", filters.taxonLevel);
+  return params;
+}
 function downloadQuery(opts) {
-  const params = new URLSearchParams({ format: opts.format });
-  if (opts.confirmedOnly) params.set("confirmedOnly", "true");
-  if (opts.dedupe) params.set("dedupe", "true");
+  const params = filterParams(opts, new URLSearchParams({ format: opts.format }));
   if (opts.bundle) params.set("bundle", "true");
   if (opts.delimiter) params.set("delimiter", opts.delimiter);
   if (opts.columns) params.set("columns", opts.columns);
@@ -1567,6 +1657,15 @@ function createApiClient(options = {}) {
     },
     getJob: (c, id) => call(c, `/v1/jobs/${encodeURIComponent(id)}`),
     downloadColumns: (c, id) => call(c, `/v1/jobs/${encodeURIComponent(id)}/download/columns`),
+    downloadCounts(c, id, filters) {
+      const query = filterParams(filters);
+      const suffix = query.size > 0 ? `?${query}` : "";
+      return call(c, `/v1/jobs/${encodeURIComponent(id)}/download/count${suffix}`);
+    },
+    listVersions: (c, backbone) => call(c, `/v1/${backbone}/snapshots`),
+    async listAreas(c) {
+      return (await call(c, "/v1/wgsrpd/areas")).areas;
+    },
     pauseJob: (c, id) => call(c, `/v1/jobs/${encodeURIComponent(id)}/pause`, { method: "POST" }),
     resumeJob: (c, id) => call(c, `/v1/jobs/${encodeURIComponent(id)}/resume`, { method: "POST" }),
     cancelJob: (c, id) => call(c, `/v1/jobs/${encodeURIComponent(id)}/cancel`, { method: "POST" }),
@@ -1805,7 +1904,7 @@ function defaultDeps() {
 
 // src/program.ts
 import { Command } from "commander";
-import kleur9 from "kleur";
+import kleur10 from "kleur";
 
 // src/output.ts
 import kleur from "kleur";
@@ -1980,11 +2079,124 @@ function registerAuthCommands(program, deps2) {
   });
 }
 
+// src/commands/catalog.ts
+import kleur3 from "kleur";
+
+// src/catalog.ts
+function parseBackbone(value) {
+  const parsed = backboneSchema.safeParse(value.trim().toLowerCase());
+  if (!parsed.success) throw new CliError(`--backbone must be wcvp or wfo (got "${value}")`, EXIT.usage);
+  return parsed.data;
+}
+function toVersionEntries(backbone, summaries) {
+  return summaries.map((s) => ({
+    backbone,
+    version: s.version,
+    kind: s.kind,
+    label: s.label,
+    baseVersion: s.baseVersion,
+    isLatest: s.isLatest,
+    // Servers before isDefault fall back to "latest", which is what they used.
+    isDefault: s.isDefault ?? s.isLatest,
+    recordCount: s.recordCount,
+    importedAt: s.importedAt
+  }));
+}
+var MAX_LISTED = 12;
+function requireVersion(entries, backbone, requested) {
+  const found = entries.find((e) => e.version === requested);
+  if (found) return found;
+  const available = entries.map((e) => e.version);
+  const listed = available.slice(0, MAX_LISTED).join(", ") + (available.length > MAX_LISTED ? ", \u2026" : "");
+  throw new CliError(
+    `no ${backbone.toUpperCase()} version "${requested}"${available.length ? ` (available: ${listed})` : ""}`,
+    EXIT.usage,
+    `Run \`planttaxomatcher versions --backbone ${backbone}\` to see them all.`
+  );
+}
+function matches(area, needle) {
+  return [area.code, area.name, area.region, area.continent].some((field) => field?.toLowerCase().includes(needle));
+}
+function searchAreas(areas, search) {
+  const needle = search?.trim().toLowerCase();
+  return needle ? areas.filter((area) => matches(area, needle)) : areas;
+}
+function requireArea(areas, requested) {
+  const code = requested.trim().toUpperCase();
+  const found = areas.find((a) => a.code.toUpperCase() === code);
+  if (found) return found;
+  const suggestions = searchAreas(areas, requested).slice(0, 5).map((a) => `${a.code} (${a.name ?? "?"})`);
+  throw new CliError(
+    `unknown area "${requested}"${suggestions.length ? `; did you mean ${suggestions.join(", ")}?` : ""}`,
+    EXIT.usage,
+    `--area takes a WGSRPD level-3 code: \`planttaxomatcher areas --search ${requested.trim()}\`.`
+  );
+}
+function describeVersion(e) {
+  const tags = [e.isDefault ? "default" : null, e.isLatest ? "latest" : null].filter(Boolean).join(", ");
+  const origin = e.kind === "derived" ? `team-edited from ${e.baseVersion ?? "?"}` : "official";
+  const label = e.label ? ` \u201C${e.label}\u201D` : "";
+  return `  ${e.version.padEnd(28)} ${origin}${label}${tags ? `  [${tags}]` : ""}  ${e.recordCount.toLocaleString("en")} names, imported ${e.importedAt.slice(0, 10)}`;
+}
+function versionLines(entries) {
+  const lines = [];
+  for (const backbone of ["wcvp", "wfo"]) {
+    const ofBackbone = entries.filter((e) => e.backbone === backbone);
+    if (ofBackbone.length === 0) continue;
+    lines.push(backbone.toUpperCase(), ...ofBackbone.map(describeVersion));
+  }
+  return lines;
+}
+function areaLine(area) {
+  const place2 = [area.region, area.continent].filter(Boolean).join(", ");
+  return `${area.code.padEnd(4)} ${area.name ?? ""}${place2 ? `  (${place2})` : ""}`;
+}
+
+// src/commands/catalog.ts
+async function fetchVersions(deps2, creds, backbone) {
+  return toVersionEntries(backbone, await deps2.api.listVersions(creds, backbone));
+}
+function registerCatalogCommands(program, deps2) {
+  program.command("versions").description(
+    "List the backbone versions a job can match against (--referential), marking the one used by default"
+  ).option("--backbone <name>", "Only this backbone: wcvp or wfo (default: both)").option("--json", "Print the versions as a JSON array", false).action(async (opts) => {
+    const out = createOutput(deps2.stdout, deps2.stderr, opts.json, deps2.now);
+    const backbones = opts.backbone ? [parseBackbone(opts.backbone)] : backboneSchema.options;
+    const creds = await requireCredentials(deps2.store, deps2.env);
+    const entries = (await Promise.all(backbones.map((b) => fetchVersions(deps2, creds, b)))).flat();
+    if (out.json) return out.data(entries);
+    if (entries.length === 0) return out.info(kleur3.gray("No backbone version is installed on this server."));
+    for (const line of versionLines(entries)) out.info(line);
+  });
+  program.command("areas").description("List the WGSRPD level-3 areas (botanical countries) that --area accepts").option("--search <text>", "Only areas whose code, name, region or continent contains this text").option("--json", "Print the areas as a JSON array", false).action(async (opts) => {
+    const out = createOutput(deps2.stdout, deps2.stderr, opts.json, deps2.now);
+    const creds = await requireCredentials(deps2.store, deps2.env);
+    const areas = searchAreas(await deps2.api.listAreas(creds), opts.search);
+    if (out.json) return out.data(areas);
+    if (areas.length === 0) return out.info(kleur3.gray("No matching area."));
+    for (const area of areas) out.info(areaLine(area));
+  });
+}
+
 // src/commands/download.ts
 import { writeFile } from "fs/promises";
-import kleur3 from "kleur";
+import kleur4 from "kleur";
 var FORMATS = ["csv", "xlsx", "json", "ndjson"];
 var DELIMITERS = ["comma", "semicolon", "tab", "pipe"];
+var TAXON_LEVELS = taxonLevelSchema.options;
+function toDownloadFilters(opts) {
+  const parsed = taxonLevelSchema.safeParse(opts.taxonLevel);
+  if (!parsed.success) {
+    throw new CliError(`--taxon-level must be ${TAXON_LEVELS.join(", ")} (got ${opts.taxonLevel})`, EXIT.usage);
+  }
+  const taxonLevel = parsed.data;
+  return {
+    confirmedOnly: opts.confirmedOnly,
+    resolvedOnly: opts.resolvedOnly,
+    dedupe: opts.dedupe,
+    ...taxonLevel !== "all" ? { taxonLevel } : {}
+  };
+}
 function toDownloadOptions(opts) {
   const format = opts.format;
   if (!FORMATS.includes(format)) {
@@ -1996,43 +2208,90 @@ function toDownloadOptions(opts) {
   }
   return {
     format,
-    confirmedOnly: opts.confirmedOnly,
-    dedupe: opts.dedupe,
+    ...toDownloadFilters(opts),
     bundle: opts.bundle,
     ...format === "csv" && delimiter !== "comma" ? { delimiter } : {},
     ...opts.columns ? { columns: opts.columns } : {},
     ...opts.wcvpExtra ? { wcvpExtra: opts.wcvpExtra } : {}
   };
 }
+function describeColumns(columns) {
+  return {
+    result: columns.result.map((c) => ({
+      ...c,
+      description: c.description ?? RESULT_COLUMN_DESCRIPTIONS[c.key] ?? null
+    })),
+    original: columns.original,
+    wcvpExtra: columns.wcvpExtra.map((f) => ({
+      ...f,
+      description: f.description ?? WCVP_EXTRA_DESCRIPTIONS[f.key] ?? null
+    }))
+  };
+}
 function printColumns(out, columns) {
-  out.info(kleur3.bold("Result columns (--columns):"));
-  for (const column of columns.result) out.info(`  ${column.key}  ${kleur3.gray(`(${column.group})`)}`);
+  const line = (key, description) => out.info(`  ${key}${description ? `
+      ${kleur4.gray(description)}` : ""}`);
+  out.info(kleur4.bold("Result columns (--columns):"));
+  for (const column of columns.result) line(column.key, column.description);
   if (columns.original.length > 0) {
-    out.info(kleur3.bold("\nYour upload columns (--columns):"));
-    for (const key of columns.original) out.info(`  ${key}`);
+    out.info(kleur4.bold("\nYour upload columns (--columns):"));
+    for (const key of columns.original) line(key);
+  }
+  out.info(kleur4.bold("\nWCVP fields to append (--wcvp-extra), exported as wcvp_<field>:"));
+  for (const field of columns.wcvpExtra) line(field.key, field.description);
+}
+function printCounts(out, counts) {
+  const rows = [
+    ["all rows", counts.total, ""],
+    ["confirmed only", counts.confirmed, "--confirmed-only"],
+    ["resolved only", counts.resolved, "--resolved-only"],
+    ["one row per accepted taxon", counts.deduped, "--dedupe"],
+    ["with the filters given", counts.selected, ""]
+  ];
+  for (const [label, count, flag] of rows) {
+    out.info(`  ${label.padEnd(28)} ${String(count).padStart(8)}  ${kleur4.gray(flag)}`);
   }
-  out.info(kleur3.bold("\nWCVP extra fields (--wcvp-extra):"));
-  for (const field of columns.wcvpExtra) out.info(`  ${field.key}  ${kleur3.gray(`(${field.group})`)}`);
 }
 function registerDownloadCommand(program, deps2) {
-  program.command("download <jobId>").description("Download a job export (CSV, XLSX, JSON or NDJSON; optionally zipped with NOTICE.md)").option("--format <fmt>", FORMATS.join(" | "), "csv").option("--confirmed-only", "Only matched rows that are accepted / not pending", false).option("--dedupe", "Collapse rows that resolved to the same accepted taxon to one line", false).option("--delimiter <sep>", `CSV separator: ${DELIMITERS.join(" | ")} (csv only)`, "comma").option("--bundle", "Wrap in a ZIP with NOTICE.md citing the WCVP snapshot and providers", false).option(
+  program.command("download <jobId>").description("Download a job export (CSV, XLSX, JSON or NDJSON; optionally zipped with NOTICE.md)").option("--format <fmt>", FORMATS.join(" | "), "csv").option(
+    "--confirmed-only",
+    "Confirmed rows only: accepted automatically (grade A) or by a reviewer, or overridden",
+    false
+  ).option(
+    "--resolved-only",
+    "Resolved rows only: drop rows with no accepted name (no match, error, rejected)",
+    false
+  ).option(
+    "--dedupe",
+    "Remove duplicate accepted taxa: rows resolving to the same accepted taxon (synonyms, subspecies\u2026) become one line; unmatched rows are kept",
+    false
+  ).option(
+    "--taxon-level <level>",
+    "Keep rows whose accepted taxon is at this level: all, species_below (species and infraspecific, drops genus/family), species_only. Unmatched rows are kept; add --resolved-only to drop them",
+    "all"
+  ).option("--delimiter <sep>", `CSV separator: ${DELIMITERS.join(" | ")} (csv only)`, "comma").option("--bundle", "Wrap in a ZIP with NOTICE.md citing the WCVP snapshot and providers", false).option(
     "--columns <list>",
     "Comma-separated result/upload column keys to keep (default: all). See --list-columns"
   ).option(
     "--wcvp-extra <list>",
     "Comma-separated extra WCVP fields appended as wcvp_<key> columns (e.g. ipni_id,powo_id). See --list-columns"
-  ).option("--list-columns", "Print the columns available for this job and exit", false).option(
+  ).option("--list-columns", "Print the columns available for this job, with what each holds, and exit", false).option("--counts", "Print how many rows each filter keeps (as the web download dialog shows) and exit", false).option(
     "--output <path>",
     "Write to this path (default: the server-provided file name in the current directory)"
-  ).option("--json", "Print the result (or --list-columns) as JSON", false).action(async (jobId, opts) => {
+  ).option("--json", "Print the result (or --list-columns / --counts) as JSON", false).action(async (jobId, opts) => {
     const out = createOutput(deps2.stdout, deps2.stderr, opts.json, deps2.now);
     const download = toDownloadOptions(opts);
     const creds = await requireCredentials(deps2.store, deps2.env);
     if (opts.listColumns) {
-      const columns = await deps2.api.downloadColumns(creds, jobId);
+      const columns = describeColumns(await deps2.api.downloadColumns(creds, jobId));
       if (out.json) return out.data(columns);
       return printColumns(out, columns);
     }
+    if (opts.counts) {
+      const counts = await deps2.api.downloadCounts(creds, jobId, toDownloadFilters(opts));
+      if (out.json) return out.data(counts);
+      return printCounts(out, counts);
+    }
     const { filename, body } = await deps2.api.downloadJob(creds, jobId, download);
     const path = opts.output ?? filename;
     await writeFile(path, body);
@@ -2042,7 +2301,7 @@ function registerDownloadCommand(program, deps2) {
 }
 
 // src/commands/jobs.ts
-import kleur5 from "kleur";
+import kleur6 from "kleur";
 
 // src/flags.ts
 function parseIntegerFlag(value, flag, range = {}) {
@@ -2056,7 +2315,7 @@ function parseIntegerFlag(value, flag, range = {}) {
 }
 
 // src/watch.ts
-import kleur4 from "kleur";
+import kleur5 from "kleur";
 var STOP = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "paused"]);
 function isStop(status) {
   return typeof status === "string" && STOP.has(status);
@@ -2079,15 +2338,15 @@ function render(out, frame) {
   }
   if (frame.type === "status") {
     out.progress.done();
-    out.info(`${kleur4.gray("\u2022")} ${String(frame.status)}`);
+    out.info(`${kleur5.gray("\u2022")} ${String(frame.status)}`);
   } else if (frame.type === "error") {
     out.progress.done();
-    out.info(`${kleur4.red("error:")} ${String(frame.message ?? "job failed")}`);
+    out.info(`${kleur5.red("error:")} ${String(frame.message ?? "job failed")}`);
   }
 }
 async function watchJob(api, out, creds, jobId) {
   out.progress.done();
-  if (!out.json) out.info(`${kleur4.cyan("\u2192")} Streaming progress for ${jobId} \u2026`);
+  if (!out.json) out.info(`${kleur5.cyan("\u2192")} Streaming progress for ${jobId} \u2026`);
   for await (const frame of api.streamJob(creds, jobId)) {
     if (frame.type === "heartbeat") continue;
     const status = stopStatusOf(frame);
@@ -2108,8 +2367,8 @@ function finish(out, status) {
   out.progress.done();
   if (!out.json) {
     if (status === "completed") out.success("completed");
-    else if (status === "paused") out.info(kleur4.yellow("paused \u2014 resume it, then watch again"));
-    else out.info(kleur4.red(`\u2717 ${status}`));
+    else if (status === "paused") out.info(kleur5.yellow("paused \u2014 resume it, then watch again"));
+    else out.info(kleur5.red(`\u2717 ${status}`));
   }
   return status;
 }
@@ -2131,7 +2390,7 @@ function watchOutcomeError(results) {
 }
 function listLine(job) {
   const matched = `${String(job.matchedRows).padStart(6)}/${String(job.totalRows).padStart(6)} matched`;
-  return `${job.id}  ${job.status.padEnd(10)}  ${matched}  ${kleur5.gray(job.name ?? "")}`;
+  return `${job.id}  ${job.status.padEnd(10)}  ${matched}  ${kleur6.gray(job.name ?? "")}`;
 }
 var JOB_ACTIONS = {
   pause: { description: "Pause a running job (the worker stops between match queries)", past: "paused" },
@@ -2154,7 +2413,7 @@ function registerJobCommands(program, deps2) {
     const creds = await requireCredentials(deps2.store, deps2.env);
     const jobs = await deps2.api.listJobs(creds, { limit, ...status ? { status: status.data } : {} });
     if (out.json) return out.data(jobs);
-    if (jobs.length === 0) return out.info(kleur5.gray("No jobs."));
+    if (jobs.length === 0) return out.info(kleur6.gray("No jobs."));
     for (const job of jobs) out.info(listLine(job));
   });
   program.command("status <jobId>").description("Print a job snapshot as JSON (counts, status, timestamps)").option("--json", "Accepted for symmetry: the output is always JSON", false).action(async (jobId) => {
@@ -2182,7 +2441,7 @@ function registerJobCommands(program, deps2) {
 }
 
 // src/commands/skills.ts
-import kleur6 from "kleur";
+import kleur7 from "kleur";
 
 // src/skills/manage.ts
 import { promises as fs3 } from "fs";
@@ -2201,11 +2460,31 @@ async function walk(dir, root = dir) {
   }
   return found.sort();
 }
+function table(rows, keyOf) {
+  const lines = Object.entries(rows).map(([key, description]) => `| \`${keyOf(key)}\` | ${description} |`);
+  return ["| Column | What it holds |", "| --- | --- |", ...lines].join("\n");
+}
+function exportColumnsMarkdown() {
+  return [
+    "## Every column",
+    "",
+    table(RESULT_COLUMN_DESCRIPTIONS, (key) => key),
+    "",
+    "## Fields `--wcvp-extra` can append",
+    "",
+    "Columns of the accepted taxon's WCVP record, exported as `wcvp_<field>`, e.g. `--wcvp-extra ipni_id,powo_id`.",
+    "",
+    table(WCVP_EXTRA_DESCRIPTIONS, (key) => key)
+  ].join("\n");
+}
 async function renderSkill(sourceDir, version2) {
   const files = /* @__PURE__ */ new Map();
   for (const path of await walk(sourceDir)) {
     const text = await fs2.readFile(join3(sourceDir, path), "utf8");
-    files.set(path, text.replaceAll("{{version}}", version2));
+    files.set(
+      path,
+      text.replaceAll("{{version}}", version2).replaceAll("{{exportColumns}}", exportColumnsMarkdown())
+    );
   }
   return files;
 }
@@ -2435,7 +2714,7 @@ function tilde(path, home) {
 }
 function printEntries(out, result, home) {
   for (const { dir, path, action } of result.entries) {
-    const line = `${SERVES[dir]}: ${ACTION_TEXT[action]} ${kleur6.gray(tilde(path, home))}`;
+    const line = `${SERVES[dir]}: ${ACTION_TEXT[action]} ${kleur7.gray(tilde(path, home))}`;
     if (action.startsWith("skipped")) out.warn(line);
     else out.success(line);
   }
@@ -2455,17 +2734,17 @@ function registerSkillsCommands(program, deps2, version2) {
     const result = await installSkill(paths(), deps2.skillSource, version2, agents, { force: opts.force });
     if (out.json) return out.data({ version: version2, agents, ...result });
     out.info(
-      `${kleur6.bold("planttaxomatcher")} skill ${version2} \u2192 ${kleur6.gray(tilde(result.canonical, deps2.home))}`
+      `${kleur7.bold("planttaxomatcher")} skill ${version2} \u2192 ${kleur7.gray(tilde(result.canonical, deps2.home))}`
     );
     printEntries(out, result, deps2.home);
-    for (const agent of agents) if (RELOAD_HINTS[agent]) out.info(kleur6.gray(RELOAD_HINTS[agent]));
-    out.info(kleur6.gray(`Try it: ask your agent to "match the plant names in my CSV with PlantTaxoMatcher".`));
+    for (const agent of agents) if (RELOAD_HINTS[agent]) out.info(kleur7.gray(RELOAD_HINTS[agent]));
+    out.info(kleur7.gray(`Try it: ask your agent to "match the plant names in my CSV with PlantTaxoMatcher".`));
   });
   skills.command("uninstall").description("Remove the links and copies this CLI installed, then its own copy of the skill").option("--force", "Also remove copies edited by hand", false).option("--json", "Print the result as JSON", false).action(async (opts) => {
     const out = createOutput(deps2.stdout, deps2.stderr, opts.json, deps2.now);
     const result = await uninstallSkill(paths(), { force: opts.force });
     if (out.json) return out.data(result);
-    if (result.entries.length === 0) out.info(kleur6.gray("No installed skill links found."));
+    if (result.entries.length === 0) out.info(kleur7.gray("No installed skill links found."));
     printEntries(out, result, deps2.home);
   });
   skills.command("status").description("Show where the skill is installed and which copy each agent loads").option("--json", "Print the status as JSON", false).action(async (opts) => {
@@ -2474,28 +2753,28 @@ function registerSkillsCommands(program, deps2, version2) {
     if (out.json) return out.data({ cliVersion: version2, ...status });
     const { canonical } = status;
     out.info(
-      canonical.version ? `Skill ${canonical.version}${canonical.pristine ? "" : " (edited)"} at ${kleur6.gray(tilde(canonical.path, deps2.home))}` : kleur6.gray("Not installed. Run `planttaxomatcher skills install`.")
+      canonical.version ? `Skill ${canonical.version}${canonical.pristine ? "" : " (edited)"} at ${kleur7.gray(tilde(canonical.path, deps2.home))}` : kleur7.gray("Not installed. Run `planttaxomatcher skills install`.")
     );
     for (const entry of status.entries) {
       if (entry.kind !== "missing")
-        out.info(`  ${entry.kind.padEnd(8)} ${kleur6.gray(tilde(entry.path, deps2.home))}`);
+        out.info(`  ${entry.kind.padEnd(8)} ${kleur7.gray(tilde(entry.path, deps2.home))}`);
     }
     for (const { agent, installed, loads, state } of status.agents) {
       const entry = status.entries.find((e) => e.dir === loads);
       const where = entry ? `${state} in ${tilde(entry.path, deps2.home)}` : "no skill";
-      out.info(`  ${AGENT_NAMES[agent].padEnd(12)} ${installed ? where : kleur6.gray(`not found (${where})`)}`);
+      out.info(`  ${AGENT_NAMES[agent].padEnd(12)} ${installed ? where : kleur7.gray(`not found (${where})`)}`);
     }
   });
 }
 
 // src/commands/submit.ts
 import { parse as parsePath } from "path";
-import kleur8 from "kleur";
+import kleur9 from "kleur";
 
 // src/dry-run.ts
 import { promises as fs4, createReadStream } from "fs";
 import Papa from "papaparse";
-import kleur7 from "kleur";
+import kleur8 from "kleur";
 async function readSample(file, sampleLimit) {
   const lower = file.toLowerCase();
   if (lower.endsWith(".json")) {
@@ -2600,23 +2879,23 @@ async function buildDryRunReport(file, opts) {
 }
 function printDryRunReport(report, log) {
   log("");
-  log(kleur7.bold("Dry-run preview"));
+  log(kleur8.bold("Dry-run preview"));
   log(
-    `  Read ${kleur7.cyan(report.rowsRead)} rows \xB7 ${kleur7.yellow(report.nullNameCount)} with no usable name \xB7 ${kleur7.yellow(report.qualifierFlagCount)} with qualifier flags`
+    `  Read ${kleur8.cyan(report.rowsRead)} rows \xB7 ${kleur8.yellow(report.nullNameCount)} with no usable name \xB7 ${kleur8.yellow(report.qualifierFlagCount)} with qualifier flags`
   );
   if (report.idTypeDetection) {
     const d = report.idTypeDetection;
     const pct = Math.round(d.dominantConfidence * 100);
-    log(`  ID-column detection: ${kleur7.green(d.dominant ?? "\u2014")} (${pct}% of ${d.sampleSize} sampled)`);
+    log(`  ID-column detection: ${kleur8.green(d.dominant ?? "\u2014")} (${pct}% of ${d.sampleSize} sampled)`);
     if (d.minorityExamples.length > 0) {
       log(`  Minority examples:`);
       for (const m of d.minorityExamples) {
-        log(`    row ${m.rowIndex + 1}: ${kleur7.gray(m.value)} \u2192 ${kleur7.dim(m.type)}`);
+        log(`    row ${m.rowIndex + 1}: ${kleur8.gray(m.value)} \u2192 ${kleur8.dim(m.type)}`);
       }
     }
   }
   log("");
-  log(kleur7.bold("First rows after normalization:"));
+  log(kleur8.bold("First rows after normalization:"));
   log(`  ${"#".padStart(4)}  ${"input".padEnd(36)}  ${"normalized".padEnd(36)}  flags`);
   for (const r of report.sampleRows) {
     const idx = String(r.rowIndex + 1).padStart(4);
@@ -2677,7 +2956,9 @@ function buildJobConfig(opts) {
     speciesLevelAcceptedOnly: opts.speciesLevel,
     acceptUnconfirmedAuthor: opts.ignoreAuthor,
     exportConfirmedOnly: false,
-    ...opts.referential ? { referentialVersion: opts.referential } : {}
+    referential: parseBackbone(opts.backbone),
+    ...opts.referential ? { referentialVersion: opts.referential } : {},
+    ...opts.area?.trim() ? { area: opts.area.trim() } : {}
   };
   const checked = jobConfigSchema.safeParse(config);
   if (!checked.success) {
@@ -2700,13 +2981,20 @@ function summarize(submitted, finals, creds) {
     url: jobUrl(creds, job.id)
   }));
 }
+async function checkAgainstServer(deps2, creds, config) {
+  const backbone = config.referential ?? "wcvp";
+  if (config.referentialVersion) {
+    requireVersion(await fetchVersions(deps2, creds, backbone), backbone, config.referentialVersion);
+  }
+  if (config.area) config.area = requireArea(await deps2.api.listAreas(creds), config.area).code;
+}
 function jobNameFor(file, fileCount, name) {
   return fileCount === 1 && name?.trim() ? name.trim() : parsePath(file).name;
 }
 async function confirmDryRun(deps2, out, files, opts) {
   const previewRows = Number(opts.dryRunRows);
   for (const file of files) {
-    if (files.length > 1) out.info(kleur8.bold(`
+    if (files.length > 1) out.info(kleur9.bold(`
 ${file}`));
     const report = await buildDryRunReport(file, {
       nameColumn: opts.nameColumn,
@@ -2741,13 +3029,17 @@ function registerSubmitCommand(program, deps2) {
     "--ignore-author",
     "Accept a unique canonical name match whose author couldn't be confirmed instead of sending it to review (a CONFLICTING author still reviews)",
     false
-  ).option("--keep-infraspecific", "Deprecated \u2014 now the default; has no effect", false).option("--allow-llm", "Allow the Layer 7 LLM to break ties between competing matches", false).option("--llm-cap-cents <cents>", "Max LLM spend in cents", "500").option(
+  ).option("--keep-infraspecific", "Deprecated \u2014 now the default; has no effect", false).option("--allow-llm", "Allow the Layer 7 LLM to break ties between competing matches", false).option("--llm-cap-cents <cents>", "Max LLM spend in cents", "500").option("--backbone <name>", "Backbone to match against: wcvp or wfo", "wcvp").option(
     "--referential <version>",
-    "WCVP snapshot version to match against (default: your team's default snapshot, else the newest import)"
+    "Backbone version to match against (default: the one `planttaxomatcher versions` marks as default)"
+  ).option(
+    "--area <code>",
+    "WGSRPD level-3 area (botanical country, e.g. FRA): an ambiguous match is narrowed to the taxa native there. See `planttaxomatcher areas`"
   ).option("--no-watch", "Return as soon as the jobs are created").option("--dry-run", "Preview the first rows locally, then confirm before uploading", false).option("--dry-run-rows <n>", "Rows to show in the dry-run preview", "10").option("-y, --yes", "Skip the --dry-run confirmation (needed without a terminal)", false).option("--json", "Print the created jobs as a JSON array (with --watch: once they end)", false).action(async (patterns, opts) => {
     const out = createOutput(deps2.stdout, deps2.stderr, opts.json, deps2.now);
     const config = buildJobConfig(opts);
     const creds = await requireCredentials(deps2.store, deps2.env);
+    await checkAgainstServer(deps2, creds, config);
     const files = await expandInputs(patterns);
     if (opts.name && files.length > 1)
       out.warn("--name ignored for a multi-file submit; each job is named after its file");
@@ -2757,11 +3049,11 @@ function registerSubmitCommand(program, deps2) {
       );
     }
     if (files.length > 1) {
-      out.info(`${kleur8.cyan("\u2192")} ${files.length} files matched:`);
-      for (const file of files) out.info(kleur8.gray(`    ${file}`));
+      out.info(`${kleur9.cyan("\u2192")} ${files.length} files matched:`);
+      for (const file of files) out.info(kleur9.gray(`    ${file}`));
     }
     if (opts.dryRun && !await confirmDryRun(deps2, out, files, opts)) {
-      out.info(kleur8.gray("Aborted."));
+      out.info(kleur9.gray("Aborted."));
       return;
     }
     const submitted = [];
@@ -2769,16 +3061,16 @@ function registerSubmitCommand(program, deps2) {
     try {
       for (const file of files) {
         const name = jobNameFor(file, files.length, opts.name);
-        out.info(`${kleur8.cyan("\u2192")} Uploading ${file} \u2026`);
+        out.info(`${kleur9.cyan("\u2192")} Uploading ${file} \u2026`);
         const job = await deps2.api.submitJob(creds, file, config, name || null);
-        out.success(`Job created: ${job.id}  ${kleur8.gray(name)}`);
+        out.success(`Job created: ${job.id}  ${kleur9.gray(name)}`);
         out.info(`  rows=${job.totalRows}  uniqueQueries=${job.uniqueQueries}`);
         submitted.push({ file, job });
       }
       if (opts.watch) {
         const watchOut = opts.json ? createOutput(deps2.stderr, deps2.stderr, false, deps2.now) : out;
         for (const { file, job } of submitted) {
-          if (submitted.length > 1) watchOut.info(kleur8.bold(`
+          if (submitted.length > 1) watchOut.info(kleur9.bold(`
 [${file}] ${job.id}`));
           finals.push({ id: job.id, status: await watchJob(deps2.api, watchOut, creds, job.id) });
         }
@@ -2813,6 +3105,7 @@ function buildProgram(deps2, version2) {
   registerAuthCommands(program, deps2);
   registerJobCommands(program, deps2);
   registerSubmitCommand(program, deps2);
+  registerCatalogCommands(program, deps2);
   registerDownloadCommand(program, deps2);
   registerSkillsCommands(program, deps2, version2);
   return program;
@@ -2823,9 +3116,9 @@ async function runCli(argv, deps2, version2) {
     return 0;
   } catch (err) {
     const { exitCode, message, hint } = describeError(err);
-    if (message) deps2.stderr.write(`${kleur9.red("error:")} ${message}
+    if (message) deps2.stderr.write(`${kleur10.red("error:")} ${message}
 `);
-    if (hint) deps2.stderr.write(`${kleur9.gray(hint)}
+    if (hint) deps2.stderr.write(`${kleur10.gray(hint)}
 `);
     return exitCode;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plantnet/planttaxomatcher",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "PlantTaxoMatcher CLI — reconcile plant names against WCVP via the PlantTaxoMatcher API.",
     "type": "module",
     "engines": {

package/skills/planttaxomatcher/SKILL.md

@@ -62,9 +62,21 @@ row of an XLSX sheet) and choose the columns:
 - `--family-column`, `--genus-column`, `--rank-column` when present: they help break ties.
 - `--id-column` when rows already carry an identifier, with `--id-type wcvp` or `--id-type gbif` if you know which.
 
+Then the reference to match against:
+
+- **Backbone**: WCVP by default. Pass `--backbone wfo` only when the user asks for World Flora Online.
+- **Version**: leave `--referential` out to use the server's default.
+  `planttaxomatcher versions --json` lists the versions; the one with
+  `"isDefault": true` is used when none is named. Pass `--referential <version>`
+  only when the user names one, or needs a team-edited version.
+- **Area**: when the user says where the plants grow (a country, a regional
+  flora), pass `--area <code>` so an ambiguous name is narrowed to the taxa
+  native there. Find the WGSRPD level-3 code with
+  `planttaxomatcher areas --search <country> --json`, e.g. `FRA` for France.
+
 Ask the user when the name column is not obvious. Keep the defaults for
 everything else unless the user asks; `references/submit-options.md` lists
-every option (author handling, species-level roll-up, snapshot, row filter, LLM).
+every option (author handling, species-level roll-up, row filter, LLM).
 
 ## 3. Submit
 
@@ -93,11 +105,29 @@ planttaxomatcher download <jobId> --format csv --output results.csv --json
 ```
 
 The export keeps every column of the user's file and adds `planttaxomatcher_*`
-and `wcvp_*` columns; `references/results.md` explains them, the grades and the
-review states. Useful options: `--confirmed-only`, `--dedupe`,
-`--wcvp-extra ipni_id,powo_id`, `--format xlsx`, and `--bundle` for a ZIP with
-a NOTICE.md that cites the WCVP snapshot. `--list-columns --json` shows every
-available column.
+and `wcvp_*` columns. The cleaned name to hand back is
+**`wcvp_accepted_name_with_author`**: the accepted name with its author, ready
+to cite (e.g. *Calicotome spinosa (L.) Link*), filled even when the input was a
+synonym. `wcvp_accepted_name` is the same without the author, and
+`wcvp_matched_name` is what the input matched before synonyms were resolved.
+
+The filters of the web app's download dialog. Check what each keeps first
+with `planttaxomatcher download <jobId> --counts --json`:
+
+- `--confirmed-only`: only rows accepted automatically (grade A) or by a reviewer.
+- `--resolved-only`: drop the rows with no accepted name (no match, error, rejected).
+- `--dedupe`: one row per accepted taxon (synonyms and duplicates collapse).
+- `--taxon-level species_below` (drop genus and family matches) or `--taxon-level species_only`.
+
+To shape the file:
+
+- `--columns` keeps only the listed columns. Start with the user's own name column (the one passed to `--name-column`), e.g. `--columns <name column>,wcvp_accepted_name_with_author,planttaxomatcher_grade,planttaxomatcher_review_status`.
+- `--wcvp-extra ipni_id,powo_id` appends WCVP fields as `wcvp_<field>` columns.
+- `--format xlsx`, or `--bundle` for a ZIP with a NOTICE.md that cites the backbone version.
+
+`planttaxomatcher download <jobId> --list-columns --json` lists every column
+with what it holds; `references/results.md` describes them all, with the grades
+and review states.
 
 ## 6. Report back
 
@@ -105,7 +135,9 @@ Summarise from the status counts and the export:
 
 - rows matched and accepted automatically (grade A),
 - rows waiting for review (grade B or C, ambiguous),
-- rows with no match or an error, with a few examples.
+- rows with no match or an error, with a few examples,
+
+quoting names as input → `wcvp_accepted_name_with_author`.
 
 Give the job's `url`: reviewing happens in the web app, not the CLI. Call a
 name accepted only when `planttaxomatcher_review_status` is `not_required`,
@@ -114,4 +146,5 @@ name accepted only when `planttaxomatcher_review_status` is `not_required`,
 ## Other commands
 
 - `planttaxomatcher list --json`: recent jobs (`--status completed`, `--limit 50`).
+- `planttaxomatcher versions --json` and `planttaxomatcher areas --json`: what `--referential` and `--area` accept.
 - `planttaxomatcher pause <jobId>`, `planttaxomatcher resume <jobId>`, `planttaxomatcher cancel <jobId>`: control a running job; each takes `--json`. Cancelling keeps the rows already matched. Ask before cancelling.

package/skills/planttaxomatcher/references/results.md

@@ -2,37 +2,20 @@
 
 Every row of the user's file comes back with its original columns, plus the
 columns below. `planttaxomatcher download <jobId> --list-columns --json` lists
-them all for a given job.
-
-## Match columns
-
-| Column                              | Meaning                                                                                                                                                          |
-| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `planttaxomatcher_match_status`     | `matched`, `ambiguous` (several candidates), `no_match`, `error`, `skipped` (filtered out by `--filter-column`, or no usable name)                               |
-| `planttaxomatcher_grade`            | `A`, `B` or `C` (see below); empty without a match                                                                                                               |
-| `planttaxomatcher_review_status`    | `not_required`, `pending`, `accepted`, `rejected`, `overridden` (see below)                                                                                      |
-| `planttaxomatcher_evidence_type`    | How the match was found: `local_exact`, `local_canonical_unique`, `local_fuzzy`, `external_validated`, `external_fuzzy`, `team_history`, `cross_backbone`, `llm` |
-| `planttaxomatcher_confidence`       | Score between 0 and 1                                                                                                                                            |
-| `planttaxomatcher_flags`            | Why a match needs a look, e.g. `author-unconfirmed`, `author-mismatch`                                                                                           |
-| `planttaxomatcher_reason`           | One-line explanation of the decision                                                                                                                             |
-| `planttaxomatcher_alternatives`     | Other candidates, for ambiguous rows                                                                                                                             |
-| `planttaxomatcher_input_normalized` | The name as matched, after cleaning                                                                                                                              |
-| `planttaxomatcher_input_qualifier`  | A qualifier found in the input (`cf`, `aff`, `sp`, `aggregate`…)                                                                                                 |
-
-## WCVP columns
-
-| Column                                                                         | Meaning                                            |
-| ------------------------------------------------------------------------------ | -------------------------------------------------- |
-| `wcvp_matched_name`                                                            | The WCVP name the input matched (may be a synonym) |
-| `wcvp_matched_taxonomic_status`                                                | Its status in WCVP: `Accepted`, `Synonym`, …       |
-| `wcvp_accepted_name`, `wcvp_accepted_author`, `wcvp_accepted_name_with_author` | The accepted name the match resolves to            |
-| `wcvp_accepted_taxon_id`                                                       | WCVP id of the accepted taxon                      |
-| `wcvp_family`, `wcvp_rank`                                                     | Family and rank of the accepted taxon              |
-| `ipni_lsid`, `powo_url`                                                        | Links to IPNI and Plants of the World Online       |
-
-`--wcvp-extra` appends more WCVP fields as `wcvp_<key>`, for example
-`ipni_id`, `powo_id`, `geographic_area`, `lifeform_description`,
-`first_published`.
+them for a given job (the Pl@ntNet columns only exist when the server has
+Pl@ntNet enabled).
+
+## The columns that matter most
+
+- `wcvp_accepted_name_with_author`: the cleaned name to hand back, the accepted
+  name with its author (e.g. *Calicotome spinosa (L.) Link*), even when the
+  input was a synonym.
+- `planttaxomatcher_grade` and `planttaxomatcher_review_status`: how far to
+  trust it (below).
+- `planttaxomatcher_flags` and `planttaxomatcher_reason`: why a row needs a look.
+- `wcvp_accepted_taxon_id`, `ipni_lsid`, `powo_url`: identifiers and links for
+  the accepted taxon (WCVP jobs; a WFO job's id is in
+  `planttaxomatcher_accepted_identifier`).
 
 ## Grades
 
@@ -53,3 +36,5 @@ them all for a given job.
 
 Only `not_required`, `accepted` and `overridden` rows carry a name the user
 can rely on. `--confirmed-only` exports just those.
+
+{{exportColumns}}

package/skills/planttaxomatcher/references/submit-options.md

@@ -16,6 +16,16 @@ something else; they are what the web app uses.
 | `--id-type <type>`                                    | What `--id-column` holds: `auto` (default), `wcvp`, `gbif`                                                                       |
 | `--filter-column <name>` and `--filter-value <value>` | Only match rows whose column equals the value (trimmed, case-insensitive), e.g. `--filter-column kingdom --filter-value Plantae` |
 
+## Backbone, version and area
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `--backbone <name>` | `wcvp` | `wcvp` (World Checklist of Vascular Plants) or `wfo` (World Flora Online) |
+| `--referential <version>` | the server's default | Backbone version, e.g. `wcvp-v14`. `planttaxomatcher versions --json` lists them and marks the default (`isDefault`); a team-edited version is listed with `kind: derived` |
+| `--area <code>` | none | WGSRPD level-3 area (botanical country), e.g. `FRA`: an ambiguous name is narrowed to the taxa native there. `planttaxomatcher areas --search <text> --json` finds the code |
+
+The CLI checks `--referential` and `--area` against the server before uploading, and names the valid values on a typo.
+
 ## Matching
 
 | Option                    | Default       | Effect                                                                                                                                     |
@@ -23,7 +33,6 @@ something else; they are what the web app uses.
 | `--author-mode <mode>`    | `prefer`      | `ignore`, `prefer` or `strict` handling of authorship                                                                                      |
 | `--ignore-author`         | off           | Accept a unique name match whose author could not be confirmed, instead of sending it to review. A conflicting author still goes to review |
 | `--species-level`         | off           | Roll varieties, subspecies and forms up to their accepted species                                                                          |
-| `--referential <version>` | team default  | WCVP snapshot to match against, e.g. `wcvp-v14`                                                                                            |
 | `--allow-llm`             | off           | Let a language model break ties between competing matches                                                                                  |
 | `--llm-cap-cents <cents>` | `500`         | Spending cap for `--allow-llm`                                                                                                             |
 | `--review-mode <mode>`    | `recommended` | `off`, `recommended` or `strict`                                                                                                           |