docs(skills): harden lingo skill after Codex review passes

Corrects claims against source (failure results omit span/confidence;
issues[].span is optional; LOCALE_NOT_LOADED only on an explicit unloaded
locale), switches the AI SDK snippet to a provider-neutral model + injected
now, qualifies the two-way and [CODE] promises, adds a timezone/applyZone
caveat, enriches the description and entry table (describe/schema), and fixes
a frontmatter YAML parse break (colon in the description value).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Aymericr

skills/lingo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lingo
-description: Parse natural-language quantities, units, dates, and ranges ("5'11\"", "1.5 cups", "72 in to cm", "three days ago", "between 5 and 10 kg", "it's hot") into canonical, validated values — and humanize them back. Use when building form inputs that accept measurements/units/dates, making LLM tool calls safe at the boundary (AI SDK / MCP), or converting and validating any human- or model-entered measurement string. Zero-dependency TypeScript, two-way (round-trips), deterministic.
+description: Parse natural-language quantities, units, dates, and ranges ("5'11\"", "1.5 cups", "72 in to cm", "three days ago", "between 5 and 10 kg", "it's hot") into canonical, validated values with issue codes and spans — and humanize them back. Use when a form input, LLM tool schema, MCP handler, or import pipeline takes free-text measurements/units/dates. Covers Standard Schema fields (quantityField/dateField/lingoObject) for the AI SDK and MCP, the headless <lingo-input>, unit conversion, and format/humanize round-trips. Zero-dependency TypeScript, deterministic.
 metadata:
   author: pascalorg
   version: "1.0.0"
