@plantnet/planttaxomatcher 0.2.0 → 0.4.0

package/dist/index.js

@@ -2,11 +2,18 @@
 
 // src/index.ts
 import { createRequire } from "module";
-import { promises as fs4 } from "fs";
-import { parse as parsePath } from "path";
-import { confirm, password } from "@inquirer/prompts";
-import { Command } from "commander";
-import kleur2 from "kleur";
+
+// src/deps.ts
+import { spawn } from "child_process";
+import { homedir as homedir2, hostname } from "os";
+import { fileURLToPath } from "url";
+import { setTimeout as sleep } from "timers/promises";
+import { checkbox, confirm } from "@inquirer/prompts";
+
+// src/api-client.ts
+import { openAsBlob } from "fs";
+import { basename } from "path";
+import { FormData, fetch } from "undici";
 
 // ../shared/src/schemas/identifiers.ts
 import { z } from "zod";
@@ -146,9 +153,11 @@ var jobStatusSchema = z4.enum([
 ]);
 var authorModeSchema = z4.enum(["ignore", "prefer", "strict"]);
 var reviewModeSchema = z4.enum(["off", "recommended", "strict"]);
+var idTypeOptionSchema = z4.enum(["auto", "wcvp", "gbif"]);
 var jobConfigSchema = z4.object({
   nameColumn: z4.string().min(1),
   idColumn: z4.string().nullable().optional(),
+  idType: idTypeOptionSchema.default("auto").optional(),
   familyColumn: z4.string().nullable().optional(),
   genusColumn: z4.string().nullable().optional(),
   rankColumn: z4.string().nullable().optional(),
@@ -183,7 +192,8 @@ var jobConfigSchema = z4.object({
   /**
    * "The author isn't important." When the canonical name matches exactly one
    * taxon but the input's author could not be CONFIRMED (flag
-   * `author-unconfirmed`), auto-accept the match instead of sending it to
+   * `author-unconfirmed`, or `author-uncomparable` when it can't be compared
+   * at all), auto-accept the match instead of sending it to
    * review. The taxon itself was never in doubt in that case — only whether
    * the author string cites it the way WCVP does — so a dataset whose author
    * column is unreliable (or absent from the source) can skip that queue.
@@ -241,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(),
@@ -296,15 +308,56 @@ var jobPublicAccessUpdateSchema = z4.object({
 var jobRenameSchema = z4.object({
   name: z4.string().trim().min(1).max(200)
 });
-var progressEventSchema = z4.object({
-  type: z4.enum(["progress", "status", "error", "completed"]),
-  jobId: z4.string().ulid(),
-  timestamp: z4.string().datetime(),
-  processedRows: z4.number().int().nonnegative().optional(),
-  totalRows: z4.number().int().nonnegative().optional(),
-  status: jobStatusSchema.optional(),
-  message: z4.string().optional()
-});
+var jobStreamPhaseSchema = z4.enum(["loading", "parsing", "matching"]);
+var nonNegativeInt = z4.number().int().nonnegative();
+var throttledProviderSchema = z4.object({
+  /** Provider id: `gbif`, `tnrs`, `gnverifier`, `plantnet`, `openrouter`. */
+  provider: z4.string(),
+  /** Calls waiting for that provider's limiter right now. */
+  waiting: nonNegativeInt,
+  /** How long the job has been waiting on it without a break. */
+  waitedMs: nonNegativeInt
+});
+var frameBase = { jobId: z4.string().optional(), timestamp: z4.string().optional() };
+var jobStreamEventSchema = z4.discriminatedUnion("type", [
+  /** A status change, or the snapshot a stream opens with. */
+  z4.object({
+    ...frameBase,
+    type: z4.literal("status"),
+    status: jobStatusSchema,
+    phase: jobStreamPhaseSchema.optional(),
+    snapshot: z4.string().optional(),
+    processedRows: nonNegativeInt.optional(),
+    totalRows: nonNegativeInt.optional(),
+    processedQueries: nonNegativeInt.optional(),
+    totalQueries: nonNegativeInt.optional()
+  }),
+  /** Live counters for the whole job, a few times a second at most. */
+  z4.object({
+    ...frameBase,
+    type: z4.literal("progress"),
+    phase: jobStreamPhaseSchema,
+    processedQueries: nonNegativeInt,
+    totalQueries: nonNegativeInt,
+    matched: nonNegativeInt,
+    ambiguous: nonNegativeInt,
+    errors: nonNegativeInt,
+    review: nonNegativeInt,
+    processed: nonNegativeInt
+  }),
+  /**
+   * External providers are holding the match stage back: their rate
+   * limiter, a retry backoff after a 429 / 5xx, or the in-flight cap. Repeated while it
+   * lasts and simply not sent once it stops, so a reader should let the
+   * state lapse a few seconds after the last one.
+   */
+  z4.object({ ...frameBase, type: z4.literal("throttle"), providers: z4.array(throttledProviderSchema).min(1) }),
+  /** Progress of a post-match verification plugin run. */
+  z4.object({ ...frameBase, type: z4.literal("plugin"), pluginId: z4.string() }).passthrough(),
+  z4.object({ ...frameBase, type: z4.literal("completed"), status: z4.enum(["completed", "cancelled"]) }),
+  z4.object({ ...frameBase, type: z4.literal("error"), message: z4.string() }),
+  z4.object({ ...frameBase, type: z4.literal("heartbeat") })
+]);
 var taxonIdentifierRefSchema = z4.object({
   namespace: z4.string(),
   value: z4.string()
@@ -356,6 +409,16 @@ var statusCountsSchema = z4.object({
   pending: z4.number().int().nonnegative()
 });
 var layerCountsSchema = z4.record(z4.string(), z4.number().int().nonnegative());
+var rowSortSchema = z4.enum([
+  "rowIndex",
+  "inputName",
+  "matchStatus",
+  "grade",
+  "confidence",
+  "acceptedName",
+  "family"
+]);
+var rowOrderSchema = z4.enum(["asc", "desc"]);
 var jobRowsPageSchema = z4.object({
   rows: z4.array(jobRowSummarySchema),
   /** Row count matching the CURRENT filter (not the whole job) — drives
@@ -363,6 +426,9 @@ var jobRowsPageSchema = z4.object({
   total: z4.number().int().nonnegative(),
   offset: z4.number().int().nonnegative(),
   limit: z4.number().int().positive(),
+  /** Opaque keyset cursor for the page after this one, in the requested sort
+   * + order; null on the last page. Pass it back as `cursor`. */
+  nextCursor: z4.string().nullable(),
   /** Per-grade row counts for the whole job, independent of the current
    * filter. Used by the SPA to show "B (12)" next to each grade chip. */
   gradeCounts: gradeCountsSchema,
@@ -578,7 +644,7 @@ var reviewChatStreamEventSchema = z4.discriminatedUnion("type", [
   /** Terminal failure — a human-readable reason. */
   z4.object({ type: z4.literal("error"), error: z4.string() })
 ]);
-var replayableLayerSchema = z4.enum(["L1", "L2", "L3", "L4", "L5", "L6", "L7"]);
+var replayableLayerSchema = z4.enum(["L1", "L1.5", "L2", "L3", "L4", "L5", "L6", "L7"]);
 var replayLayerBodySchema = z4.object({ layer: replayableLayerSchema });
 var replayCandidateSchema = z4.object({
   scientificName: z4.string(),
@@ -626,9 +692,50 @@ var replayLayerResultSchema = z4.object({
   attempts: z4.array(replayAttemptSchema)
 });
 
-// ../shared/src/schemas/auth.ts
+// ../shared/src/schemas/live-match.ts
 import { z as z5 } from "zod";
-var tokenScopeSchema = z5.enum([
+var liveMatchBodySchema = z5.object({
+  name: z5.string().trim().min(3).max(300),
+  referential: z5.enum(["wcvp", "wfo"]).default("wcvp"),
+  referentialVersion: z5.string().min(1),
+  /** WGSRPD Level-3 area code narrowing an ambiguous outcome (null = off). */
+  area: z5.string().nullable().optional(),
+  speciesLevelAcceptedOnly: z5.boolean().default(false),
+  acceptUnconfirmedAuthor: z5.boolean().default(false)
+});
+var liveMatchCandidateSchema = matchCandidateSummarySchema.omit({ id: true, attemptId: true });
+var liveMatchAttemptSchema = z5.object({
+  layer: z5.string(),
+  provider: z5.string(),
+  status: z5.string(),
+  durationMs: z5.number().int().nonnegative(),
+  query: z5.unknown(),
+  rawResponseSummary: z5.unknown().nullable()
+});
+var liveMatchResultSchema = z5.object({
+  query: z5.object({
+    input: z5.string(),
+    canonical: z5.string(),
+    authorship: z5.string().nullable(),
+    parser: z5.enum(["gnparser", "fallback"])
+  }),
+  matchStatus: matchStatusSchema,
+  evidenceType: evidenceTypeSchema.nullable(),
+  grade: gradeSchema.nullable(),
+  confidence: z5.number().nullable(),
+  /** Layer that settled the outcome (null for no_match). */
+  decidedBy: z5.string().nullable(),
+  flags: z5.array(z5.string()),
+  /** Index into `candidates` of the pick a job would have selected. */
+  selectedIndex: z5.number().int().nonnegative().nullable(),
+  candidates: z5.array(liveMatchCandidateSchema),
+  attempts: z5.array(liveMatchAttemptSchema),
+  durationMs: z5.number().int().nonnegative()
+});
+
+// ../shared/src/schemas/auth.ts
+import { z as z6 } from "zod";
+var tokenScopeSchema = z6.enum([
   "submit:job",
   "read:job",
   "cancel:job",
@@ -640,83 +747,87 @@ var tokenScopeSchema = z5.enum([
   "admin:teams"
 ]);
 var ALL_TOKEN_SCOPES = tokenScopeSchema.options;
-var tokenStringSchema = z5.string().regex(/^ptm_[a-zA-Z0-9]{12}_[a-zA-Z0-9]{32}$/, "Malformed token");
-var meSchema = z5.object({
-  userId: z5.string().uuid(),
-  teamId: z5.string().uuid(),
-  displayName: z5.string(),
-  scopes: z5.array(tokenScopeSchema),
-  tokenLabel: z5.string().nullable(),
+var tokenStringSchema = z6.string().regex(/^ptm_[a-zA-Z0-9]{12}_[a-zA-Z0-9]{32}$/, "Malformed token");
+var meSchema = z6.object({
+  userId: z6.string().uuid(),
+  teamId: z6.string().uuid(),
+  displayName: z6.string(),
+  scopes: z6.array(tokenScopeSchema),
+  tokenLabel: z6.string().nullable(),
   /** DB id of the token that authenticated this request — matches a row's
    * `id` in the admin token list, so the UI can highlight "this is you". */
-  tokenId: z5.string().uuid().nullable()
-});
-var tokenCreateBodySchema = z5.object({
-  label: z5.string().min(1).max(120),
-  scopes: z5.array(tokenScopeSchema).min(1),
-  expiresAt: z5.string().datetime().optional()
-});
-var tokenRenameSchema = z5.object({
-  label: z5.string().trim().min(1).max(120)
-});
-var tokenSummarySchema = z5.object({
-  id: z5.string().uuid(),
-  tokenIdPrefix: z5.string(),
-  label: z5.string(),
-  displayName: z5.string(),
-  scopes: z5.array(tokenScopeSchema),
-  createdAt: z5.string().datetime(),
-  lastUsedAt: z5.string().datetime().nullable(),
-  expiresAt: z5.string().datetime().nullable()
+  tokenId: z6.string().uuid().nullable(),
+  /** Where this deployment's web app lives, for links to a job page. Absent from older servers. */
+  appUrl: z6.string().optional()
+});
+var tokenCreateBodySchema = z6.object({
+  label: z6.string().min(1).max(120),
+  scopes: z6.array(tokenScopeSchema).min(1),
+  expiresAt: z6.string().datetime().optional()
+});
+var tokenRenameSchema = z6.object({
+  label: z6.string().trim().min(1).max(120)
+});
+var tokenSummarySchema = z6.object({
+  id: z6.string().uuid(),
+  /** Team the token belongs to — `admin:teams` callers list every team's tokens. */
+  teamId: z6.string().uuid(),
+  tokenIdPrefix: z6.string(),
+  label: z6.string(),
+  displayName: z6.string(),
+  scopes: z6.array(tokenScopeSchema),
+  createdAt: z6.string().datetime(),
+  lastUsedAt: z6.string().datetime().nullable(),
+  expiresAt: z6.string().datetime().nullable()
 });
 var tokenCreatedSchema = tokenSummarySchema.extend({
   tokenString: tokenStringSchema
 });
-var teamSummarySchema = z5.object({
-  id: z5.string().uuid(),
-  name: z5.string(),
-  createdAt: z5.string().datetime()
-});
-var teamCreateBodySchema = z5.object({
-  name: z5.string().min(1).max(120),
-  initialUserDisplayName: z5.string().min(1).max(120).default("Admin"),
-  initialToken: z5.object({
-    label: z5.string().min(1).max(120),
-    scopes: z5.array(tokenScopeSchema).min(1)
+var teamSummarySchema = z6.object({
+  id: z6.string().uuid(),
+  name: z6.string(),
+  createdAt: z6.string().datetime()
+});
+var teamCreateBodySchema = z6.object({
+  name: z6.string().min(1).max(120),
+  initialUserDisplayName: z6.string().min(1).max(120).default("Admin"),
+  initialToken: z6.object({
+    label: z6.string().min(1).max(120),
+    scopes: z6.array(tokenScopeSchema).min(1)
   }).optional()
 });
 var teamCreatedSchema = teamSummarySchema.extend({
-  initialUser: z5.object({
-    id: z5.string().uuid(),
-    displayName: z5.string()
+  initialUser: z6.object({
+    id: z6.string().uuid(),
+    displayName: z6.string()
   }),
   initialToken: tokenCreatedSchema.nullable()
 });
-var setupStatusSchema = z5.object({
-  needsSetup: z5.boolean()
+var setupStatusSchema = z6.object({
+  needsSetup: z6.boolean()
 });
-var setupBodySchema = z5.object({
-  teamName: z5.string().min(1).max(120),
-  displayName: z5.string().min(1).max(120).default("Admin")
+var setupBodySchema = z6.object({
+  teamName: z6.string().min(1).max(120),
+  displayName: z6.string().min(1).max(120).default("Admin")
 });
-var setupResultSchema = z5.object({
+var setupResultSchema = z6.object({
   team: teamSummarySchema,
-  user: z5.object({ id: z5.string().uuid(), displayName: z5.string() }),
+  user: z6.object({ id: z6.string().uuid(), displayName: z6.string() }),
   tokenString: tokenStringSchema,
-  scopes: z5.array(tokenScopeSchema)
+  scopes: z6.array(tokenScopeSchema)
 });
-var teamLlmSettingsSchema = z5.object({
-  keyConfigured: z5.boolean(),
-  keyHint: z5.string().nullable(),
-  lightModel: z5.string(),
-  heavyModel: z5.string()
+var teamLlmSettingsSchema = z6.object({
+  keyConfigured: z6.boolean(),
+  keyHint: z6.string().nullable(),
+  lightModel: z6.string(),
+  heavyModel: z6.string()
 });
-var teamLlmUpdateSchema = z5.object({
-  openrouterApiKey: z5.string().max(400).nullable().optional(),
-  lightModel: z5.string().min(1).max(200).optional(),
-  heavyModel: z5.string().min(1).max(200).optional()
+var teamLlmUpdateSchema = z6.object({
+  openrouterApiKey: z6.string().max(400).nullable().optional(),
+  lightModel: z6.string().min(1).max(200).optional(),
+  heavyModel: z6.string().min(1).max(200).optional()
 });
-var wcvpImportStatusSchema = z5.enum([
+var wcvpImportStatusSchema = z6.enum([
   "queued",
   "downloading",
   "importing",
@@ -724,68 +835,73 @@ var wcvpImportStatusSchema = z5.enum([
   "failed",
   "cancelled"
 ]);
-var wcvpImportRunSchema = z5.object({
-  id: z5.string().uuid(),
-  version: z5.string(),
-  sourceUrl: z5.string(),
+var wcvpImportRunSchema = z6.object({
+  id: z6.string().uuid(),
+  version: z6.string(),
+  sourceUrl: z6.string(),
   status: wcvpImportStatusSchema,
-  forceOverwrite: z5.boolean(),
-  bytesDownloaded: z5.number().int().nonnegative(),
-  totalBytes: z5.number().int().nonnegative().nullable(),
-  insertedCount: z5.number().int().nonnegative(),
-  recordCount: z5.number().int().nonnegative().nullable(),
-  message: z5.string().nullable(),
-  createdAt: z5.string().datetime(),
-  startedAt: z5.string().datetime().nullable(),
-  completedAt: z5.string().datetime().nullable()
-});
-var wcvpImportCreateBodySchema = z5.object({
-  version: z5.string().min(1).max(120),
+  forceOverwrite: z6.boolean(),
+  bytesDownloaded: z6.number().int().nonnegative(),
+  totalBytes: z6.number().int().nonnegative().nullable(),
+  insertedCount: z6.number().int().nonnegative(),
+  recordCount: z6.number().int().nonnegative().nullable(),
+  message: z6.string().nullable(),
+  createdAt: z6.string().datetime(),
+  startedAt: z6.string().datetime().nullable(),
+  completedAt: z6.string().datetime().nullable()
+});
+var wcvpImportCreateBodySchema = z6.object({
+  version: z6.string().min(1).max(120),
   /** Defaults to the Kew SFTP URL when omitted, so the admin doesn't have
    * to remember it for routine v13/v14 imports. */
-  url: z5.string().url().optional(),
-  force: z5.boolean().optional()
-});
-var adminHealthErrorSchema = z5.object({
-  id: z5.string().uuid(),
-  action: z5.string(),
-  entityType: z5.string(),
-  entityId: z5.string().nullable(),
-  timestamp: z5.string().datetime(),
-  metadata: z5.unknown().nullable()
-});
-var adminHealthSchema = z5.object({
-  queueDepth: z5.object({
-    waiting: z5.number().int().nonnegative(),
-    active: z5.number().int().nonnegative(),
-    delayed: z5.number().int().nonnegative(),
-    completed: z5.number().int().nonnegative(),
-    failed: z5.number().int().nonnegative(),
-    paused: z5.number().int().nonnegative()
-  }),
-  workerCount: z5.number().int().nonnegative(),
-  lastErrors: z5.array(adminHealthErrorSchema),
-  rateLimitBudget: z5.object({
-    max: z5.number().int().nonnegative(),
-    timeWindowSeconds: z5.number().int().nonnegative()
+  url: z6.string().url().optional(),
+  force: z6.boolean().optional()
+});
+var adminHealthErrorSchema = z6.object({
+  id: z6.string().uuid(),
+  action: z6.string(),
+  entityType: z6.string(),
+  entityId: z6.string().nullable(),
+  timestamp: z6.string().datetime(),
+  metadata: z6.unknown().nullable()
+});
+var queueDepthSchema = z6.object({
+  waiting: z6.number().int().nonnegative(),
+  active: z6.number().int().nonnegative(),
+  delayed: z6.number().int().nonnegative(),
+  completed: z6.number().int().nonnegative(),
+  failed: z6.number().int().nonnegative(),
+  paused: z6.number().int().nonnegative()
+});
+var adminQueueSchema = z6.object({
+  queueDepth: queueDepthSchema,
+  workerCount: z6.number().int().nonnegative()
+});
+var adminHealthSchema = z6.object({
+  queueDepth: queueDepthSchema,
+  workerCount: z6.number().int().nonnegative(),
+  lastErrors: z6.array(adminHealthErrorSchema),
+  rateLimitBudget: z6.object({
+    max: z6.number().int().nonnegative(),
+    timeWindowSeconds: z6.number().int().nonnegative()
   }),
-  snapshotVersion: z5.string().nullable(),
-  snapshotImportedAt: z5.string().datetime().nullable(),
+  snapshotVersion: z6.string().nullable(),
+  snapshotImportedAt: z6.string().datetime().nullable(),
   /**
    * Number of cached accepted-name mappings (L0.5 match-history rows) for the
    * caller's team — the size of the team accepted-name cache.
    */
-  teamHistorySize: z5.number().int().nonnegative(),
+  teamHistorySize: z6.number().int().nonnegative(),
   /**
    * Overall (all-teams) tally of which cascade layer produced the winning
    * candidate, across every matched query. `layer` is the raw attempt layer
    * (`L1`…`L7`, `L0.5`, `OVERRIDE`); `count` is the number of matched queries
    * that layer resolved. Descending by count.
    */
-  layerUsage: z5.array(
-    z5.object({
-      layer: z5.string(),
-      count: z5.number().int().nonnegative()
+  layerUsage: z6.array(
+    z6.object({
+      layer: z6.string(),
+      count: z6.number().int().nonnegative()
     })
   ),
   /**
@@ -795,59 +911,108 @@ var adminHealthSchema = z5.object({
    * Lets the health page surface each external source's usage, hit/miss/error
    * breakdown, latency, and recency — so a misbehaving provider is visible.
    */
-  externalProviders: z5.array(
-    z5.object({
-      provider: z5.string(),
-      total: z5.number().int().nonnegative(),
-      hits: z5.number().int().nonnegative(),
-      misses: z5.number().int().nonnegative(),
-      errors: z5.number().int().nonnegative(),
-      avgDurationMs: z5.number().int().nonnegative(),
-      lastUsedAt: z5.string().datetime().nullable()
+  externalProviders: z6.array(
+    z6.object({
+      provider: z6.string(),
+      total: z6.number().int().nonnegative(),
+      hits: z6.number().int().nonnegative(),
+      misses: z6.number().int().nonnegative(),
+      errors: z6.number().int().nonnegative(),
+      avgDurationMs: z6.number().int().nonnegative(),
+      lastUsedAt: z6.string().datetime().nullable()
     })
   )
 });
-var matchHistoryEntrySchema = z5.object({
-  id: z5.string().uuid(),
+var matchHistoryEntrySchema = z6.object({
+  id: z6.string().uuid(),
   /** The normalized input name this mapping is keyed on. */
-  normalizedInput: z5.string(),
-  acceptedName: z5.string(),
-  acceptedIdentifier: z5.object({ namespace: z5.string(), value: z5.string() }).nullable(),
+  normalizedInput: z6.string(),
+  acceptedName: z6.string(),
+  acceptedIdentifier: z6.object({ namespace: z6.string(), value: z6.string() }).nullable(),
   /** Resolved from the backbone snapshot at read time (null when the stored
    * identifier no longer resolves): authorship + family of the accepted taxon,
    * its identifiers (backbone id, IPNI LSID, portal url) and the portal link. */
-  acceptedAuthorship: z5.string().nullable(),
-  family: z5.string().nullable(),
-  acceptedIdentifiers: z5.array(z5.object({ namespace: z5.string(), value: z5.string() })),
-  targetUrl: z5.string().nullable(),
-  targetReferential: z5.string(),
-  referentialVersion: z5.string(),
-  independentUserAcceptanceCount: z5.number().int().nonnegative(),
-  rejectionCount: z5.number().int().nonnegative(),
-  blacklisted: z5.boolean(),
-  needsReconfirmation: z5.boolean(),
+  acceptedAuthorship: z6.string().nullable(),
+  family: z6.string().nullable(),
+  acceptedIdentifiers: z6.array(z6.object({ namespace: z6.string(), value: z6.string() })),
+  targetUrl: z6.string().nullable(),
+  targetReferential: z6.string(),
+  referentialVersion: z6.string(),
+  independentUserAcceptanceCount: z6.number().int().nonnegative(),
+  rejectionCount: z6.number().int().nonnegative(),
+  blacklisted: z6.boolean(),
+  needsReconfirmation: z6.boolean(),
   /** Currently usable as a cache hit (not blacklisted, acceptances > rejections). */
-  active: z5.boolean(),
+  active: z6.boolean(),
   /** Auto-accept (Grade A): acceptances ≥ the team's promotion threshold. */
-  promoted: z5.boolean(),
+  promoted: z6.boolean(),
   /** Label of the token that last reviewed this mapping (falls back to the
    * reviewer's display name for rows predating token tracking). */
-  lastReviewedBy: z5.string().nullable(),
-  firstSeenAt: z5.string().datetime(),
-  lastAcceptedAt: z5.string().datetime().nullable()
+  lastReviewedBy: z6.string().nullable(),
+  firstSeenAt: z6.string().datetime(),
+  lastAcceptedAt: z6.string().datetime().nullable()
 });
-var teamCacheResponseSchema = z5.object({
+var teamCacheResponseSchema = z6.object({
   /** Distinct-user acceptances needed to promote a hit to Grade A. */
-  promotionThreshold: z5.number().int().positive(),
+  promotionThreshold: z6.number().int().positive(),
   /** Total entries in the team cache (before the limit). */
-  total: z5.number().int().nonnegative(),
-  entries: z5.array(matchHistoryEntrySchema)
+  total: z6.number().int().nonnegative(),
+  entries: z6.array(matchHistoryEntrySchema)
+});
+
+// ../shared/src/schemas/device-auth.ts
+import { z as z7 } from "zod";
+var SLOW_DOWN_STEP_SECONDS = 5;
+var deviceAuthorizationStatusSchema = z7.enum(["pending", "approved", "denied", "consumed"]);
+var deviceAuthorizationCreateSchema = z7.object({
+  /** Shown to the approver so they recognise their own machine (the CLI sends its hostname). */
+  clientName: z7.string().trim().min(1).max(100)
+});
+var deviceAuthorizationCreatedSchema = z7.object({
+  deviceCode: z7.string(),
+  userCode: z7.string(),
+  verificationUri: z7.string(),
+  verificationUriComplete: z7.string(),
+  expiresIn: z7.number().int().positive(),
+  interval: z7.number().int().positive()
+});
+var deviceAuthorizationSchema = z7.object({
+  userCode: z7.string(),
+  clientName: z7.string(),
+  clientIp: z7.string().nullable(),
+  status: deviceAuthorizationStatusSchema,
+  scopes: z7.array(tokenScopeSchema),
+  createdAt: z7.string().datetime(),
+  expiresAt: z7.string().datetime()
+});
+var deviceAuthorizationDecisionSchema = z7.object({
+  status: z7.enum(["approved", "denied"])
+});
+var deviceTokenRequestSchema = z7.object({
+  deviceCode: z7.string().min(1).max(200)
+});
+var deviceTokenSchema = z7.object({
+  token: z7.string(),
+  label: z7.string(),
+  scopes: z7.array(tokenScopeSchema),
+  expiresAt: z7.string().datetime()
+});
+var deviceTokenErrorCodeSchema = z7.enum([
+  "authorization_pending",
+  "slow_down",
+  "expired_token",
+  "access_denied"
+]);
+var deviceTokenErrorSchema = z7.object({
+  error: deviceTokenErrorCodeSchema,
+  /** Seconds to wait before the next poll, sent with `slow_down`. */
+  interval: z7.number().int().positive().optional()
 });
 
 // ../shared/src/schemas/backbone.ts
-import { z as z6 } from "zod";
-var backboneSchema = z6.enum(["wcvp", "wfo"]);
-var wfoImportStatusSchema = z6.enum([
+import { z as z8 } from "zod";
+var backboneSchema = z8.enum(["wcvp", "wfo"]);
+var wfoImportStatusSchema = z8.enum([
   "queued",
   "downloading",
   "importing",
@@ -855,72 +1020,87 @@ var wfoImportStatusSchema = z6.enum([
   "failed",
   "cancelled"
 ]);
-var wfoImportRunSchema = z6.object({
-  id: z6.string().uuid(),
-  version: z6.string(),
-  sourceUrl: z6.string(),
+var wfoImportRunSchema = z8.object({
+  id: z8.string().uuid(),
+  version: z8.string(),
+  sourceUrl: z8.string(),
   status: wfoImportStatusSchema,
-  forceOverwrite: z6.boolean(),
-  bytesDownloaded: z6.number().int().nonnegative(),
-  totalBytes: z6.number().int().nonnegative().nullable(),
-  insertedCount: z6.number().int().nonnegative(),
-  recordCount: z6.number().int().nonnegative().nullable(),
-  message: z6.string().nullable(),
-  createdAt: z6.string().datetime(),
-  startedAt: z6.string().datetime().nullable(),
-  completedAt: z6.string().datetime().nullable()
-});
-var wfoImportCreateBodySchema = z6.object({
-  version: z6.string().min(1).max(120),
+  forceOverwrite: z8.boolean(),
+  bytesDownloaded: z8.number().int().nonnegative(),
+  totalBytes: z8.number().int().nonnegative().nullable(),
+  insertedCount: z8.number().int().nonnegative(),
+  recordCount: z8.number().int().nonnegative().nullable(),
+  message: z8.string().nullable(),
+  createdAt: z8.string().datetime(),
+  startedAt: z8.string().datetime().nullable(),
+  completedAt: z8.string().datetime().nullable()
+});
+var wfoImportCreateBodySchema = z8.object({
+  version: z8.string().min(1).max(120),
   /** Direct download URL (from the Zenodo version listing). Required for WFO
    * since versions aren't derivable from the label like WCVP's Kew URLs. */
-  url: z6.string().url().optional(),
-  force: z6.boolean().optional()
-});
-var snapshotKindSchema = z6.enum(["official", "derived"]);
-var wfoSnapshotSummarySchema = z6.object({
-  version: z6.string(),
-  recordCount: z6.number().int().nonnegative(),
-  importedAt: z6.string().datetime(),
-  isLatest: z6.boolean(),
+  url: z8.string().url().optional(),
+  force: z8.boolean().optional()
+});
+var snapshotKindSchema = z8.enum(["official", "derived"]);
+var wfoSnapshotSummarySchema = z8.object({
+  version: z8.string(),
+  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: z6.string().nullable(),
-  label: z6.string().nullable(),
-  ownerTeamId: z6.string().nullable()
+  baseVersion: z8.string().nullable(),
+  label: z8.string().nullable(),
+  ownerTeamId: z8.string().nullable()
 });
-var wfoVersionSchema = z6.object({
+var wfoVersionSchema = z8.object({
   /** Release label, e.g. "2025-12". */
-  version: z6.string(),
+  version: z8.string(),
   /** Zenodo record id for this version. */
-  recordId: z6.string(),
+  recordId: z8.string(),
   /** The plant-list archive filename inside the record. */
-  fileName: z6.string(),
+  fileName: z8.string(),
   /** Direct content download URL. */
-  url: z6.string().url(),
-  sizeBytes: z6.number().int().nonnegative().nullable(),
-  publishedAt: z6.string().nullable(),
-  isLatest: z6.boolean()
-});
-var wfoVersionListSchema = z6.array(wfoVersionSchema);
-var backboneKeySchema = z6.enum(["wcvp", "wfo"]);
-var backboneDefaultsSchema = z6.object({
-  wcvp: z6.string().nullable(),
-  wfo: z6.string().nullable()
-});
-var backboneDefaultUpdateSchema = z6.object({
+  url: z8.string().url(),
+  sizeBytes: z8.number().int().nonnegative().nullable(),
+  publishedAt: z8.string().nullable(),
+  isLatest: z8.boolean()
+});
+var wfoVersionListSchema = z8.array(wfoVersionSchema);
+var wcvpVersionSchema = z8.object({
+  /** Snapshot label the import uses, e.g. "wcvp-v15". */
+  version: z8.string(),
+  /** Kew release number, e.g. 15. */
+  release: z8.number().int().positive(),
+  /** Direct download URL. */
+  url: z8.string().url(),
+  /** Size as Kew's directory index prints it, e.g. "85M". */
+  sizeLabel: z8.string().nullable(),
+  /** Last-modified timestamp from the index, "YYYY-MM-DD HH:MM". */
+  publishedAt: z8.string().nullable()
+});
+var wcvpVersionListSchema = z8.array(wcvpVersionSchema);
+var backboneKeySchema = z8.enum(["wcvp", "wfo"]);
+var backboneDefaultsSchema = z8.object({
+  wcvp: z8.string().nullable(),
+  wfo: z8.string().nullable()
+});
+var backboneDefaultUpdateSchema = z8.object({
   backbone: backboneKeySchema,
-  version: z6.string().min(1).nullable()
+  version: z8.string().min(1).nullable()
 });
 var DERIVED_SLUG_RE = /^[a-z0-9][a-z0-9-]{1,40}$/;
 var MAX_BASE_VERSION_LENGTH = 120;
 var MAX_SNAPSHOT_VERSION_LENGTH = MAX_BASE_VERSION_LENGTH + 1 + 41;
-var derivedUploadMetaSchema = z6.object({
-  baseVersion: z6.string().min(1).max(MAX_BASE_VERSION_LENGTH),
-  slug: z6.string().regex(DERIVED_SLUG_RE, "slug: lowercase letters, digits and dashes (2\u201341 chars)"),
-  label: z6.string().trim().min(1).max(120),
-  notes: z6.string().trim().max(2e3).optional()
+var derivedUploadMetaSchema = z8.object({
+  baseVersion: z8.string().min(1).max(MAX_BASE_VERSION_LENGTH),
+  slug: z8.string().regex(DERIVED_SLUG_RE, "slug: lowercase letters, digits and dashes (2\u201341 chars)"),
+  label: z8.string().trim().min(1).max(120),
+  notes: z8.string().trim().max(2e3).optional()
 });
-var derivedUploadStatusSchema = z6.enum([
+var derivedUploadStatusSchema = z8.enum([
   "staging",
   "ready",
   "invalid",
@@ -929,23 +1109,23 @@ var derivedUploadStatusSchema = z6.enum([
   "failed",
   "discarded"
 ]);
-var derivedIssueSeveritySchema = z6.enum(["error", "warning"]);
-var derivedIssueSchema = z6.object({
-  code: z6.string(),
+var derivedIssueSeveritySchema = z8.enum(["error", "warning"]);
+var derivedIssueSchema = z8.object({
+  code: z8.string(),
   severity: derivedIssueSeveritySchema,
-  count: z6.number().int().nonnegative(),
+  count: z8.number().int().nonnegative(),
   /** Free-form detail for the UI (e.g. the offending vocabulary values). */
-  detail: z6.string().nullable(),
-  samples: z6.array(
-    z6.object({
-      taxonId: z6.string().nullable(),
-      name: z6.string().nullable(),
-      detail: z6.string().nullable(),
-      line: z6.number().int().nullable()
+  detail: z8.string().nullable(),
+  samples: z8.array(
+    z8.object({
+      taxonId: z8.string().nullable(),
+      name: z8.string().nullable(),
+      detail: z8.string().nullable(),
+      line: z8.number().int().nullable()
     })
   )
 });
-var derivedDiffFieldSchema = z6.enum([
+var derivedDiffFieldSchema = z8.enum([
   "canonical_name",
   "scientific_name",
   "authorship",
@@ -956,77 +1136,77 @@ var derivedDiffFieldSchema = z6.enum([
   "family"
 ]);
 var DERIVED_DIFF_FIELDS = derivedDiffFieldSchema.options;
-var diffSampleSchema = z6.object({ taxonId: z6.string(), name: z6.string().nullable() });
+var diffSampleSchema = z8.object({ taxonId: z8.string(), name: z8.string().nullable() });
 var changedSampleSchema = diffSampleSchema.extend({
-  changes: z6.array(
-    z6.object({ field: derivedDiffFieldSchema, before: z6.string().nullable(), after: z6.string().nullable() })
+  changes: z8.array(
+    z8.object({ field: derivedDiffFieldSchema, before: z8.string().nullable(), after: z8.string().nullable() })
   )
 });
-var derivedReportSchema = z6.object({
-  rowsRead: z6.number().int().nonnegative(),
-  rowsStaged: z6.number().int().nonnegative(),
-  rowsRejected: z6.number().int().nonnegative(),
-  baseRowCount: z6.number().int().nonnegative(),
-  errors: z6.number().int().nonnegative(),
-  warnings: z6.number().int().nonnegative(),
-  issues: z6.array(derivedIssueSchema),
-  diff: z6.object({
-    added: z6.object({ count: z6.number().int().nonnegative(), samples: z6.array(diffSampleSchema) }),
-    removed: z6.object({ count: z6.number().int().nonnegative(), samples: z6.array(diffSampleSchema) }),
-    changed: z6.object({
-      count: z6.number().int().nonnegative(),
-      byField: z6.record(z6.string(), z6.number().int().nonnegative()),
-      samples: z6.array(changedSampleSchema)
+var derivedReportSchema = z8.object({
+  rowsRead: z8.number().int().nonnegative(),
+  rowsStaged: z8.number().int().nonnegative(),
+  rowsRejected: z8.number().int().nonnegative(),
+  baseRowCount: z8.number().int().nonnegative(),
+  errors: z8.number().int().nonnegative(),
+  warnings: z8.number().int().nonnegative(),
+  issues: z8.array(derivedIssueSchema),
+  diff: z8.object({
+    added: z8.object({ count: z8.number().int().nonnegative(), samples: z8.array(diffSampleSchema) }),
+    removed: z8.object({ count: z8.number().int().nonnegative(), samples: z8.array(diffSampleSchema) }),
+    changed: z8.object({
+      count: z8.number().int().nonnegative(),
+      byField: z8.record(z8.string(), z8.number().int().nonnegative()),
+      samples: z8.array(changedSampleSchema)
     }),
-    unchanged: z6.number().int().nonnegative()
+    unchanged: z8.number().int().nonnegative()
   })
 });
-var derivedUploadSchema = z6.object({
-  id: z6.string().uuid(),
+var derivedUploadSchema = z8.object({
+  id: z8.string().uuid(),
   backbone: backboneSchema,
-  baseVersion: z6.string(),
-  slug: z6.string(),
-  label: z6.string(),
-  notes: z6.string().nullable(),
+  baseVersion: z8.string(),
+  slug: z8.string(),
+  label: z8.string(),
+  notes: z8.string().nullable(),
   /** The snapshot version this upload installs as (`<base>+<slug>`). */
-  version: z6.string(),
-  originalFilename: z6.string().nullable(),
-  sha256: z6.string(),
-  sizeBytes: z6.number().int().nonnegative(),
+  version: z8.string(),
+  originalFilename: z8.string().nullable(),
+  sha256: z8.string(),
+  sizeBytes: z8.number().int().nonnegative(),
   status: derivedUploadStatusSchema,
-  rowsRead: z6.number().int().nonnegative(),
+  rowsRead: z8.number().int().nonnegative(),
   report: derivedReportSchema.nullable(),
-  message: z6.string().nullable(),
-  createdAt: z6.string().datetime(),
-  expiresAt: z6.string().datetime(),
-  importedVersion: z6.string().nullable()
+  message: z8.string().nullable(),
+  createdAt: z8.string().datetime(),
+  expiresAt: z8.string().datetime(),
+  importedVersion: z8.string().nullable()
 });
-var derivedConfirmBodySchema = z6.object({
+var derivedConfirmBodySchema = z8.object({
   /** Acknowledge warnings. Never overrides errors. */
-  force: z6.boolean().optional()
+  force: z8.boolean().optional()
 });
 
 // ../shared/src/schemas/openrouter.ts
-import { z as z7 } from "zod";
-var openRouterModelSchema = z7.object({
+import { z as z9 } from "zod";
+var openRouterModelSchema = z9.object({
   /** Full model id, e.g. `anthropic/claude-opus-4.8` or the alias
    *  `~anthropic/claude-haiku-latest`. Used verbatim as the OpenRouter model. */
-  id: z7.string(),
+  id: z9.string(),
   /** Human label from OpenRouter (falls back to the id). */
-  name: z7.string(),
+  name: z9.string(),
   /** Author slug (the part before `/`), with any leading `~` stripped. */
-  author: z7.string(),
+  author: z9.string(),
   /** Unix seconds the model was published; used to rank "latest". */
-  created: z7.number(),
+  created: z9.number(),
   /** Context window in tokens, when OpenRouter reports it. */
-  contextLength: z7.number().nullable(),
+  contextLength: z9.number().nullable(),
   /** USD price per PROMPT token (input). Null when OpenRouter doesn't report a
    * numeric price. 0 = free. */
-  promptPriceUsd: z7.number().nullable(),
+  promptPriceUsd: z9.number().nullable(),
   /** USD price per COMPLETION token (output). */
-  completionPriceUsd: z7.number().nullable(),
+  completionPriceUsd: z9.number().nullable(),
   /** An auto-updating `…-latest` pointer (e.g. `~anthropic/claude-haiku-latest`). */
-  isAlias: z7.boolean()
+  isAlias: z9.boolean()
 });
 
 // ../shared/src/normalize.ts
@@ -1155,184 +1335,1450 @@ function detectIdTypeDistribution(samples, opts) {
 }
 
 // ../shared/src/column-map.ts
-import { z as z8 } from "zod";
-var columnMappingSchema = z8.object({
-  nameColumn: z8.string().nullable(),
-  idColumn: z8.string().nullable(),
-  familyColumn: z8.string().nullable(),
-  genusColumn: z8.string().nullable(),
-  rankColumn: z8.string().nullable(),
-  authorColumn: z8.string().nullable()
-});
-var detectColumnsBodySchema = z8.object({
-  headers: z8.array(z8.string().min(1)).min(1).max(200)
-});
-var detectColumnsResponseSchema = z8.object({
+import { z as z10 } from "zod";
+var columnMappingSchema = z10.object({
+  nameColumn: z10.string().nullable(),
+  idColumn: z10.string().nullable(),
+  familyColumn: z10.string().nullable(),
+  genusColumn: z10.string().nullable(),
+  rankColumn: z10.string().nullable(),
+  authorColumn: z10.string().nullable()
+});
+var detectColumnsBodySchema = z10.object({
+  headers: z10.array(z10.string().min(1)).min(1).max(200)
+});
+var detectColumnsResponseSchema = z10.object({
   mapping: columnMappingSchema,
-  usedLlm: z8.boolean()
+  usedLlm: z10.boolean()
 });
 
-// src/api-client.ts
-import { promises as fs } from "fs";
-import { basename } from "path";
-import { FormData, fetch, request } from "undici";
-var ApiError = class extends Error {
-  constructor(message, status, body) {
+// ../shared/src/env-flag.ts
+var FALSY = /* @__PURE__ */ new Set(["false", "0", "no", "off"]);
+function parseEnvFlag(raw, fallback) {
+  if (raw === void 0 || raw.trim() === "") return fallback;
+  return !FALSY.has(raw.trim().toLowerCase());
+}
+
+// ../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 = {
+  ok: 0,
+  error: 1,
+  usage: 2,
+  auth: 3,
+  jobFailed: 4,
+  jobPaused: 5
+};
+var LOGIN_HINT = "Run `planttaxomatcher login`, or set PLANTTAXOMATCHER_TOKEN.";
+var CliError = class extends Error {
+  constructor(message, exitCode = EXIT.error, hint) {
     super(message);
+    this.exitCode = exitCode;
+    this.hint = hint;
+  }
+  exitCode;
+  hint;
+};
+var ApiError = class extends Error {
+  constructor(status, body) {
+    super(describeApiFailure(status, body));
     this.status = status;
     this.body = body;
   }
   status;
   body;
 };
-async function call(creds, path, init) {
-  const url = new URL(path, creds.server).toString();
-  const hasBody = init?.body !== void 0;
-  const res = await request(url, {
-    method: init?.method ?? "GET",
-    headers: {
-      authorization: `Bearer ${creds.token}`,
-      ...hasBody ? { "content-type": "application/json" } : {}
-    },
-    ...hasBody ? { body: JSON.stringify(init.body) } : {}
-  });
-  const text = await res.body.text();
-  const parsed = text ? safeJson(text) : null;
-  if (res.statusCode >= 400) {
-    throw new ApiError(`HTTP ${res.statusCode}`, res.statusCode, parsed ?? text);
+function describeApiFailure(status, body) {
+  const parsed = body && typeof body === "object" ? body : {};
+  const text = typeof body === "string" ? body.trim() : "";
+  const code = typeof parsed.error === "string" ? parsed.error : "";
+  const message = typeof parsed.message === "string" ? parsed.message : "";
+  if (code === "missing_scope" && Array.isArray(parsed.required)) {
+    return `HTTP ${status}: this token lacks the ${parsed.required.join(", ")} scope`;
   }
-  return parsed;
+  if (text.startsWith("<"))
+    return `HTTP ${status}: the server answered with a web page, not the API \u2014 check the server URL`;
+  const detail = message || code || text.slice(0, 200);
+  return detail ? `HTTP ${status}: ${detail}` : `HTTP ${status}`;
 }
-function safeJson(s) {
+function describeError(err) {
+  if (err instanceof CommanderError) {
+    return { exitCode: err.exitCode === 0 ? EXIT.ok : EXIT.usage, message: null };
+  }
+  if (err instanceof CliError) {
+    return { exitCode: err.exitCode, message: err.message, ...err.hint ? { hint: err.hint } : {} };
+  }
+  if (err instanceof ApiError) {
+    if (err.status === 401) return { exitCode: EXIT.auth, message: err.message, hint: LOGIN_HINT };
+    return { exitCode: EXIT.error, message: err.message };
+  }
+  return { exitCode: EXIT.error, message: err instanceof Error ? err.message : String(err) };
+}
+function unreachable(server, err) {
+  const cause = err instanceof Error && err.cause instanceof Error ? err.cause : err;
+  const code = cause?.code;
+  const reason = code ?? (cause instanceof Error ? cause.message : String(cause));
+  return new CliError(`cannot reach ${server}: ${reason}`);
+}
+
+// src/ndjson.ts
+async function* parseNdjson(chunks) {
+  const decoder = new TextDecoder("utf-8");
+  let buffered = "";
+  for await (const chunk of chunks) {
+    buffered += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+    let newline;
+    while ((newline = buffered.indexOf("\n")) >= 0) {
+      const frame = parseLine(buffered.slice(0, newline));
+      buffered = buffered.slice(newline + 1);
+      if (frame) yield frame;
+    }
+  }
+  const last = parseLine(buffered + decoder.decode());
+  if (last) yield last;
+}
+function parseLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
   try {
-    return JSON.parse(s);
+    const value = JSON.parse(trimmed);
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
   } catch {
     return null;
   }
 }
-var apiClient = {
-  me: (c) => call(c, "/v1/me"),
-  listJobs: (c) => call(c, "/v1/jobs"),
-  getJob: (c, id) => call(c, `/v1/jobs/${id}`),
-  downloadColumns: (c, id) => call(c, `/v1/jobs/${id}/download/columns`),
-  pauseJob: (c, id) => call(c, `/v1/jobs/${id}/pause`, { method: "POST" }),
-  resumeJob: (c, id) => call(c, `/v1/jobs/${id}/resume`, { method: "POST" }),
-  cancelJob: (c, id) => call(c, `/v1/jobs/${id}/cancel`, { method: "POST" }),
-  async submitJob(creds, filePath, config, name) {
-    const buf = await fs.readFile(filePath);
-    const fd = new FormData();
-    const lower = filePath.toLowerCase();
-    const mime = lower.endsWith(".json") ? "application/json" : lower.endsWith(".xlsx") || lower.endsWith(".xls") ? "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" : "text/csv";
-    fd.set("file", new Blob([buf], { type: mime }), basename(filePath));
-    fd.set("config", JSON.stringify(config));
-    if (name && name.trim()) fd.set("name", name.trim());
-    const url = new URL("/v1/jobs", creds.server).toString();
-    const res = await fetch(url, {
-      method: "POST",
-      body: fd,
-      headers: { authorization: `Bearer ${creds.token}` }
+
+// src/api-client.ts
+var MIME_BY_EXTENSION = {
+  json: "application/json",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  xls: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+};
+function uploadMimeType(filePath) {
+  const extension = filePath.toLowerCase().split(".").pop() ?? "";
+  return MIME_BY_EXTENSION[extension] ?? "text/csv";
+}
+function downloadFilename(contentDisposition, jobId, opts) {
+  const match = /filename="?([^";]+)"?/.exec(contentDisposition ?? "");
+  const suggested = match?.[1] ? basename(match[1].replaceAll("\\", "/")) : "";
+  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 = 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);
+  if (opts.wcvpExtra) params.set("wcvpExtra", opts.wcvpExtra);
+  return params;
+}
+function notAnApi(server, path) {
+  return new CliError(`${server} did not answer ${path} like a PlantTaxoMatcher API \u2014 check the server URL`);
+}
+function safeJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function createApiClient(options = {}) {
+  const dispatcher = options.dispatcher ? { dispatcher: options.dispatcher } : {};
+  async function send(target, path, init = {}) {
+    const headers = target.token ? { authorization: `Bearer ${target.token}` } : {};
+    if (typeof init.body === "string") headers["content-type"] = "application/json";
+    try {
+      return await fetch(new URL(path, target.server), {
+        method: init.method ?? "GET",
+        headers,
+        ...init.body !== void 0 ? { body: init.body } : {},
+        ...dispatcher
+      });
+    } catch (err) {
+      throw unreachable(target.server, err);
+    }
+  }
+  async function call(creds, path, init = {}) {
+    const res = await send(creds, path, {
+      ...init.method ? { method: init.method } : {},
+      ...init.json !== void 0 ? { body: JSON.stringify(init.json) } : {}
     });
     const text = await res.text();
     const parsed = text ? safeJson(text) : null;
-    if (!res.ok) throw new ApiError(`HTTP ${res.status}`, res.status, parsed ?? text);
+    if (!res.ok) throw new ApiError(res.status, parsed ?? text);
+    if (parsed === null) throw notAnApi(creds.server, path);
     return parsed;
-  },
-  async downloadJob(creds, id, opts) {
-    const params = new URLSearchParams({ format: opts.format });
-    if (opts.confirmedOnly) params.set("confirmedOnly", "true");
-    if (opts.dedupe) params.set("dedupe", "true");
-    if (opts.bundle) params.set("bundle", "true");
-    if (opts.delimiter) params.set("delimiter", opts.delimiter);
-    if (opts.columns) params.set("columns", opts.columns);
-    if (opts.wcvpExtra) params.set("wcvpExtra", opts.wcvpExtra);
-    const url = new URL(`/v1/jobs/${id}/download?${params}`, creds.server).toString();
-    const res = await fetch(url, { headers: { authorization: `Bearer ${creds.token}` } });
-    if (!res.ok) {
-      const text = await res.text().catch(() => "");
-      throw new ApiError(`HTTP ${res.status}`, res.status, text);
-    }
-    const disp = res.headers.get("content-disposition") ?? "";
-    const m = /filename="?([^"]+)"?/.exec(disp);
-    const ext = opts.bundle ? "zip" : opts.format === "csv" ? "csv" : opts.format === "json" ? "json" : opts.format === "xlsx" ? "xlsx" : "ndjson";
-    const filename = m?.[1] ?? `planttaxomatcher_${id}.${ext}`;
-    const buf = Buffer.from(await res.arrayBuffer());
-    return { filename, body: buf };
-  },
-  async *streamJob(creds, id) {
-    const url = new URL(`/v1/jobs/${id}/stream`, creds.server).toString();
-    const res = await fetch(url, { headers: { authorization: `Bearer ${creds.token}` } });
-    if (!res.ok || !res.body) {
-      const text = await res.text().catch(() => "");
-      throw new ApiError(`HTTP ${res.status}`, res.status, text);
-    }
-    const reader = res.body.getReader();
-    const decoder = new TextDecoder("utf-8");
-    let buf = "";
-    try {
-      for (; ; ) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buf += decoder.decode(value, { stream: true });
-        let nl;
-        while ((nl = buf.indexOf("\n")) >= 0) {
-          const line = buf.slice(0, nl).trim();
-          buf = buf.slice(nl + 1);
-          if (!line) continue;
-          try {
-            yield JSON.parse(line);
-          } catch {
-          }
+  }
+  async function failWith(res) {
+    const text = await res.text().catch(() => "");
+    throw new ApiError(res.status, (text && safeJson(text)) ?? text);
+  }
+  return {
+    async startDeviceAuthorization(server, clientName) {
+      let created;
+      try {
+        created = await call({ server }, "/v1/device-authorizations", {
+          method: "POST",
+          json: { clientName }
+        });
+      } catch (err) {
+        if (err instanceof ApiError && err.status === 404) {
+          throw new CliError(
+            `${server} does not offer browser sign-in`,
+            EXIT.usage,
+            "Pass a personal token instead: `planttaxomatcher login --token-stdin`."
+          );
         }
+        throw err;
       }
-    } finally {
-      await reader.cancel().catch(() => {
+      const checked = deviceAuthorizationCreatedSchema.safeParse(created);
+      if (!checked.success) throw notAnApi(server, "/v1/device-authorizations");
+      return checked.data;
+    },
+    /** One poll: the token once approved, else the RFC 8628 reason to keep waiting or stop. */
+    async pollDeviceToken(server, deviceCode) {
+      const res = await send({ server }, "/v1/device-tokens", {
+        method: "POST",
+        body: JSON.stringify({ deviceCode })
       });
+      const text = await res.text();
+      const parsed = text ? safeJson(text) : null;
+      if (res.status === 400) {
+        const refusal = deviceTokenErrorSchema.safeParse(parsed);
+        if (refusal.success) return refusal.data;
+      }
+      if (!res.ok) throw new ApiError(res.status, parsed ?? text);
+      const token = deviceTokenSchema.safeParse(parsed);
+      if (!token.success) throw notAnApi(server, "/v1/device-tokens");
+      return token.data;
+    },
+    async me(c) {
+      const checked = meSchema.safeParse(await call(c, "/v1/me"));
+      if (!checked.success) throw notAnApi(c.server, "/v1/me");
+      return checked.data;
+    },
+    listJobs(c, opts = {}) {
+      const params = new URLSearchParams();
+      if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+      if (opts.status) params.set("status", opts.status);
+      const query = params.size > 0 ? `?${params}` : "";
+      return call(c, `/v1/jobs${query}`);
+    },
+    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" }),
+    async submitJob(c, filePath, config, name) {
+      const form = new FormData();
+      form.set("config", JSON.stringify(config));
+      if (name) form.set("name", name);
+      form.set("file", await openAsBlob(filePath, { type: uploadMimeType(filePath) }), basename(filePath));
+      const res = await send(c, "/v1/jobs", { method: "POST", body: form });
+      if (!res.ok) return failWith(res);
+      return await res.json();
+    },
+    async downloadJob(c, id, opts) {
+      const res = await send(c, `/v1/jobs/${encodeURIComponent(id)}/download?${downloadQuery(opts)}`);
+      if (!res.ok) return failWith(res);
+      const filename = downloadFilename(res.headers.get("content-disposition"), id, opts);
+      return { filename, body: Buffer.from(await res.arrayBuffer()) };
+    },
+    async *streamJob(c, id) {
+      const res = await send(c, `/v1/jobs/${encodeURIComponent(id)}/stream`);
+      if (!res.ok || !res.body) return failWith(res);
+      const reader = res.body.getReader();
+      const chunks = {
+        async *[Symbol.asyncIterator]() {
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done) return;
+            yield value;
+          }
+        }
+      };
+      try {
+        yield* parseNdjson(chunks);
+      } finally {
+        await reader.cancel().catch(() => {
+        });
+      }
     }
-  }
-};
+  };
+}
 
 // src/config.ts
-import { promises as fs2 } from "fs";
+import { promises as fs } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-var CONFIG_DIR = join(homedir(), ".config", "planttaxomatcher");
-var CONFIG_FILE = join(CONFIG_DIR, "credentials");
-async function readCredentials() {
+
+// src/transport.ts
+function isLoopback(hostname2) {
+  return hostname2 === "localhost" || hostname2 === "127.0.0.1" || hostname2 === "[::1]" || hostname2 === "::1" || hostname2.endsWith(".localhost");
+}
+function assertServerTransport(server, options = { allowInsecure: false }) {
+  let url;
+  try {
+    url = new URL(server);
+  } catch {
+    throw new CliError(`invalid server URL: ${server}`, EXIT.usage);
+  }
+  if (url.protocol === "https:") return;
+  if (url.protocol !== "http:") {
+    throw new CliError(`server must use http or https (got ${url.protocol})`, EXIT.usage);
+  }
+  if (!isLoopback(url.hostname) && !options.allowInsecure) {
+    const override = options.insecureFlag ? ", or pass --insecure to override (NOT recommended)" : "";
+    throw new CliError(
+      `refusing to send a token in cleartext to ${url.host}. Use an https URL${override}.`,
+      EXIT.usage
+    );
+  }
+}
+
+// src/config.ts
+function defaultConfigDir() {
+  return join(homedir(), ".config", "planttaxomatcher");
+}
+function createCredentialStore(dir = defaultConfigDir()) {
+  const file = join(dir, "credentials");
+  return {
+    file,
+    async read() {
+      try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+      } catch (err) {
+        if (err.code === "ENOENT") return null;
+        throw err;
+      }
+    },
+    async write(creds) {
+      await fs.mkdir(dir, { recursive: true, mode: 448 });
+      await fs.writeFile(file, JSON.stringify(creds, null, 2), { mode: 384 });
+      await fs.chmod(file, 384);
+    },
+    async clear() {
+      await fs.rm(file, { force: true });
+    }
+  };
+}
+function envValue(env2, key) {
+  const value = env2[key]?.trim();
+  return value ? value : void 0;
+}
+function serverFromEnv(env2) {
+  return envValue(env2, "PLANTTAXOMATCHER_SERVER");
+}
+function tokenFromEnv(env2) {
+  return envValue(env2, "PLANTTAXOMATCHER_TOKEN");
+}
+function sameServer(a, b) {
+  const normalize = (url) => url.trim().replace(/\/+$/, "").toLowerCase();
+  return normalize(a) === normalize(b);
+}
+function resolveCredentials(stored, env2) {
+  const envToken = tokenFromEnv(env2);
+  const envServer = serverFromEnv(env2);
+  if (envToken) return { token: envToken, server: envServer ?? DEFAULT_SERVER_URL };
+  if (!stored) return null;
+  if (envServer && !sameServer(envServer, stored.server)) {
+    throw new CliError(
+      `PLANTTAXOMATCHER_SERVER (${envServer}) is not the server of the saved login (${stored.server})`,
+      EXIT.usage,
+      "Set PLANTTAXOMATCHER_TOKEN for that server too, or run `planttaxomatcher login --server <url>`."
+    );
+  }
+  return stored;
+}
+async function requireCredentials(store, env2) {
+  const envServer = serverFromEnv(env2);
+  if (envServer) assertServerTransport(envServer, { allowInsecure: false });
+  const creds = resolveCredentials(await store.read(), env2);
+  if (!creds) throw new CliError("not signed in", EXIT.auth, LOGIN_HINT);
+  return creds;
+}
+
+// src/skills/paths.ts
+import { join as join2 } from "path";
+var SKILL_NAME = "planttaxomatcher";
+var MARKER_FILE = ".planttaxomatcher-managed";
+var AGENTS = ["claude", "codex", "opencode", "pi"];
+var SKILL_DIRS = ["claude", "agents", "opencode", "pi"];
+var env = (value) => value?.trim() ? value.trim() : void 0;
+function skillPaths(home, vars) {
+  const dataHome = env(vars.XDG_DATA_HOME) ?? join2(home, ".local", "share");
+  const configHome = env(vars.XDG_CONFIG_HOME) ?? join2(home, ".config");
+  const claudeHome = env(vars.CLAUDE_CONFIG_DIR) ?? join2(home, ".claude");
+  return {
+    canonical: join2(dataHome, "planttaxomatcher", "skills", SKILL_NAME),
+    entries: {
+      claude: join2(claudeHome, "skills", SKILL_NAME),
+      agents: join2(home, ".agents", "skills", SKILL_NAME),
+      opencode: join2(configHome, "opencode", "skills", SKILL_NAME),
+      pi: join2(home, ".pi", "agent", "skills", SKILL_NAME)
+    },
+    agentHomes: {
+      claude: claudeHome,
+      codex: join2(home, ".codex"),
+      opencode: join2(configHome, "opencode"),
+      pi: join2(home, ".pi")
+    }
+  };
+}
+var READS = {
+  claude: ["claude"],
+  codex: ["agents"],
+  opencode: ["opencode", "agents", "claude"],
+  pi: ["pi", "agents"]
+};
+function linkPlan(agents, alreadyLinked) {
+  const plan = /* @__PURE__ */ new Set();
+  if (agents.includes("claude")) plan.add("claude");
+  if (agents.includes("codex") || agents.includes("pi")) plan.add("agents");
+  const openCodeCovered = ["claude", "agents"].some(
+    (dir) => plan.has(dir) || alreadyLinked.has(dir)
+  );
+  if (agents.includes("opencode") && !openCodeCovered) plan.add("opencode");
+  return [...plan];
+}
+function parseAgents(value) {
+  const names = value.split(",").map((name) => name.trim().toLowerCase()).filter(Boolean);
+  if (names.includes("all")) return "all";
+  return names.length > 0 && names.every((name) => AGENTS.includes(name)) ? names : null;
+}
+function isNewerVersion(candidate, current) {
+  const parse = (v) => v.split(/[.+-]/).slice(0, 3).map((n) => Number.parseInt(n, 10) || 0);
+  const [a, b] = [parse(candidate), parse(current)];
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}
+
+// src/deps.ts
+async function readAllStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+function browserCommand(url) {
+  if (process.platform === "darwin") return ["open", [url]];
+  if (process.platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+  return ["xdg-open", [url]];
+}
+function openInBrowser(url, env2) {
+  if (env2.SSH_CONNECTION || env2.SSH_TTY) return Promise.resolve(false);
+  const [command, args] = browserCommand(url);
+  return new Promise((resolve2) => {
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.once("error", () => resolve2(false));
+    child.once("spawn", () => {
+      child.unref();
+      resolve2(true);
+    });
+  });
+}
+function defaultDeps() {
+  return {
+    api: createApiClient(),
+    store: createCredentialStore(),
+    env: process.env,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    stdinIsTTY: !!process.stdin.isTTY,
+    readStdin: readAllStdin,
+    promptConfirm: (message) => confirm({ message, default: true }),
+    openBrowser: (url) => openInBrowser(url, process.env),
+    promptAgents: (detected) => checkbox({
+      message: "Install the skill for",
+      choices: AGENTS.map((agent) => ({ value: agent, checked: detected.includes(agent) }))
+    }),
+    hostname,
+    home: homedir2(),
+    // `src/` in development and the bundled `dist/` both sit next to `skills/`.
+    skillSource: fileURLToPath(new URL("../skills/planttaxomatcher", import.meta.url)),
+    sleep: (ms) => sleep(ms),
+    now: Date.now
+  };
+}
+
+// src/program.ts
+import { Command } from "commander";
+import kleur10 from "kleur";
+
+// src/output.ts
+import kleur from "kleur";
+function createOutput(stdout, stderr, json, now = Date.now) {
+  const human = json ? stderr : stdout;
+  const line = (text) => human.write(`${text}
+`);
+  return {
+    json,
+    info: line,
+    success: (message) => line(`${kleur.green("\u2713")} ${message}`),
+    warn: (message) => stderr.write(`${kleur.yellow("!")} ${message}
+`),
+    data: (value) => stdout.write(`${JSON.stringify(value)}
+`),
+    progress: createProgressWriter(human, now)
+  };
+}
+var NON_TTY_PROGRESS_INTERVAL_MS = 5e3;
+function createProgressWriter(sink, now, intervalMs = NON_TTY_PROGRESS_INTERVAL_MS) {
+  let width = 0;
+  let lastEmittedAt = null;
+  let pending = null;
+  if (sink.isTTY) {
+    return {
+      update(line) {
+        sink.write(`\r${line.padEnd(width)}`);
+        width = line.length;
+      },
+      done() {
+        if (width > 0) sink.write("\n");
+        width = 0;
+      }
+    };
+  }
+  return {
+    update(line) {
+      const at = now();
+      if (lastEmittedAt !== null && at - lastEmittedAt < intervalMs) {
+        pending = line;
+        return;
+      }
+      sink.write(`${line}
+`);
+      lastEmittedAt = at;
+      pending = null;
+    },
+    done() {
+      if (pending !== null) sink.write(`${pending}
+`);
+      pending = null;
+      lastEmittedAt = null;
+    }
+  };
+}
+
+// src/device-login.ts
+import kleur2 from "kleur";
+var RESTART_HINT = "Run `planttaxomatcher login` again.";
+var CLIENT_NAME_MAX = 100;
+function isTransient(err) {
+  if (err instanceof ApiError) return err.status === 429 || err.status >= 500;
+  return err instanceof CliError && err.message.startsWith("cannot reach");
+}
+async function pollOnce(deps2, server, deviceCode) {
   try {
-    const raw = await fs2.readFile(CONFIG_FILE, "utf8");
-    return JSON.parse(raw);
+    return await deps2.api.pollDeviceToken(server, deviceCode);
   } catch (err) {
-    if (err.code === "ENOENT") return null;
+    if (isTransient(err)) return { error: "slow_down" };
     throw err;
   }
 }
-async function writeCredentials(creds) {
-  await fs2.mkdir(CONFIG_DIR, { recursive: true, mode: 448 });
-  await fs2.writeFile(CONFIG_FILE, JSON.stringify(creds, null, 2), { mode: 384 });
+async function deviceLogin(deps2, out, server, options) {
+  const clientName = deps2.hostname().trim().slice(0, CLIENT_NAME_MAX) || "unknown";
+  const request = await deps2.api.startDeviceAuthorization(server, clientName);
+  out.info(`To sign in, open this page and approve the code ${kleur2.bold(request.userCode)}:`);
+  out.info(`  ${kleur2.cyan(request.verificationUriComplete)}`);
+  if (options.openBrowser && await deps2.openBrowser(request.verificationUriComplete)) {
+    out.info(kleur2.gray("Opened it in your browser."));
+  }
+  out.info(kleur2.gray("Waiting for approval\u2026"));
+  const deadline = deps2.now() + request.expiresIn * 1e3;
+  let interval = request.interval;
+  while (deps2.now() < deadline) {
+    await deps2.sleep(interval * 1e3);
+    const answer = await pollOnce(deps2, server, request.deviceCode);
+    if ("token" in answer) return answer;
+    if (answer.error === "slow_down") interval = answer.interval ?? interval + SLOW_DOWN_STEP_SECONDS;
+    else if (answer.error === "access_denied")
+      throw new CliError("the sign-in was denied in the browser", EXIT.auth);
+    else if (answer.error === "expired_token") break;
+  }
+  throw new CliError("the sign-in code expired before it was approved", EXIT.auth, RESTART_HINT);
 }
-async function clearCredentials() {
+
+// src/commands/auth.ts
+async function suppliedToken(opts, deps2) {
+  if (opts.tokenStdin) {
+    const token = (await deps2.readStdin()).trim();
+    if (!token) throw new CliError("--token-stdin was set but stdin was empty", EXIT.usage);
+    return token;
+  }
+  if (opts.token) return opts.token.trim();
+  return tokenFromEnv(deps2.env) ?? null;
+}
+async function browserToken(deps2, out, server, opts) {
+  if (parseEnvFlag(deps2.env.CI, false)) {
+    throw new CliError(
+      "no token given, and a browser sign-in cannot be approved in CI",
+      EXIT.usage,
+      "Set PLANTTAXOMATCHER_TOKEN, or pipe one to `planttaxomatcher login --token-stdin`."
+    );
+  }
+  return (await deviceLogin(deps2, out, server, { openBrowser: opts.browser !== false })).token;
+}
+async function verifyToken(deps2, server, token) {
   try {
-    await fs2.unlink(CONFIG_FILE);
+    return await deps2.api.me({ server, token });
   } catch (err) {
-    if (err.code !== "ENOENT") throw err;
+    if (err instanceof ApiError && err.status === 401) {
+      throw new CliError(`${server} rejected this token (${err.message})`, EXIT.auth);
+    }
+    if (err instanceof ApiError && err.status === 403) return null;
+    throw err;
   }
 }
-async function requireCredentials() {
-  const creds = await readCredentials();
-  if (!creds) {
-    throw new Error("Not logged in. Run: planttaxomatcher login --token <t> --server <url>");
+function registerAuthCommands(program, deps2) {
+  program.command("login").description(
+    "Sign in through the browser (approve a code on the web app), or save a personal token you pass in"
+  ).option(
+    "--token <token>",
+    "Personal token (ptm_...). Avoid on shared hosts: it is visible in shell history and the process list. Prefer --token-stdin or PLANTTAXOMATCHER_TOKEN."
+  ).option(
+    "--token-stdin",
+    "Read the token from stdin (e.g. `cat token.txt | planttaxomatcher login --token-stdin`)",
+    false
+  ).option("--server <url>", `API server URL (default: $PLANTTAXOMATCHER_SERVER, else ${DEFAULT_SERVER_URL})`).option(
+    "--insecure",
+    "Allow sending the token over cleartext http to a non-loopback server (NOT recommended)",
+    false
+  ).option("--no-browser", "Print the sign-in link without opening a browser").option("--json", "Print the result as JSON", false).action(async (opts) => {
+    const out = createOutput(deps2.stdout, deps2.stderr, !!opts.json, deps2.now);
+    const server = opts.server ?? serverFromEnv(deps2.env) ?? DEFAULT_SERVER_URL;
+    assertServerTransport(server, { allowInsecure: !!opts.insecure, insecureFlag: true });
+    const token = await suppliedToken(opts, deps2) ?? await browserToken(deps2, out, server, opts);
+    if (!tokenStringSchema.safeParse(token).success) {
+      throw new CliError("malformed token \u2014 expected ptm_<12 chars>_<32 chars>", EXIT.usage);
+    }
+    const me = await verifyToken(deps2, server, token);
+    await deps2.store.write({ token, server, ...me?.appUrl ? { appUrl: me.appUrl } : {} });
+    if (out.json) {
+      out.data({ server, displayName: me?.displayName ?? null, scopes: me?.scopes ?? null });
+      return;
+    }
+    out.success(me ? `Signed in to ${server} as ${me.displayName}` : `Signed in to ${server}`);
+    if (!me) out.warn("this token cannot read jobs (no read:job scope)");
+  });
+  program.command("logout").description("Forget the saved token").action(async () => {
+    await deps2.store.clear();
+    createOutput(deps2.stdout, deps2.stderr, false).success("Logged out");
+  });
+  program.command("whoami").description("Show who the current token belongs to").option("--json", "Print the result as JSON", false).action(async (opts) => {
+    const out = createOutput(deps2.stdout, deps2.stderr, !!opts.json, deps2.now);
+    const creds = await requireCredentials(deps2.store, deps2.env);
+    const me = await deps2.api.me(creds);
+    if (out.json) {
+      out.data({ ...me, server: creds.server });
+      return;
+    }
+    out.info(`${me.displayName}  team=${me.teamId}  scopes=${me.scopes.join(",")}`);
+    out.info(`server=${creds.server}`);
+  });
+}
+
+// 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 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)) {
+    throw new CliError(`--format must be ${FORMATS.join(", ")} (got ${opts.format})`, EXIT.usage);
+  }
+  const delimiter = opts.delimiter;
+  if (!DELIMITERS.includes(delimiter)) {
+    throw new CliError(`--delimiter must be ${DELIMITERS.join(", ")} (got ${opts.delimiter})`, EXIT.usage);
+  }
+  return {
+    format,
+    ...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) {
+  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(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)}`);
+  }
+}
+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",
+    "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, 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 / --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 = 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);
+    if (out.json) return out.data({ path, bytes: body.length, format: download.format });
+    out.success(`wrote ${body.length} bytes to ${path}`);
+  });
+}
+
+// src/commands/jobs.ts
+import kleur6 from "kleur";
+
+// src/flags.ts
+function parseIntegerFlag(value, flag, range = {}) {
+  const parsed = Number(value);
+  const { min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER } = range;
+  if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+    const bounds = range.min !== void 0 || range.max !== void 0 ? ` between ${min} and ${max}` : "";
+    throw new CliError(`${flag} must be an integer${bounds} (got "${value}")`, EXIT.usage);
+  }
+  return parsed;
+}
+
+// src/watch.ts
+import kleur5 from "kleur";
+var STOP = /* @__PURE__ */ new Set(["completed", "failed", "cancelled", "paused"]);
+function isStop(status) {
+  return typeof status === "string" && STOP.has(status);
+}
+function stopStatusOf(frame) {
+  if (frame.type === "status" || frame.type === "completed") return isStop(frame.status) ? frame.status : null;
+  if (frame.type === "error") return "failed";
+  return null;
+}
+function progressLine(frame) {
+  const processed = Number(frame.processedQueries ?? frame.processedRows ?? 0);
+  const total = Number(frame.totalQueries ?? frame.totalRows ?? 0);
+  const phase = processed === 0 && typeof frame.phase === "string" ? ` (${frame.phase}\u2026)` : "";
+  return `  progress: ${processed}/${total}${phase}`;
+}
+function render(out, frame) {
+  if (frame.type === "progress") {
+    out.progress.update(progressLine(frame));
+    return;
+  }
+  if (frame.type === "status") {
+    out.progress.done();
+    out.info(`${kleur5.gray("\u2022")} ${String(frame.status)}`);
+  } else if (frame.type === "error") {
+    out.progress.done();
+    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(`${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);
+    if (out.json) out.data(frame);
+    else if (!(status && frame.type === "status")) render(out, frame);
+    if (status) return finish(out, status);
+  }
+  out.progress.done();
+  const job = await api.getJob(creds, jobId);
+  if (isStop(job.status)) return finish(out, job.status);
+  throw new CliError(
+    `the progress stream closed while job ${jobId} was still ${job.status}`,
+    void 0,
+    `Run \`planttaxomatcher watch ${jobId}\` to follow it again.`
+  );
+}
+function finish(out, status) {
+  out.progress.done();
+  if (!out.json) {
+    if (status === "completed") out.success("completed");
+    else if (status === "paused") out.info(kleur5.yellow("paused \u2014 resume it, then watch again"));
+    else out.info(kleur5.red(`\u2717 ${status}`));
+  }
+  return status;
+}
+
+// src/commands/jobs.ts
+function jobUrl(creds, jobId) {
+  return new URL(`/jobs/${encodeURIComponent(jobId)}`, creds.appUrl ?? creds.server).toString();
+}
+function watchOutcomeError(results) {
+  const stopped = results.filter((r) => r.status !== "completed");
+  if (stopped.length === 0) return null;
+  const list = stopped.map((r) => `${r.id} (${r.status})`).join(", ");
+  const onlyPaused = stopped.every((r) => r.status === "paused");
+  return new CliError(
+    onlyPaused ? `job paused: ${list}` : `job did not complete: ${list}`,
+    onlyPaused ? EXIT.jobPaused : EXIT.jobFailed,
+    onlyPaused ? "Run `planttaxomatcher resume <jobId>`, then `planttaxomatcher watch <jobId>`." : void 0
+  );
+}
+function listLine(job) {
+  const matched = `${String(job.matchedRows).padStart(6)}/${String(job.totalRows).padStart(6)} matched`;
+  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" },
+  resume: { description: "Resume a paused job", past: "resumed" },
+  cancel: { description: "Cancel a job. Rows already matched are kept; pending queries stop.", past: "cancelled" }
+};
+function runAction(deps2, action, creds, jobId) {
+  if (action === "pause") return deps2.api.pauseJob(creds, jobId);
+  if (action === "resume") return deps2.api.resumeJob(creds, jobId);
+  return deps2.api.cancelJob(creds, jobId);
+}
+function registerJobCommands(program, deps2) {
+  program.command("list").description("List recent jobs, newest first").option("--limit <n>", "How many jobs to show (1-100)", "20").option("--status <status>", `Only jobs in this status: ${jobStatusSchema.options.join(", ")}`).option("--json", "Print the jobs as a JSON array", false).action(async (opts) => {
+    const out = createOutput(deps2.stdout, deps2.stderr, !!opts.json, deps2.now);
+    const status = opts.status === void 0 ? void 0 : jobStatusSchema.safeParse(opts.status);
+    if (status && !status.success) {
+      throw new CliError(`--status must be one of ${jobStatusSchema.options.join(", ")}`, EXIT.usage);
+    }
+    const limit = parseIntegerFlag(opts.limit, "--limit", { min: 1, max: 100 });
+    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(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) => {
+    const creds = await requireCredentials(deps2.store, deps2.env);
+    const job = await deps2.api.getJob(creds, jobId);
+    deps2.stdout.write(`${JSON.stringify({ ...job, url: jobUrl(creds, job.id) }, null, 2)}
+`);
+  });
+  program.command("watch <jobId>").description("Follow a job until it stops. Exits 4 if it fails or is cancelled, 5 if it is paused.").option("--json", "Echo each progress frame as one NDJSON line", false).action(async (jobId, opts) => {
+    const out = createOutput(deps2.stdout, deps2.stderr, !!opts.json, deps2.now);
+    const creds = await requireCredentials(deps2.store, deps2.env);
+    const status = await watchJob(deps2.api, out, creds, jobId);
+    const failure = watchOutcomeError([{ id: jobId, status }]);
+    if (failure) throw failure;
+  });
+  for (const [action, { description, past }] of Object.entries(JOB_ACTIONS)) {
+    program.command(`${action} <jobId>`).description(description).option("--json", "Print the updated job as JSON", false).action(async (jobId, opts) => {
+      const out = createOutput(deps2.stdout, deps2.stderr, !!opts.json, deps2.now);
+      const creds = await requireCredentials(deps2.store, deps2.env);
+      const job = await runAction(deps2, action, creds, jobId);
+      if (out.json) return out.data(job);
+      out.success(`${past}: ${job.id} (status=${job.status})`);
+    });
+  }
+}
+
+// src/commands/skills.ts
+import kleur7 from "kleur";
+
+// src/skills/manage.ts
+import { promises as fs3 } from "fs";
+import { dirname as dirname2, resolve } from "path";
+
+// src/skills/content.ts
+import { createHash } from "crypto";
+import { promises as fs2 } from "fs";
+import { dirname, join as join3, relative } from "path";
+async function walk(dir, root = dir) {
+  const found = [];
+  for (const entry of await fs2.readdir(dir, { withFileTypes: true })) {
+    const path = join3(dir, entry.name);
+    if (entry.isDirectory()) found.push(...await walk(path, root));
+    else if (entry.isFile() && entry.name !== MARKER_FILE) found.push(relative(root, path));
+  }
+  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).replaceAll("{{exportColumns}}", exportColumnsMarkdown())
+    );
+  }
+  return files;
+}
+function hashFiles(files) {
+  const hash = createHash("sha256");
+  for (const [path, text] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+    hash.update(path).update("\0").update(text).update("\0");
+  }
+  return hash.digest("hex");
+}
+async function readSkillDir(dir) {
+  const files = /* @__PURE__ */ new Map();
+  for (const path of await walk(dir)) files.set(path, await fs2.readFile(join3(dir, path), "utf8"));
+  return files;
+}
+async function readMarker(dir) {
+  try {
+    const parsed = JSON.parse(await fs2.readFile(join3(dir, MARKER_FILE), "utf8"));
+    return typeof parsed.version === "string" && typeof parsed.hash === "string" ? { version: parsed.version, hash: parsed.hash } : null;
+  } catch {
+    return null;
+  }
+}
+async function writeSkillDir(dir, files, version2) {
+  const staging = join3(dirname(dirname(dir)), `.planttaxomatcher-staging-${process.pid}-${Date.now()}`);
+  try {
+    for (const [path, text] of files) {
+      await fs2.mkdir(dirname(join3(staging, path)), { recursive: true });
+      await fs2.writeFile(join3(staging, path), text);
+    }
+    const marker = { version: version2, hash: hashFiles(files) };
+    await fs2.writeFile(join3(staging, MARKER_FILE), `${JSON.stringify(marker, null, 2)}
+`);
+    await fs2.rm(dir, { recursive: true, force: true });
+    await fs2.mkdir(dirname(dir), { recursive: true });
+    await fs2.rename(staging, dir);
+  } finally {
+    await fs2.rm(staging, { recursive: true, force: true });
+  }
+}
+async function isPristine(dir) {
+  const marker = await readMarker(dir);
+  return !!marker && hashFiles(await readSkillDir(dir)) === marker.hash;
+}
+
+// src/skills/manage.ts
+var symlink = (target, path) => fs3.symlink(target, path, "junction");
+function samePath(a, b) {
+  const norm = (p) => resolve(p.replace(/^\\\\\?\\/, ""));
+  return process.platform === "win32" ? norm(a).toLowerCase() === norm(b).toLowerCase() : norm(a) === norm(b);
+}
+var OUR_LAYOUT = /[/\\]planttaxomatcher[/\\]skills[/\\]planttaxomatcher$/;
+async function exists(path) {
+  return fs3.stat(path).then(
+    () => true,
+    () => false
+  );
+}
+async function classify(entry, canonical) {
+  const stat = await fs3.lstat(entry).catch(() => null);
+  if (!stat) return { kind: "missing" };
+  if (stat.isSymbolicLink()) {
+    const target = resolve(dirname2(entry), await fs3.readlink(entry));
+    if (samePath(target, canonical)) return await exists(canonical) ? { kind: "link" } : { kind: "broken" };
+    return OUR_LAYOUT.test(target) || await readMarker(target) ? { kind: "stale" } : { kind: "foreign" };
+  }
+  if (!stat.isDirectory()) return { kind: "foreign" };
+  const marker = await readMarker(entry);
+  return marker ? { kind: "copy", version: marker.version, pristine: await isPristine(entry) } : { kind: "foreign" };
+}
+async function classifyAll(paths) {
+  const states = {};
+  for (const dir of SKILL_DIRS) states[dir] = await classify(paths.entries[dir], paths.canonical);
+  return states;
+}
+var isOurs = (state) => state.kind === "link" || state.kind === "copy" || state.kind === "stale";
+async function detectAgents(paths) {
+  const found = [];
+  for (const agent of AGENTS) if (await exists(paths.agentHomes[agent])) found.push(agent);
+  return found;
+}
+async function writeCanonical(paths, files, version2, force) {
+  const state = await fs3.lstat(paths.canonical).catch(() => null);
+  if (state && !force) {
+    const marker = await readMarker(paths.canonical);
+    if (marker && isNewerVersion(marker.version, version2)) {
+      throw new CliError(
+        `the installed skill (${marker.version}) is newer than this CLI (${version2})`,
+        EXIT.usage,
+        "Run the newer CLI (`npx -y @plantnet/planttaxomatcher@latest skills install`), or pass --force."
+      );
+    }
+    if (!marker || !await isPristine(paths.canonical)) {
+      throw new CliError(
+        `${paths.canonical} was edited or is not ours`,
+        EXIT.usage,
+        "Pass --force to replace it with the skill shipped with this CLI."
+      );
+    }
+  }
+  await writeSkillDir(paths.canonical, files, version2);
+}
+async function place(paths, dir, state, files, version2, options) {
+  const entry = paths.entries[dir];
+  if (state.kind === "foreign") return "skipped-foreign";
+  if (state.kind === "link") return "kept";
+  if (state.kind === "copy") {
+    if (!state.pristine && !options.force) return "skipped-edited";
+    await writeSkillDir(entry, files, version2);
+    return "refreshed";
+  }
+  if (state.kind === "broken" || state.kind === "stale") await fs3.unlink(entry);
+  await fs3.mkdir(dirname2(entry), { recursive: true });
+  try {
+    await options.link(paths.canonical, entry);
+    return "linked";
+  } catch {
+    await writeSkillDir(entry, files, version2);
+    return "copied";
+  }
+}
+async function installSkill(paths, source, version2, agents, options = {}) {
+  const opts = { force: !!options.force, link: options.link ?? symlink };
+  const files = await renderSkill(source, version2);
+  await writeCanonical(paths, files, version2, opts.force);
+  const states = await classifyAll(paths);
+  const linked = new Set(SKILL_DIRS.filter((dir) => isOurs(states[dir])));
+  const planned = new Set(linkPlan(agents, linked));
+  const entries = [];
+  for (const dir of SKILL_DIRS) {
+    const state = states[dir];
+    if (!planned.has(dir) && !(state.kind === "copy" && state.pristine)) continue;
+    entries.push({ dir, path: paths.entries[dir], action: await place(paths, dir, state, files, version2, opts) });
+  }
+  return { canonical: paths.canonical, entries };
+}
+async function uninstallSkill(paths, options = {}) {
+  const entries = [];
+  for (const [dir, state] of Object.entries(await classifyAll(paths))) {
+    const path = paths.entries[dir];
+    if (state.kind === "link" || state.kind === "broken" || state.kind === "stale") {
+      await fs3.unlink(path);
+      entries.push({ dir, path, action: "removed" });
+    } else if (state.kind === "copy") {
+      const removable = state.pristine || options.force;
+      if (removable) await fs3.rm(path, { recursive: true, force: true });
+      entries.push({ dir, path, action: removable ? "removed" : "skipped-edited" });
+    }
+  }
+  const marker = await readMarker(paths.canonical);
+  if (marker && (options.force || await isPristine(paths.canonical))) {
+    await fs3.rm(paths.canonical, { recursive: true, force: true });
+  }
+  return { canonical: paths.canonical, entries };
+}
+async function skillStatus(paths) {
+  const states = await classifyAll(paths);
+  const marker = await readMarker(paths.canonical);
+  const installed = new Set(await detectAgents(paths));
+  return {
+    canonical: {
+      path: paths.canonical,
+      version: marker?.version ?? null,
+      pristine: marker ? await isPristine(paths.canonical) : false
+    },
+    entries: SKILL_DIRS.map((dir) => ({ dir, path: paths.entries[dir], ...states[dir] })),
+    agents: AGENTS.map((agent) => {
+      const loads = READS[agent].find((dir) => states[dir].kind !== "missing") ?? null;
+      return { agent, installed: installed.has(agent), loads, state: loads ? states[loads].kind : "missing" };
+    })
+  };
+}
+async function refreshSkillIfOutdated(paths, source, version2) {
+  try {
+    const marker = await readMarker(paths.canonical);
+    if (!marker || !isNewerVersion(version2, marker.version) || !await isPristine(paths.canonical)) return false;
+    const files = await renderSkill(source, version2);
+    await writeSkillDir(paths.canonical, files, version2);
+    for (const [dir, state] of Object.entries(await classifyAll(paths))) {
+      if (state.kind === "copy" && state.pristine) await writeSkillDir(paths.entries[dir], files, version2);
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/commands/skills.ts
+var AGENT_NAMES = { claude: "Claude Code", codex: "Codex", opencode: "OpenCode", pi: "pi" };
+var SERVES = {
+  claude: "Claude Code (and OpenCode)",
+  agents: "Codex, pi (and OpenCode)",
+  opencode: "OpenCode",
+  pi: "pi"
+};
+var ACTION_TEXT = {
+  linked: "linked",
+  copied: "copied (links are not available here)",
+  kept: "already linked",
+  refreshed: "copy refreshed",
+  removed: "removed",
+  "skipped-foreign": "left alone: a skill of the same name that is not ours",
+  "skipped-edited": "left alone: edited by hand (use --force)"
+};
+var RELOAD_HINTS = {
+  opencode: "Restart OpenCode to load it.",
+  pi: "In pi, run /reload."
+};
+async function chooseAgents(deps2, requested, detected) {
+  if (requested !== void 0) {
+    const parsed = parseAgents(requested);
+    if (!parsed) throw new CliError(`--agent takes ${AGENTS.join(", ")} or all (got "${requested}")`, EXIT.usage);
+    return parsed === "all" ? [...AGENTS] : parsed;
+  }
+  if (deps2.stdinIsTTY) return deps2.promptAgents(detected);
+  if (detected.length === 0) {
+    throw new CliError(
+      "no supported agent found in your home directory",
+      EXIT.usage,
+      `Pass --agent with any of ${AGENTS.join(", ")}, or all.`
+    );
+  }
+  return detected;
+}
+function tilde(path, home) {
+  return path === home || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+function printEntries(out, result, home) {
+  for (const { dir, path, action } of result.entries) {
+    const line = `${SERVES[dir]}: ${ACTION_TEXT[action]} ${kleur7.gray(tilde(path, home))}`;
+    if (action.startsWith("skipped")) out.warn(line);
+    else out.success(line);
   }
-  return creds;
+}
+function registerSkillsCommands(program, deps2, version2) {
+  const skills = program.command("skills").description("Add the PlantTaxoMatcher skill to your AI coding agents (Claude Code, Codex, OpenCode, pi)");
+  const paths = () => skillPaths(deps2.home, deps2.env);
+  skills.command("install").description(
+    "Install the skill for your user. The files live in one CLI-owned folder; each agent only gets a link to it."
+  ).option(
+    "--agent <list>",
+    `Comma-separated: ${AGENTS.join(", ")}, or all (default: the agents found, or a prompt)`
+  ).option("--force", "Replace an installed skill even if it was 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 agents = await chooseAgents(deps2, opts.agent, await detectAgents(paths()));
+    if (agents.length === 0) throw new CliError("no agent selected", EXIT.usage);
+    const result = await installSkill(paths(), deps2.skillSource, version2, agents, { force: opts.force });
+    if (out.json) return out.data({ version: version2, agents, ...result });
+    out.info(
+      `${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(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(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) => {
+    const out = createOutput(deps2.stdout, deps2.stderr, opts.json, deps2.now);
+    const status = await skillStatus(paths());
+    if (out.json) return out.data({ cliVersion: version2, ...status });
+    const { canonical } = status;
+    out.info(
+      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)} ${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 : kleur7.gray(`not found (${where})`)}`);
+    }
+  });
 }
 
+// src/commands/submit.ts
+import { parse as parsePath } from "path";
+import kleur9 from "kleur";
+
 // src/dry-run.ts
-import { promises as fs3, createReadStream } from "fs";
+import { promises as fs4, createReadStream } from "fs";
 import Papa from "papaparse";
-import kleur from "kleur";
+import kleur8 from "kleur";
 async function readSample(file, sampleLimit) {
   const lower = file.toLowerCase();
   if (lower.endsWith(".json")) {
-    const text = await fs3.readFile(file, "utf8");
+    const text = await fs4.readFile(file, "utf8");
     const arr = JSON.parse(text);
     if (!Array.isArray(arr)) throw new Error("JSON file must be an array of row objects");
     const out = [];
@@ -1346,13 +2792,13 @@ async function readSample(file, sampleLimit) {
     }
     return out;
   }
-  return await new Promise((resolve, reject) => {
+  return await new Promise((resolve2, reject) => {
     const out = [];
     let done = false;
-    const finish = () => {
+    const finish2 = () => {
       if (done) return;
       done = true;
-      resolve(out);
+      resolve2(out);
     };
     const stream = createReadStream(file);
     const parseStream = Papa.parse(Papa.NODE_STREAM_INPUT, {
@@ -1370,10 +2816,10 @@ async function readSample(file, sampleLimit) {
       out.push(o);
       if (out.length >= sampleLimit) {
         stream.destroy();
-        finish();
+        finish2();
       }
     });
-    parseStream.on("end", finish);
+    parseStream.on("end", finish2);
     stream.pipe(parseStream);
   });
 }
@@ -1391,7 +2837,7 @@ async function buildDryRunReport(file, opts) {
     };
   }
   if (!(opts.nameColumn in rows[0])) {
-    throw new Error(`name column "${opts.nameColumn}" not present in file header`);
+    throw new CliError(`name column "${opts.nameColumn}" not present in file header`, EXIT.usage);
   }
   let nullNameCount = 0;
   let qualifierFlagCount = 0;
@@ -1431,352 +2877,255 @@ async function buildDryRunReport(file, opts) {
     idTypeDetection
   };
 }
-function printDryRunReport(report) {
-  console.log();
-  console.log(kleur.bold("Dry-run preview"));
-  console.log(
-    `  Read ${kleur.cyan(report.rowsRead)} rows \xB7 ${kleur.yellow(report.nullNameCount)} with no usable name \xB7 ${kleur.yellow(report.qualifierFlagCount)} with qualifier flags`
+function printDryRunReport(report, log) {
+  log("");
+  log(kleur8.bold("Dry-run preview"));
+  log(
+    `  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);
-    console.log(
-      `  ID-column detection: ${kleur.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) {
-      console.log(`  Minority examples:`);
+      log(`  Minority examples:`);
       for (const m of d.minorityExamples) {
-        console.log(
-          `    row ${m.rowIndex + 1}: ${kleur.gray(m.value)} \u2192 ${kleur.dim(m.type)}`
-        );
+        log(`    row ${m.rowIndex + 1}: ${kleur8.gray(m.value)} \u2192 ${kleur8.dim(m.type)}`);
       }
     }
   }
-  console.log();
-  console.log(kleur.bold("First rows after normalization:"));
-  console.log(
-    `  ${"#".padStart(4)}  ${"input".padEnd(36)}  ${"normalized".padEnd(36)}  flags`
-  );
+  log("");
+  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);
     const inp = trunc(r.input ?? "\u2205", 36).padEnd(36);
     const norm = trunc(r.normalized ?? "\u2205", 36).padEnd(36);
-    console.log(`  ${idx}  ${inp}  ${norm}  ${r.flags.join(" ") || ""}`);
+    log(`  ${idx}  ${inp}  ${norm}  ${r.flags.join(" ") || ""}`);
   }
-  console.log();
+  log("");
 }
 function trunc(s, n) {
   if (s.length <= n) return s;
   return s.slice(0, n - 1) + "\u2026";
 }
 
-// src/index.ts
-var { version } = createRequire(import.meta.url)("../package.json");
-var program = new Command();
-program.name("planttaxomatcher").description("PlantTaxoMatcher CLI").version(version);
-program.command("login").description("Save a personal token + server URL").option(
-  "--token <token>",
-  "Personal token (ptm_...). Avoid on shared hosts: it is visible in shell history and the process list. Prefer --token-stdin or the PLANTTAXOMATCHER_TOKEN env var."
-).option(
-  "--token-stdin",
-  "Read the token from stdin instead of argv (e.g. `cat token.txt | planttaxomatcher login --token-stdin`).",
-  false
-).option("--server <url>", "API server base URL", "http://localhost:4000").option(
-  "--insecure",
-  "Allow sending the token over cleartext http to a non-loopback server (NOT recommended).",
-  false
-).action(async (opts) => {
-  assertServerTransport(opts.server, !!opts.insecure);
-  const token = await resolveLoginToken(opts);
-  if (!tokenStringSchema.safeParse(token).success) {
-    throw new Error("malformed token \u2014 expected ptm_<12 chars>_<32 chars>");
-  }
-  await writeCredentials({ token, server: opts.server });
-  console.log(kleur2.green("\u2713"), `Logged in to ${opts.server}`);
-});
-program.command("logout").description("Clear saved credentials").action(async () => {
-  await clearCredentials();
-  console.log(kleur2.green("\u2713"), "Logged out");
-});
-program.command("whoami").description("Show current user").action(async () => {
-  const creds = await requireCredentials();
-  const me = await apiClient.me(creds);
-  console.log(`${me.displayName}  team=${me.teamId}  scopes=${me.scopes.join(",")}`);
-  console.log(`server=${creds.server}`);
-});
-program.command("list").description("List recent jobs").action(async () => {
-  const creds = await requireCredentials();
-  const jobs = await apiClient.listJobs(creds);
-  if (jobs.length === 0) {
-    console.log(kleur2.gray("No jobs."));
-    return;
-  }
-  for (const j of jobs) {
-    console.log(
-      `${j.id}  ${j.status.padEnd(10)}  ${String(j.matchedRows).padStart(6)}/${String(j.totalRows).padStart(6)} matched`
-    );
-  }
-});
-program.command("status <jobId>").description("Show job status snapshot").action(async (jobId) => {
-  const creds = await requireCredentials();
-  const job = await apiClient.getJob(creds, jobId);
-  console.log(JSON.stringify(job, null, 2));
-});
-program.command("submit <files...>").description(
-  'Submit one or more CSV/JSON files for matching. Accepts shell-expanded paths or quoted glob patterns (e.g. "data/*.csv"). Each file becomes its own job; the file name (without extension) is used as the job name.'
-).option(
-  "--name <label>",
-  "Job name override (single file only; ignored when multiple files match \u2014 the file name is used)"
-).requiredOption("--name-column <name>", "Column holding the scientific name").option("--id-column <name>", "Column holding a known ID").option("--family-column <name>", "Column holding family").option("--genus-column <name>", "Column holding genus").option("--rank-column <name>", "Column holding rank").option("--author-column <name>", "Column holding authorship").option("--filter-column <name>", "Only process rows where this column matches --filter-value; others are skipped").option("--filter-value <value>", "Value the --filter-column must equal (trimmed, case-insensitive)").option("--author-mode <mode>", "ignore|prefer|strict", "prefer").option("--parallel <n>", "Per-job parallelism", "4").option("--review-mode <mode>", "off|recommended|strict", "recommended").option(
-  "--species-level",
-  "Roll infraspecific accepted taxa (varieties, subspecies, forms) up to their species, so every output row sits at species level",
-  false
-).option(
-  "--ignore-author",
-  "Accept a unique canonical name match whose author couldn't be confirmed instead of sending it to review (an author that CONFLICTS with the matched taxon still reviews)",
-  false
-).option("--keep-infraspecific", "Deprecated \u2014 now the default; has no effect", false).option("--allow-llm", "Allow Layer 7 LLM cascade (breaks ties between competing matches)", false).option("--llm-cap-cents <cents>", "Max LLM spend in cents", "500").option(
-  "--referential <version>",
-  "WCVP snapshot version to match against (default: your team's configured default snapshot, else the newest import)"
-).option("--no-watch", "Do not stream progress after submit").option("--dry-run", "Preview locally (normalize first rows + detect ID type) and confirm before uploading", false).option("--dry-run-rows <n>", "Number of rows to show in the dry-run preview table (default 10)", "10").action(async (files, opts) => {
-  const creds = await requireCredentials();
-  const inputs = await expandInputs(files);
-  if (inputs.length === 0) throw new Error("no input files");
-  if (opts.name && inputs.length > 1) {
-    console.log(kleur2.yellow("!"), "--name ignored for multi-file submit; using each file name as the job name");
-  }
-  if (opts.keepInfraspecific) {
-    console.log(
-      kleur2.yellow("!"),
-      "--keep-infraspecific is deprecated and does nothing \u2014 infraspecific taxa are kept by default. Pass --species-level to roll them up to the species."
-    );
-  }
-  if (inputs.length > 1) {
-    console.log(kleur2.cyan("\u2192"), `${inputs.length} files matched:`);
-    for (const f of inputs) console.log(kleur2.gray(`    ${f}`));
-  }
-  if (opts.dryRun) {
-    const idColumn = opts.idColumn ? String(opts.idColumn) : null;
-    const previewRows = Number(opts.dryRunRows ?? 10);
-    for (const file of inputs) {
-      if (inputs.length > 1) console.log(kleur2.bold(`
-${file}`));
-      const report = await buildDryRunReport(file, {
-        nameColumn: String(opts.nameColumn),
-        idColumn,
-        previewRows: Number.isFinite(previewRows) ? previewRows : 10,
-        sampleLimit: 1e3
+// src/inputs.ts
+import { promises as fs5 } from "fs";
+var GLOB_MAGIC = /[*?[\]{}!()]/;
+async function expandInputs(patterns) {
+  const files = /* @__PURE__ */ new Set();
+  for (const pattern of patterns) {
+    if (GLOB_MAGIC.test(pattern)) {
+      let matched = false;
+      for await (const file of fs5.glob(pattern)) {
+        files.add(file);
+        matched = true;
+      }
+      if (!matched) throw new CliError(`no files matched: ${pattern}`, EXIT.usage);
+    } else {
+      await fs5.access(pattern).catch(() => {
+        throw new CliError(`file not found: ${pattern}`, EXIT.usage);
       });
-      printDryRunReport(report);
-    }
-    const proceed = await confirm({
-      message: inputs.length > 1 ? `Proceed with upload of ${inputs.length} files?` : "Proceed with upload?",
-      default: true
-    });
-    if (!proceed) {
-      console.log(kleur2.gray("Aborted."));
-      return;
+      files.add(pattern);
     }
   }
+  return [...files].sort();
+}
+
+// src/job-config.ts
+import "zod";
+function buildJobConfig(opts) {
   const config = {
-    nameColumn: String(opts.nameColumn),
-    idColumn: opts.idColumn ? String(opts.idColumn) : null,
-    familyColumn: opts.familyColumn ? String(opts.familyColumn) : null,
-    genusColumn: opts.genusColumn ? String(opts.genusColumn) : null,
-    rankColumn: opts.rankColumn ? String(opts.rankColumn) : null,
-    authorColumn: opts.authorColumn ? String(opts.authorColumn) : null,
-    filterColumn: opts.filterColumn ? String(opts.filterColumn) : null,
-    filterValue: opts.filterValue != null ? String(opts.filterValue) : null,
-    authorMode: String(opts.authorMode ?? "prefer"),
+    nameColumn: opts.nameColumn,
+    idColumn: opts.idColumn ?? null,
+    idType: opts.idType,
+    familyColumn: opts.familyColumn ?? null,
+    genusColumn: opts.genusColumn ?? null,
+    rankColumn: opts.rankColumn ?? null,
+    authorColumn: opts.authorColumn ?? null,
+    filterColumn: opts.filterColumn ?? null,
+    filterValue: opts.filterValue ?? null,
+    authorMode: opts.authorMode,
     matchAuthors: true,
-    parallelism: Number(opts.parallel ?? 4),
+    parallelism: parseIntegerFlag(opts.parallel, "--parallel"),
     allowFuzzy: true,
-    allowLlm: !!opts.allowLlm,
-    llmCostCapCents: Number(opts.llmCapCents ?? 500),
-    reviewMode: String(opts.reviewMode ?? "recommended"),
-    // Opt-in: by default an infraspecific accepted taxon is kept at the
-    // rank it resolved to, not rolled up to its species.
-    speciesLevelAcceptedOnly: !!opts.speciesLevel,
-    // Opt-in: an unconfirmed author still routes the match to review
-    // unless the caller declares the author unimportant.
-    acceptUnconfirmedAuthor: !!opts.ignoreAuthor,
+    allowLlm: opts.allowLlm,
+    llmCostCapCents: parseIntegerFlag(opts.llmCapCents, "--llm-cap-cents"),
+    reviewMode: opts.reviewMode,
+    speciesLevelAcceptedOnly: opts.speciesLevel,
+    acceptUnconfirmedAuthor: opts.ignoreAuthor,
     exportConfirmedOnly: false,
-    forceReviewFamilies: [],
-    ...opts.referential ? { referentialVersion: String(opts.referential) } : {}
+    referential: parseBackbone(opts.backbone),
+    ...opts.referential ? { referentialVersion: opts.referential } : {},
+    ...opts.area?.trim() ? { area: opts.area.trim() } : {}
   };
-  const submitted = [];
-  for (const file of inputs) {
-    const jobName = inputs.length === 1 && opts.name ? String(opts.name) : parsePath(file).name;
-    console.log(kleur2.cyan("\u2192"), `Uploading ${file} \u2026`);
-    const job = await apiClient.submitJob(creds, file, config, jobName || null);
-    console.log(kleur2.green("\u2713"), `Job created: ${job.id}  ${kleur2.gray(jobName)}`);
-    console.log(`  rows=${job.totalRows}  uniqueQueries=${job.uniqueQueries}`);
-    submitted.push({ id: job.id, file });
-  }
-  if (opts.watch === false) return;
-  for (const s of submitted) {
-    if (submitted.length > 1) console.log(kleur2.bold(`
-[${s.file}] ${s.id}`));
-    await streamJob(creds, s.id);
-  }
-});
-program.command("watch <jobId>").description("Stream NDJSON progress for a job").action(async (jobId) => {
-  const creds = await requireCredentials();
-  await streamJob(creds, jobId);
-});
-program.command("pause <jobId>").description("Pause a running job (worker stops between match queries)").action(async (jobId) => {
-  const creds = await requireCredentials();
-  const job = await apiClient.pauseJob(creds, jobId);
-  console.log(kleur2.green("\u2713"), `paused: ${job.id} (status=${job.status})`);
-});
-program.command("resume <jobId>").description("Resume a paused job (re-enqueues the match stage)").action(async (jobId) => {
-  const creds = await requireCredentials();
-  const job = await apiClient.resumeJob(creds, jobId);
-  console.log(kleur2.green("\u2713"), `resumed: ${job.id} (status=${job.status})`);
-});
-program.command("cancel <jobId>").description("Cancel a job. Already-matched rows are kept; pending queries stop.").action(async (jobId) => {
-  const creds = await requireCredentials();
-  const job = await apiClient.cancelJob(creds, jobId);
-  console.log(kleur2.green("\u2713"), `cancelled: ${job.id} (status=${job.status})`);
-});
-program.command("download <jobId>").description("Download a job export (CSV, JSON, or NDJSON; optionally bundled with NOTICE.md)").option("--format <fmt>", "csv | xlsx | json | ndjson", "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: comma | semicolon | tab | pipe (csv format only)", "comma").option("--bundle", "wrap in a ZIP with NOTICE.md citing the WCVP snapshot + 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 to append 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("--output <path>", "write to this path; default is the server-provided filename in CWD").action(async (jobId, opts) => {
-  const creds = await requireCredentials();
-  if (opts.listColumns) {
-    const cat = await apiClient.downloadColumns(creds, jobId);
-    console.log(kleur2.bold("Result columns (--columns):"));
-    for (const r of cat.result) console.log(`  ${r.key}  ${kleur2.gray(`(${r.group})`)}`);
-    if (cat.original.length > 0) {
-      console.log(kleur2.bold("\nYour upload columns (--columns):"));
-      for (const k of cat.original) console.log(`  ${k}`);
-    }
-    console.log(kleur2.bold("\nWCVP extra fields (--wcvp-extra):"));
-    for (const f of cat.wcvpExtra) console.log(`  ${f.key}  ${kleur2.gray(`(${f.group})`)}`);
-    return;
-  }
-  const format = opts.format ?? "csv";
-  if (format !== "csv" && format !== "json" && format !== "ndjson" && format !== "xlsx") {
-    throw new Error(`--format must be csv, xlsx, json or ndjson (got ${String(format)})`);
-  }
-  const confirmedOnly = !!opts.confirmedOnly;
-  const dedupe = !!opts.dedupe;
-  const bundle = !!opts.bundle;
-  const delimiter = String(opts.delimiter ?? "comma");
-  if (!["comma", "semicolon", "tab", "pipe"].includes(delimiter)) {
-    throw new Error(`--delimiter must be comma, semicolon, tab or pipe (got ${delimiter})`);
-  }
-  const { filename, body } = await apiClient.downloadJob(creds, jobId, {
-    format,
-    confirmedOnly,
-    dedupe,
-    bundle,
-    ...format === "csv" && delimiter !== "comma" ? { delimiter } : {},
-    ...opts.columns ? { columns: String(opts.columns) } : {},
-    ...opts.wcvpExtra ? { wcvpExtra: String(opts.wcvpExtra) } : {}
-  });
-  const outPath = opts.output ?? filename;
-  const { writeFile } = await import("fs/promises");
-  await writeFile(outPath, body);
-  console.log(kleur2.green("\u2713"), `wrote ${body.length} bytes to ${outPath}`);
-});
-program.parseAsync(process.argv).catch((err) => {
-  const msg = err instanceof Error ? err.message : String(err);
-  console.error(kleur2.red("error:"), msg);
-  process.exit(1);
-});
-function assertServerTransport(server, insecure) {
-  let u;
-  try {
-    u = new URL(server);
-  } catch {
-    throw new Error(`invalid --server URL: ${server}`);
+  const checked = jobConfigSchema.safeParse(config);
+  if (!checked.success) {
+    const issue = checked.error.issues[0];
+    const field = issue?.path.join(".") ?? "config";
+    throw new CliError(`invalid ${field}: ${issue?.message ?? "rejected"}`, EXIT.usage);
   }
-  if (u.protocol === "https:") return;
-  if (u.protocol !== "http:") {
-    throw new Error(`--server must use http or https (got ${u.protocol})`);
-  }
-  const host = u.hostname;
-  const isLoopback = host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]" || host.endsWith(".localhost");
-  if (!isLoopback && !insecure) {
-    throw new Error(
-      `refusing to send a token in cleartext to ${u.host}. Use an https URL, or pass --insecure to override (NOT recommended).`
-    );
+  return config;
+}
+
+// src/commands/submit.ts
+function summarize(submitted, finals, creds) {
+  return submitted.map(({ file, job }) => ({
+    id: job.id,
+    name: job.name,
+    file,
+    status: finals.find((f) => f.id === job.id)?.status ?? job.status,
+    totalRows: job.totalRows,
+    uniqueQueries: job.uniqueQueries,
+    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;
 }
-async function readStdinLine() {
-  const chunks = [];
-  for await (const chunk of process.stdin) chunks.push(chunk);
-  return Buffer.concat(chunks).toString("utf8").trim();
+function jobNameFor(file, fileCount, name) {
+  return fileCount === 1 && name?.trim() ? name.trim() : parsePath(file).name;
 }
-async function resolveLoginToken(opts) {
-  if (opts.tokenStdin) {
-    const t = await readStdinLine();
-    if (!t) throw new Error("--token-stdin was set but stdin was empty");
-    return t;
+async function confirmDryRun(deps2, out, files, opts) {
+  const previewRows = Number(opts.dryRunRows);
+  for (const file of files) {
+    if (files.length > 1) out.info(kleur9.bold(`
+${file}`));
+    const report = await buildDryRunReport(file, {
+      nameColumn: opts.nameColumn,
+      idColumn: opts.idColumn ?? null,
+      previewRows: Number.isFinite(previewRows) ? previewRows : 10,
+      sampleLimit: 1e3
+    });
+    printDryRunReport(report, out.info);
   }
-  if (opts.token) return opts.token.trim();
-  const env = process.env.PLANTTAXOMATCHER_TOKEN;
-  if (env && env.trim()) return env.trim();
-  if (!process.stdin.isTTY) {
-    throw new Error("no token provided. Pass --token-stdin, set PLANTTAXOMATCHER_TOKEN, or run interactively.");
+  if (opts.yes) return true;
+  if (!deps2.stdinIsTTY) {
+    throw new CliError("--dry-run needs a confirmation", EXIT.usage, "Pass --yes to upload after the preview.");
   }
-  const entered = await password({ message: "Personal token (ptm_...)", mask: true });
-  return entered.trim();
+  const message = files.length > 1 ? `Proceed with upload of ${files.length} files?` : "Proceed with upload?";
+  return deps2.promptConfirm(message);
 }
-var GLOB_MAGIC = /[*?[\]{}!()]/;
-async function expandInputs(patterns) {
-  const out = /* @__PURE__ */ new Set();
-  for (const p of patterns) {
-    if (GLOB_MAGIC.test(p)) {
-      let matched = false;
-      for await (const m of fs4.glob(p)) {
-        out.add(m);
-        matched = true;
-      }
-      if (!matched) throw new Error(`no files matched: ${p}`);
-    } else {
-      await fs4.access(p).catch(() => {
-        throw new Error(`file not found: ${p}`);
-      });
-      out.add(p);
+function registerSubmitCommand(program, deps2) {
+  program.command("submit <files...>").description(
+    'Submit CSV/XLSX/JSON files for matching, one job per file (named after the file). Accepts shell-expanded paths or quoted globs such as "data/*.csv". Follows progress until the jobs stop unless --no-watch; exits 4 if one fails, 5 if one is paused.'
+  ).option("--name <label>", "Job name (single file only; with several files each job is named after its file)").requiredOption("--name-column <name>", "Column holding the scientific name").option("--id-column <name>", "Column holding a known ID").option("--family-column <name>", "Column holding family").option("--genus-column <name>", "Column holding genus").option("--rank-column <name>", "Column holding rank").option("--author-column <name>", "Column holding authorship").option(
+    "--filter-column <name>",
+    "Only process rows where this column matches --filter-value; others are skipped"
+  ).option("--filter-value <value>", "Value the --filter-column must equal (trimmed, case-insensitive)").option("--author-mode <mode>", "ignore|prefer|strict", "prefer").option("--parallel <n>", "Per-job parallelism (1-10)", "4").option("--review-mode <mode>", "off|recommended|strict", "recommended").option(
+    "--id-type <type>",
+    "What --id-column holds: auto (backbone id, else GBIF key for bare integers), wcvp, gbif",
+    "auto"
+  ).option(
+    "--species-level",
+    "Roll infraspecific accepted taxa (varieties, subspecies, forms) up to their species",
+    false
+  ).option(
+    "--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("--backbone <name>", "Backbone to match against: wcvp or wfo", "wcvp").option(
+    "--referential <version>",
+    "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");
+    if (opts.keepInfraspecific) {
+      out.warn(
+        "--keep-infraspecific is deprecated and does nothing \u2014 pass --species-level to roll up to the species"
+      );
     }
-  }
-  return [...out].sort();
-}
-async function streamJob(creds, jobId) {
-  console.log(kleur2.cyan("\u2192"), `Streaming progress for ${jobId} \u2026`);
-  let lastLineWidth = 0;
-  for await (const evt of apiClient.streamJob(creds, jobId)) {
-    const t = String(evt.type ?? "");
-    if (t === "heartbeat") continue;
-    if (t === "status") {
-      const status = String(evt.status ?? "");
-      console.log(kleur2.gray("\u2022"), status);
-      if (status === "completed") {
-        console.log(kleur2.green("\u2713"), "completed");
-        return;
+    if (files.length > 1) {
+      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(kleur9.gray("Aborted."));
+      return;
+    }
+    const submitted = [];
+    const finals = [];
+    try {
+      for (const file of files) {
+        const name = jobNameFor(file, files.length, opts.name);
+        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}  ${kleur9.gray(name)}`);
+        out.info(`  rows=${job.totalRows}  uniqueQueries=${job.uniqueQueries}`);
+        submitted.push({ file, job });
       }
-      if (status === "failed" || status === "cancelled") {
-        console.error(kleur2.red(status));
-        return;
+      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(kleur9.bold(`
+[${file}] ${job.id}`));
+          finals.push({ id: job.id, status: await watchJob(deps2.api, watchOut, creds, job.id) });
+        }
       }
-    } else if (t === "progress") {
-      const p = evt.processedQueries ?? evt.processedRows ?? 0;
-      const total = evt.totalQueries ?? evt.totalRows ?? 0;
-      const phase = p === 0 && typeof evt.phase === "string" ? ` (${evt.phase}\u2026)` : "";
-      const line = `  progress: ${p}/${total}${phase}`;
-      process.stdout.write(`\r${line.padEnd(lastLineWidth)}`);
-      lastLineWidth = line.length;
-    } else if (t === "completed") {
-      process.stdout.write("\n");
-      console.log(kleur2.green("\u2713"), "completed");
-      return;
-    } else if (t === "error") {
-      process.stdout.write("\n");
-      console.error(kleur2.red("error:"), evt.message);
-      return;
+    } finally {
+      if (opts.json) out.data(summarize(submitted, finals, creds));
     }
+    const failure = watchOutcomeError(finals);
+    if (failure) throw failure;
+  });
+}
+
+// src/program.ts
+var EXIT_CODES_HELP = `
+Exit codes:
+  0  success
+  1  error (API or network failure)
+  2  usage error (bad flag or argument)
+  3  not signed in, or the token was rejected
+  4  a watched job ended failed or cancelled
+  5  a watched job was paused (resume it, then watch again)
+
+Environment:
+  PLANTTAXOMATCHER_TOKEN   token to use instead of the saved login
+  PLANTTAXOMATCHER_SERVER  its server (default: the public server); alone, it
+                           must match the saved login's server`;
+function buildProgram(deps2, version2) {
+  const program = new Command().name("planttaxomatcher").description("Reconcile plant names against WCVP with the PlantTaxoMatcher API").version(version2).addHelpText("after", EXIT_CODES_HELP).exitOverride().configureOutput({
+    writeOut: (text) => deps2.stdout.write(text),
+    writeErr: (text) => deps2.stderr.write(text)
+  });
+  registerAuthCommands(program, deps2);
+  registerJobCommands(program, deps2);
+  registerSubmitCommand(program, deps2);
+  registerCatalogCommands(program, deps2);
+  registerDownloadCommand(program, deps2);
+  registerSkillsCommands(program, deps2, version2);
+  return program;
+}
+async function runCli(argv, deps2, version2) {
+  try {
+    await buildProgram(deps2, version2).parseAsync(argv, { from: "user" });
+    return 0;
+  } catch (err) {
+    const { exitCode, message, hint } = describeError(err);
+    if (message) deps2.stderr.write(`${kleur10.red("error:")} ${message}
+`);
+    if (hint) deps2.stderr.write(`${kleur10.gray(hint)}
+`);
+    return exitCode;
   }
 }
+
+// src/index.ts
+var { version } = createRequire(import.meta.url)("../package.json");
+var deps = defaultDeps();
+await refreshSkillIfOutdated(skillPaths(deps.home, deps.env), deps.skillSource, version);
+process.exitCode = await runCli(process.argv.slice(2), deps, version);