@@ -11,14 +11,20 @@ metadata:
 [`@pascal-app/lingo`](https://github.com/pascalorg/lingo) is a zero-dependency
 TypeScript library that turns the strings people type and models emit —
 `180cm`, `5ft 11`, `1.5 cups`, `90 min`, `next friday`, `1,5 kg`, `"5'11\""`,
-`"twenty-five kg"`, `"3pm EST"` — into canonical, validated values (one number
-in one unit, one ISO date), converts and range-checks them, then humanizes the
-value back. Every result carries a stable issue code and a `[start, end)` span
-into the original input. It's **two-way**: whatever `format()`/`humanize*()`
-emits re-parses to the same value.
+`"twenty-five kg"`, `"3pm EST"` — into canonical, validated values: a quantity,
+range, conversion, date, date-range, or duration in one canonical unit. It
+converts, range-checks, and humanizes the value back. Every successful result
+carries a `[start, end)` span into the original input plus any issues with stable
+codes. It's **two-way**: default `format()`/`humanize*()` output re-parses to the
+same value (display-only options like `localizedUnits` are outside the guarantee).
 
 Tagline: **Make forms easier, LLM tools safer.**
 
+> **Source of truth:** for anything past the patterns below — the full API, every
+> unit and kind, all issue codes, and per-input examples — open
+> `node_modules/@pascal-app/lingo/llms.txt` or
+> [`lingo.pascal.app/llms.txt`](https://lingo.pascal.app/llms.txt).
+
 ## When to use this skill
 
 Reach for lingo whenever a value arrives as free text and needs to become a
@@ -35,7 +41,8 @@ trustworthy stored value:
 - **Anything that converts** (`72 in to cm`), **ranges** (`between 5 and 10 kg`,
   `under 10 minutes`, `10 ± 0.5 mm`), or **relative dates** (`three days ago`).
 
-Do **not** reach for it for plain already-canonical numbers, or for currency
+Do **not** reach for it for already-canonical typed numbers, generic calendar
+scheduling or timezone-database work, arbitrary NLP extraction, or currency
 conversion needing live FX (lingo returns `RATE_REQUIRED` — you inject rates).
 
 ## Install & entry points
@@ -58,6 +65,8 @@ Import only what you need; each subpath is tree-shakeable.
 | `@pascal-app/lingo/complete` | ranked autocomplete `completions()` |
 | `@pascal-app/lingo/locales/{en,en-gb,es,fr,pt,zh,ja}` | opt-in parsing language packs |
 | `@pascal-app/lingo/catalog` | query units/kinds/currencies |
+| `@pascal-app/lingo/describe` | rich human/agent-readable views of a value or result |
+| `@pascal-app/lingo/schema` | JSON Schema / OpenAPI generated from the v3 wire types |
 
 ## Pattern 1 — parse, validate, convert (core)
 
@@ -72,10 +81,12 @@ parseRange("between 5 and 10 kg", { kind: "mass" }) // range 5..10 kg
 ```
 
 `lingo(text, opts?)` returns a versioned union on `.type`
-(`quantity | range | conversion | number | failure`), serialized as flat v3 JSON
-(`{ schemaVersion: 3, ok, type, ...value, text, span, issues, confidence }`).
-Always branch on `.ok` / `.type` before reading the value, and surface
-`.issues[]` (each has `code`, `severity`, `message`, `span`) to the user.
+(`quantity | range | conversion | number | failure`), serialized as flat v3 JSON.
+**Branch on `.ok` first.** Successes carry the value fields plus `span` and
+`confidence`; a failure is `{ schemaVersion: 3, ok: false, type: "failure", text,
+issues, candidate? }` — with no `span`/`confidence`. Surface `.issues[]` (each has
+`code`, `severity`, `message`, and usually a `span`; field-level bound issues from
+`/ai` may omit it) to the user.
 
 Pass context to disambiguate: `{ kind, unit, currency, locale, system, strictness }`.
 `strictness: "confirm"` turns each assumption (typo fix, ambiguous number) into a
@@ -104,20 +115,23 @@ element: `defineLingoInput()` then `<lingo-input kind="length" unit="m" name="he
 
 The fields expose a **`string`** input JSON Schema (models are better at emitting
 `"5'11\""` than `1.8034`) and hand your handler the **canonical** value. Risky
-readings fail loudly with `[CODE] … Did you mean …?` messages a model can
-self-correct from in one round trip.
+readings fail loudly: parser failures are `[CODE]`-prefixed and carry a
+`candidate` when one exists (so a model can self-correct in one round trip);
+schema-shape errors surface as plain Standard Schema messages.
 
 ```ts
 import { tool, generateText } from "ai"
 import { lingoObject, quantityField, dateField } from "@pascal-app/lingo/ai"
 
+// `now` must be injected per request (fixed here for reproducibility) — not Date.now()
+const now = new Date("2026-07-08T12:00:00Z")
 const shipment = lingoObject({
   weight: quantityField({ kind: "mass", unit: "kg", min: 0, max: 500 }),
-  deliverBy: dateField({ now: new Date() }),   // relative dates REQUIRE now
+  deliverBy: dateField({ now }),   // relative dates REQUIRE now
 })
 
 await generateText({
-  model: "claude-opus-4-8",
+  model,   // your AI SDK model, e.g. "anthropic/claude-opus-4-8" via the gateway
   tools: { create_shipment: tool({ inputSchema: shipment, execute: run }) },
 })
 ```
@@ -131,19 +145,23 @@ return `{ isError: true }` with `[CODE]`-prefixed text.
 1. **Keep measurements as strings in tool/form schemas.** Let lingo convert,
    validate, surface spans, and handle ambiguity — don't ask the model or user
    for a float.
-2. **Store the canonical value, display the humanized one.** `format()` /
-   `humanizeDate()` round-trip back to the same value (`1.9999 m` → `6′7″`,
-   never `5′12″`).
+2. **Store the canonical value, display the humanized one.** Default `format()` /
+   `humanizeDate()` output round-trips back to the same value (`1.9999 m` → `6′7″`,
+   never `5′12″`); display-only options like `localizedUnits` don't round-trip.
 3. **Always pass an explicit `now`** to `parseDate`/`dateField` for relative
    dates — never rely on `Date.now()`, so a queued or retried call can't drift
    across midnight. Reference-dependent input without `now` → `NOW_REQUIRED`.
+   Timezones are detected but kept as civil time unless you pass `applyZone: true`;
+   `/ai` `dateField` rejects an ignored zone (`TZ_IGNORED`) by default.
 4. **No silent guesses.** Ambiguous input returns a deterministic best reading
    plus ranked `alternatives`/`candidate` and a warning code — show it, or use
    `strictness: "confirm"` / `"strict"` to force confirmation.
 5. **Currency conversion needs injected rates** — `5 EUR to USD` returns
    `RATE_REQUIRED`; call `convertCurrency` with your own rates.
-6. **Locale packs are opt-in.** English is built in; for other languages
-   `createLingo({ locales: [es, fr, …] })` or you'll get `LOCALE_NOT_LOADED`.
+6. **Locale packs are opt-in.** English is built in; load others with
+   `createLingo({ locales: [es, fr, …] })`. Omitting `locale` auto-detects among
+   loaded packs plus English; requesting an explicit *unloaded* `locale` →
+   `LOCALE_NOT_LOADED`.
 
 Common issue codes to handle: `UNKNOWN_UNIT`, `KIND_MISMATCH`, `UNIT_REQUIRED`,
 `AMBIGUOUS_NUMBER`, `AMBIGUOUS_UNIT`, `TYPO_CORRECTED`, `RANGE_MIN`/`RANGE_MAX`,