{
  "schema_version": "v1",
  "name": "AIFreight Operating System (FreightOS · BondOS · LogisticsOS · AI Clerk)",
  "description": "AI-native UK/SME freight-forwarding, customs-warehousing and fleet operating system. One consignment object flows through four engines: FreightOS (instant multimodal quote with live UK Trade Tariff duty, import VAT, origin-aware preferential duty, multi-currency valuation, real-geography route optimisation, public-index rate bands and OFSI/OFAC/UN/EU sanctions screening); BondOS (customs-warehouse duty + import VAT suspension, stock record, partial draw-down, CCG guarantee headroom, working-capital released); LogisticsOS (O-licence van-fleet job costing, driver-hours + vehicle compliance, load utilisation, dispatch clearance); the AI Clerk (every document at every stage — import, bond, delivery — pre-filled and validated); plus the FMCG funded-cycle layer (Vaping Products Duty + Soft Drinks Industry Levy + the supplier-terms/PVA/deferment/bond/invoice-finance cash-conversion cycle). Decision support — figures are indicative, firmed at booking; regulated/irreversible steps stop at a human gate.",
  "contact": "hello@aifreight.co.uk",
  "base_url": "https://aifreight.uk",
  "human_surfaces": {
    "/api/reconcile": "/bond/reconcile/",
    "/api/company-check": "/verify/",
    "/api/cbam": "/tools/cbam/",
    "/api/origin": "/tools/origin/",
    "/api/demurrage": "/tools/demurrage/",
    "/api/searoute": "/tools/sea-route/",
    "/api/quote": "/quote/",
    "/api/bonded-relief": "/bonded/",
    "/api/control-tower": "/control-tower/"
  },
  "legal": "Not customs advice. The declarant/operator stays accountable. Freight is indicative; official HMRC customs exchange rates + carrier rates apply at declaration/booking.",
  "tools": [
    {
      "name": "freight_copilot",
      "description": "ONE call, the whole decision. Orchestrates quote (landed cost + route) → OFSI/OFAC/UN/EU party screening → bonded-regime comparison → machine-declaration readiness, and fuses them into a sourced dossier: headline, compliance posture, bond recommendation, and an ORDERED next-action list with every regulated step human-gated. The AI-native orchestration layer point tools lack — start here for \"what do I do with this shipment?\".",
      "method": "POST",
      "path": "/api/copilot",
      "input_schema": {
        "type": "object",
        "required": [
          "goods_value",
          "weight_kg"
        ],
        "properties": {
          "goods_value": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "weight_kg": {
            "type": "number"
          },
          "commodity_code": {
            "type": "string",
            "description": "HS/commodity code — use classify_commodity if unknown."
          },
          "origin_country": {
            "type": "string"
          },
          "consignor_name": {
            "type": "string",
            "description": "Screened against OFSI/OFAC/UN/EU."
          },
          "consignee_name": {
            "type": "string",
            "description": "Screened against OFSI/OFAC/UN/EU."
          },
          "eori": {
            "type": "string"
          },
          "incoterm": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "to_warehouse": {
            "type": "boolean",
            "description": "Bonded entry vs home-use import."
          },
          "dwell_days": {
            "type": "number"
          }
        }
      },
      "returns": "dossier: { headline, landed, duty, compliance, bond, next_actions[], blockers[], human_gates[], confidence, sources[] }"
    },
    {
      "name": "quote_shipment",
      "description": "Price a shipment across road/sea/air on one object: landed cost (duty + import VAT), freight by mode with a route score, cheapest + best-overall picks, customs readiness, sanctions posture. Persists and returns a shareable id.",
      "method": "POST",
      "path": "/api/quote",
      "input_schema": {
        "type": "object",
        "required": [
          "goods_value",
          "weight_kg"
        ],
        "properties": {
          "goods_value": {
            "type": "number",
            "description": "Customs (CIF) value of the goods"
          },
          "currency": {
            "type": "string",
            "description": "ISO currency of goods_value (GBP default). 20 majors supported; converted to GBP at the live ECB rate."
          },
          "weight_kg": {
            "type": "number"
          },
          "volume_m3": {
            "type": "number"
          },
          "commodity_code": {
            "type": "string",
            "description": "6-10 digit HS/commodity code. Use classify_commodity if unknown."
          },
          "origin": {
            "type": "string",
            "enum": [
              "eu",
              "rest",
              "gb"
            ],
            "description": "Origin zone"
          },
          "origin_country": {
            "type": "string",
            "description": "Origin country (name or ISO) — sharpens duty + preferential eligibility + sanctions."
          },
          "origin_locode": {
            "type": "string",
            "description": "Origin UN/LOCODE (e.g. CNSHA Shanghai) — resolves the real port so the lane carries chokepoint exposure, draught limits + customs dwell (port_profile)."
          },
          "dest_locode": {
            "type": "string",
            "description": "Destination UN/LOCODE (e.g. GBFXT Felixstowe). Pair with origin_locode for port-to-port operational nuance."
          },
          "vessel_draught_m": {
            "type": "number",
            "description": "Optional laden draught (m) — flags any port or canal (e.g. Panama 15.2m) the vessel cannot transit."
          },
          "destination": {
            "type": "string",
            "enum": [
              "gb",
              "ni",
              "eu",
              "rest"
            ]
          },
          "incoterm": {
            "type": "string",
            "enum": [
              "DDP",
              "DAP",
              "FCA",
              "EXW",
              "CIF",
              "FOB"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "auto",
              "road",
              "sea",
              "air"
            ],
            "description": "auto = cheapest compliant"
          },
          "vat_rate_pct": {
            "type": "number",
            "enum": [
              20,
              5,
              0
            ],
            "description": "UK import VAT rate (20 standard default)"
          },
          "method": {
            "type": "string",
            "enum": [
              "pva",
              "border",
              "deferment"
            ],
            "description": "VAT accounting method"
          },
          "consignor_name": {
            "type": "string",
            "description": "Shipper name — screened against OFSI/OFAC/UN/EU"
          },
          "consignee_name": {
            "type": "string",
            "description": "Receiver name — screened against OFSI/OFAC/UN/EU"
          }
        }
      },
      "returns": "quote object: { quote_ref, id, share_path, duty, landed_cost, options[], recommended, best_overall, lane, customs, screening, compliance_stop, decision }"
    },
    {
      "name": "retrieve_quote",
      "description": "Rehydrate a stored quote by its id (margin-stripped, customer-safe).",
      "method": "GET",
      "path": "/api/quote?id={uuid}"
    },
    {
      "name": "classify_commodity",
      "description": "Find candidate HS/commodity codes from a plain-English goods description (UK Trade Tariff). Use the returned code with quote_shipment for a sourced duty.",
      "method": "GET",
      "path": "/api/classify?q={description}",
      "returns": "candidates[]: { code, description, score }"
    },
    {
      "name": "sea_route",
      "description": "Real port-to-port sea routing (searoute approach): the routed distance + transit days through the actual canals/straits/capes (Suez/Panama/Malacca/…), draught-gated, with a Cape-of-Good-Hope alternative when a canal is used. Not great-circle — China→UK reads ~19,000 km via Suez, and the quote sea leg now runs on this.",
      "method": "GET",
      "path": "/api/searoute?from={UN/LOCODE|ISO2|lat,lng}&to={...}&draught={m}&speed={kn}",
      "returns": "{ distance_km, transit_days, via[], canals[], straits[], capes[], detour_ratio, great_circle_km, alternative }"
    },
    {
      "name": "verify_company",
      "description": "Verify a UK importer/counterparty against the Companies House register (5.6M companies): status (active/dissolved/liquidation), age, filed accounts (turnover/net-assets/cash), outstanding charges, London Gazette (strike-off) signals + qualitative risk bands → a verdict (verified/caution/red_flag). \"Is this a real, active, on-side company — or a shell?\" No external key. Indicative due-diligence; the co-pilot runs this on the consignee automatically.",
      "method": "GET",
      "path": "/api/company-check?q={company name or 8-char number}",
      "returns": "{ verdict, band, company:{number,name,status,age_years,sic_codes}, financials, risk_bands, reasons[], flags[], candidates[] }"
    },
    {
      "name": "prefill_from_document",
      "description": "Paste a commercial invoice / PO / packing list / bill of lading and extract the quote + co-pilot input fields (value, currency, gross weight, Incoterm, HS code, origin, shipper/consignee, refs). Deterministic — no LLM, no spend. Feed the fields to quote_shipment or freight_copilot; always review before it drives a quote.",
      "method": "POST",
      "path": "/api/parse-doc",
      "input_schema": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "The pasted document text."
          }
        }
      },
      "returns": "{ doc_type, fields:{ goods_value, currency, weight_kg, incoterm, commodity_code, origin_country, consignor_name, consignee_name }, references, confidence }"
    },
    {
      "name": "cbam_liability",
      "description": "Carbon Border Adjustment Mechanism exposure off the commodity code + weight + destination: is it in scope (iron/steel, aluminium, cement, fertilisers, hydrogen, electricity), which regime (EU CBAM live 2026 vs UK CBAM from 2027), the estimated embedded emissions + indicative certificate/return liability, and the obligations. Indicative — verified emissions + live ETS price at filing. Not tax advice.",
      "method": "GET",
      "path": "/api/cbam?code={CN}&weight={kg}&dest={eu|gb}",
      "returns": "{ in_scope, sector, regime, embedded_tco2, indicative_liability, carbon_price, obligations[] }"
    },
    {
      "name": "origin_qualification",
      "description": "Does a shipment QUALIFY for a preferential FTA rate (UK–EU TCA / Japan CEPA / DCTS-GSP / CPTPP / AfCFTA) — wholly-obtained vs change-of-tariff-heading vs value-added (max non-originating %) — and what proof is needed. Complements the quote (which says a preference is available). Indicative — confirm the exact Product-Specific Rule.",
      "method": "POST",
      "path": "/api/origin",
      "input_schema": {
        "type": "object",
        "required": [
          "agreement"
        ],
        "properties": {
          "agreement": {
            "type": "string",
            "enum": [
              "eu_tca",
              "japan_cepa",
              "dcts",
              "cptpp",
              "afcfta"
            ]
          },
          "commodity_code": {
            "type": "string"
          },
          "wholly_obtained": {
            "type": "boolean"
          },
          "tariff_heading_changed": {
            "type": "boolean"
          },
          "non_originating_value": {
            "type": "number"
          },
          "exworks_price": {
            "type": "number"
          },
          "max_nom_pct": {
            "type": "number",
            "description": "the exact PSR max non-originating % from the Annex"
          }
        }
      },
      "returns": "{ qualifies: qualifies|no|likely_not|need_more_info, criterion_met, proof_required, reasons[] }"
    },
    {
      "name": "demurrage_exposure",
      "description": "Demurrage & detention exposure — the free-time clock. Off the milestone dates (discharge / gate-out / empty-return) + free days + per-diem tiers: days used, chargeable days, cost, and the LIVE accruing exposure while it runs. The biggest surprise cost in container freight. Indicative — the carrier tariff decides.",
      "method": "GET",
      "path": "/api/demurrage?discharge={date}&gate_out={date}&containers={n}",
      "returns": "{ demurrage:{ chargeable_days, cost_gbp, status }, detention:{…}, total_exposure_gbp, accruing, severity, headline }"
    },
    {
      "name": "track_shipment",
      "description": "Ingest carrier/DCSA/AIS milestone events for a consignment (by UCR) and get the live status: lifecycle stage, ETA + ETA-drift, a ranked exception queue (hold · rollover · delay · demurrage · dead-feed) and a geo/time-decayed disruption risk score (live NASA EONET). Idempotent; decision-support only (acting on an exception is a human decision).",
      "method": "POST",
      "path": "/api/track",
      "input_schema": {
        "type": "object",
        "required": [
          "ucr"
        ],
        "properties": {
          "ucr": {
            "type": "string",
            "description": "Consignment reference (DUCR-shaped) — the join key across quote/bond/logistics."
          },
          "events": {
            "type": "array",
            "description": "Manual milestone events. Deduped on a stable key so re-polling never double-counts."
          },
          "dcsa": {
            "type": "object",
            "description": "A full DCSA Track&Trace 3.0 carrier payload (events[]/transportEvents/equipmentEvents/shipmentEvents) — mapped through the adapter into the canonical stream."
          },
          "ais": {
            "type": "object",
            "description": "An AIS vessel position (aisstream.io envelope or flat {lat,lon,vessel,timestamp})."
          },
          "mock": {
            "type": "string",
            "description": "Pass \"dcsa\" to prove the live-pull pipe with a keyless sample DCSA payload."
          },
          "planned_eta": {
            "type": "string",
            "description": "ISO planned arrival — enables ETA-drift + delay detection."
          },
          "destination_country": {
            "type": "string",
            "description": "ISO2 — resolves the point for disruption-risk proximity."
          },
          "mode": {
            "type": "string",
            "enum": [
              "sea",
              "air",
              "road"
            ]
          },
          "action": {
            "type": "string",
            "enum": [
              "ingest",
              "plan",
              "provider_request"
            ],
            "description": "plan → which subscriptions are due to poll; provider_request → the fetch descriptor for a provider (dcsa-generic|vizion|terminal49|aisstream). The live feed is a creds paste onto the built adapter."
          }
        }
      },
      "returns": "status: { stage, eta, eta_drift_days, exceptions[], severity }, risk: { score, band, drivers[] }, milestones[]"
    },
    {
      "name": "get_shipment_status",
      "description": "Read a consignment’s live status + timeline by UCR (no ingest).",
      "method": "GET",
      "path": "/api/track?ucr={ucr}&dest={ISO2}&mode={mode}"
    },
    {
      "name": "emit_declaration",
      "description": "Turn a shipment (a stored quote id, a quote object, or a consignment) into the FILEABLE machine forms: a UK CDS data-element set, a UN/EDIFACT CUSDEC message, and a WCO Data Model JSON — plus a readiness check on the required DEs. DRAFT decision-support only: a customs declaration is filed and signed by a human at the CDS/CSP gate; the emitter never transmits.",
      "method": "POST",
      "path": "/api/declaration",
      "input_schema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Stored quote uuid (rehydrated into a consignment)."
          },
          "quote": {
            "type": "object",
            "description": "A computed quote object (projected into a consignment)."
          },
          "consignment": {
            "type": "object",
            "description": "An explicit consignment header."
          },
          "type": {
            "type": "string",
            "enum": [
              "import",
              "warehouse_entry",
              "removal",
              "ens"
            ],
            "description": "Declaration type (import default)."
          },
          "extras": {
            "type": "object",
            "description": "eori, incoterm, description, warehouse_auth, removal_type, preference, valuation_method …"
          }
        }
      },
      "returns": "declaration: { declaration_type_code, procedure_code, data_elements[], missing[], ready, cusdec, wco, human_gate }"
    },
    {
      "name": "reconcile_bond",
      "description": "The HMRC 3-way test as a live check: roll a customs-warehouse movement ledger to an expected on-hand, compare to the physical stock-take and the declared removals, and flag every break (undeclared_removal · quantity_mismatch · negative_balance · orphan_physical) ranked by duty-at-risk, with the open suspended liability costed and an audit pack assembled. Decision-support only — a human files each removal and resolves each break.",
      "method": "POST",
      "path": "/api/reconcile",
      "input_schema": {
        "type": "object",
        "properties": {
          "movements": {
            "type": "array",
            "description": "Stock ledger: [{ direction:in|out, rotation, quantity, valueGbp, dutyGbp, vatGbp, removalType, declaration_ref }]"
          },
          "physical": {
            "description": "Stock-take: [{ rotation, quantity }] or { rotation: qty }"
          },
          "as_of": {
            "type": "string"
          },
          "warehouse_auth": {
            "type": "string"
          },
          "warehouse_type": {
            "type": "string",
            "enum": [
              "private",
              "public"
            ]
          }
        }
      },
      "returns": "reconciliation: { reconciled, breaks[], rotations[], totals:{ open_liability, duty_at_risk }, audit_pack }"
    },
    {
      "name": "book_shipment",
      "description": "Assemble a carrier booking off a shipment (WebCargo/CargoAi air · DCSA/INTTRA ocean · EasyPost/Sendcloud parcel), then a named human confirms. Partner-send is a HUMAN GATE — the AI assembles and packages; it never transmits to a carrier on its own. Scaffold: confirmed bookings are packaged (ready_to_transmit) until a real partnership + credentials are wired.",
      "method": "POST",
      "path": "/api/booking",
      "input_schema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "assemble",
              "prepare",
              "confirm"
            ],
            "description": "prepare = the exact carrier request + idempotency key (mock:true proves the round-trip, no send)"
          },
          "carrier": {
            "type": "string",
            "description": "webcargo | cargoai | dcsa | inttra | easypost | sendcloud"
          },
          "id": {
            "type": "string",
            "description": "a stored quote uuid (assemble) or booking uuid (confirm)"
          },
          "quote": {
            "type": "object"
          },
          "consignment": {
            "type": "object"
          },
          "extras": {
            "type": "object",
            "description": "shipper_name, consignee_name, description, requested_ready_date, service …"
          },
          "booking": {
            "type": "object",
            "description": "the assembled booking (for confirm)"
          },
          "mock": {
            "type": "boolean",
            "description": "prepare only — return a deterministic mock transmit result proving the adapter wiring (NOT a real carrier booking)."
          },
          "confirmed_by": {
            "type": "string",
            "description": "REQUIRED to confirm — the named human. The AI cannot confirm or send."
          }
        }
      },
      "returns": "assemble → { booking_ref, state:draft, request, ready, human_gate, carrier_transmit }; prepare → { carrier_transmit:{ adapter, idempotency_key, mapped_request }, mock_result? }; confirm → { state:ready_to_transmit, dry_run, would_transmit, carrier_transmit }. The born-ready adapter maps the request + derives an idempotency key; the real send stays a partner_send human gate (named confirmed_by + authorize_send)."
    },
    {
      "name": "compare_customs_regimes",
      "description": "Bonded-warehouse decision engine: compare pay-at-border / Postponed VAT Accounting / duty deferment / customs warehousing for one consignment. Quantifies duty suspension over the dwell, re-export duty relief (never paid), VAT cash-flow and the bonded storage premium. Stateless + indicative; duty rate + valuation apply at RELEASE from the warehouse.",
      "method": "POST",
      "path": "/api/bonded-relief",
      "input_schema": {
        "type": "object",
        "required": [
          "customs_value_gbp",
          "duty_pct"
        ],
        "properties": {
          "customs_value_gbp": {
            "type": "number",
            "description": "CIF customs value in GBP"
          },
          "duty_pct": {
            "type": "number",
            "description": "HMRC duty rate % (use classify_commodity + quote_shipment for a sourced rate)"
          },
          "vat_rate": {
            "type": "number",
            "enum": [
              0.2,
              0.05,
              0
            ],
            "description": "import VAT rate (0.20 default)"
          },
          "dwell_days": {
            "type": "number",
            "description": "expected days in bond before release (default 60)"
          },
          "reexport_share": {
            "type": "number",
            "description": "0..1 share re-exported from bond — UK duty never paid on it (default 0)"
          },
          "annual_cost_of_capital": {
            "type": "number",
            "description": "working-capital cost assumption (default 0.08)"
          },
          "bonded_storage_premium_gbp": {
            "type": "number",
            "description": "premium the bonded warehouse charges over standard storage (default 0)"
          },
          "vat_registered": {
            "type": "boolean",
            "description": "default true — unregistered importers cannot use PVA or recover import VAT"
          },
          "vat_recovery_days": {
            "type": "number",
            "description": "days from paying import VAT to recovering it on the return (default 45)"
          },
          "deferment_delay_days": {
            "type": "number",
            "description": "duty-deferment payment delay in days (default 30 — Notice 101, ~15th of the following month)"
          },
          "pva_at_release": {
            "type": "boolean",
            "description": "default true — use Postponed VAT Accounting on the release-from-warehouse declaration (registered importers)"
          }
        }
      },
      "returns": "comparison: { duty_full_gbp, import_vat_full_gbp, regimes[4] (net_advantage_vs_immediate_gbp, requirements, notes), recommended, honesty, source_basis }"
    },
    {
      "name": "bond_movement",
      "description": "BondOS — model goods entering a customs warehouse with import duty + import VAT suspended, an optional partial draw-down (home-use/export/transfer), CCG guarantee headroom, and the working-capital released. Returns the suspended figures + the stock-record ledger. Duty rate/value at removal is confirmed on the CDS declaration (human gate).",
      "method": "POST",
      "path": "/api/bond",
      "input_schema": {
        "type": "object",
        "required": [
          "goods_value"
        ],
        "properties": {
          "goods_value": {
            "type": "number",
            "description": "Customs value of the goods entering the warehouse"
          },
          "duty_rate_pct": {
            "type": "number"
          },
          "vat_rate_pct": {
            "type": "number",
            "enum": [
              20,
              5,
              0
            ]
          },
          "commodity_code": {
            "type": "string"
          },
          "warehouse_type": {
            "type": "string",
            "enum": [
              "private",
              "public"
            ]
          },
          "warehouse_auth": {
            "type": "string",
            "description": "Customs-warehouse authorisation number"
          },
          "guarantee_gbp": {
            "type": "number",
            "description": "CCG reference amount"
          },
          "guarantee_waiver": {
            "type": "boolean"
          },
          "open_liability_gbp": {
            "type": "number",
            "description": "Duty already suspended across the warehouse"
          },
          "days_in_warehouse": {
            "type": "number"
          },
          "pva": {
            "type": "boolean",
            "description": "Postponed VAT Accounting (default true)"
          },
          "removal": {
            "type": "object",
            "description": "{ type: home_use|export|transfer, portion_pct: 0-100, duty_rate_pct? }"
          }
        }
      },
      "returns": "bond object: { warehouse, suspension, removal, guarantee, working_capital, stock_record[], suspended_remaining_gbp, flags[], ready, decision }"
    },
    {
      "name": "logistics_job",
      "description": "LogisticsOS — cost + compliance-check a delivery job for an O-licence fleet: own-fleet cost per mile/per drop + sell rate at margin, driver-hours regime check (EU >3.5t / GB domestic), vehicle compliance (MOT/tax/inspection/tacho/walkaround), O-licence financial standing + vehicle margin, load utilisation, and a dispatch verdict. Statutory sign-off stops at a human gate.",
      "method": "POST",
      "path": "/api/logistics",
      "input_schema": {
        "type": "object",
        "required": [
          "distance_miles"
        ],
        "properties": {
          "distance_miles": {
            "type": "number"
          },
          "drops": {
            "type": "number"
          },
          "international": {
            "type": "boolean"
          },
          "vehicle": {
            "type": "object",
            "description": "{ reg, gvw_kg, payload_kg, volume_m3, mpg, fuel_price_ppl, mot_due, ved_due, safety_inspection_due, tacho_calibration_due, walkaround_due }"
          },
          "load": {
            "type": "object",
            "description": "{ weight_kg, volume_m3 }"
          },
          "driver": {
            "type": "object",
            "description": "{ driving_hours, duty_hours }"
          },
          "licence": {
            "type": "object",
            "description": "{ type: standard|light_goods|restricted, vehicles_authorised, vehicles_in_use, available_finance_gbp }"
          }
        }
      },
      "returns": "job object: { cost, driver_hours, load, compliance, licence, flags[], dispatchable, decision }"
    },
    {
      "name": "clerk_paperwork",
      "description": "AI Clerk — for a consignment + stage (import/bond/delivery/all), return the required document checklist pre-filled from the consignment, what is still missing, and drafts of the structured documents. Pass extras.product_type (vape / soft_drink / energy_drink / wine_spirits) to pull the FMCG bond-clerk documents: EMCS eAD for duty-suspended excise movements, AWRS due-diligence record, vaping duty-stamp compliance record, SDIL quarterly-return line. Regulated filings/signatures carry a human gate; optional AI assist normalises the goods description + drafts a covering note.",
      "method": "POST",
      "path": "/api/clerk",
      "input_schema": {
        "type": "object",
        "properties": {
          "consignment": {
            "type": "object",
            "description": "The shared consignment, or pass its fields at the top level"
          },
          "stage": {
            "type": "string",
            "enum": [
              "import",
              "bond",
              "delivery",
              "all"
            ]
          },
          "extras": {
            "type": "object",
            "description": "Operator details: consignor_name, consignee_name, invoice_no, incoterm, eori, description, warehouse_auth, delivery_address, vehicle_reg, claim_preference …"
          },
          "draft": {
            "type": "string",
            "description": "A single document key to draft in full"
          },
          "ai": {
            "type": "boolean",
            "description": "Request the optional AI-assist pass"
          }
        }
      },
      "returns": "pack: { ucr, stage, documents[]:{ name, stage, authority, human_gate, fields[], missing[], status }, summary, ai_assist? }"
    },
    {
      "name": "dispatch_pack",
      "description": "AI fleet dispatcher — consignment + job → the complete dispatch pack: LogisticsOS verdict (cost/sell, driver-hours, vehicle + O-licence compliance, load), delivery paperwork (delivery note/CMR, POD spec, walkaround) pre-filled by the AI Clerk, a step-by-step driver brief with timing legs, and an honest dispatch_ready flag that never goes green past a blocker. Statutory sign-offs (walkaround, POD, driver hours, bonded release) stay human gates.",
      "method": "POST",
      "path": "/api/dispatch",
      "input_schema": {
        "type": "object",
        "required": [
          "job"
        ],
        "properties": {
          "job": {
            "type": "object",
            "description": "LogisticsOS body: { distance_miles (required), drops, vehicle{}, load{}, driver{}, licence{} }"
          },
          "consignment": {
            "type": "object",
            "description": "the shared consignment (ucr, goods_value, weight_kg, mode, origin, destination)"
          },
          "extras": {
            "type": "object",
            "description": "delivery_address / drop_addresses[], pickup_address, bonded_collection (adds a human-gated release leg), consignor_name, consignee_name, description, vehicle_reg, driver"
          }
        }
      },
      "returns": "pack: { logistics, documents[], docs_summary, brief: { legs[], est_total_hours, drops }, blockers[], dispatch_ready, decision }"
    },
    {
      "name": "fmcg_funded_cycle",
      "description": "FMCG import cashflow + compliance for one consignment — vapes (Vaping Products Duty £2.20/10ml from 1 Oct 2026, duty stamps mandatory 1 Apr 2027, excise suspension separate from customs warehousing), soft drinks (SDIL bands + quarterly-return cashflow, Jan 2028 reform), and the full cash-conversion-cycle runway: negotiated supplier terms + PVA + duty deferment + bonded/excise suspension + invoice finance vs the unstructured baseline. Returns duty plan + compliance timeline + day-by-day cash ledger with peak funding requirement before/after the stack.",
      "method": "POST",
      "path": "/api/fmcg",
      "input_schema": {
        "type": "object",
        "required": [
          "product_type",
          "goods_cost_gbp"
        ],
        "properties": {
          "product_type": {
            "type": "string",
            "enum": [
              "vape",
              "soft_drink",
              "other"
            ]
          },
          "goods_cost_gbp": {
            "type": "number",
            "description": "supplier invoice value (GBP)"
          },
          "on_date": {
            "type": "string",
            "description": "YYYY-MM-DD — rates + timeline statuses computed for this date (default today)"
          },
          "liquid_ml": {
            "type": "number",
            "description": "vape: total ml of vaping liquid"
          },
          "litres": {
            "type": "number",
            "description": "soft_drink: total litres"
          },
          "sugar_g_per_100ml": {
            "type": "number",
            "description": "soft_drink: total sugar per 100ml"
          },
          "milk_based": {
            "type": "boolean",
            "description": "soft_drink: exempt until Jan 2028"
          },
          "customs_duty_gbp": {
            "type": "number"
          },
          "import_vat_gbp": {
            "type": "number"
          },
          "freight_cost_gbp": {
            "type": "number"
          },
          "sale_value_gbp": {
            "type": "number"
          },
          "supplier_terms_days": {
            "type": "number",
            "description": "negotiated supplier payment terms (default 0)"
          },
          "transit_days": {
            "type": "number"
          },
          "days_to_sell": {
            "type": "number"
          },
          "debtor_days": {
            "type": "number"
          },
          "pva": {
            "type": "boolean",
            "description": "default true"
          },
          "dda": {
            "type": "boolean",
            "description": "duty deferment account (default false)"
          },
          "bonded": {
            "type": "boolean",
            "description": "customs warehouse — customs duty at removal (default false)"
          },
          "excise_suspended": {
            "type": "boolean",
            "description": "excise warehouse/approved store — excise at removal (default false; a customs warehouse alone does NOT suspend VPD)"
          },
          "invoice_finance": {
            "type": "boolean",
            "description": "default false"
          },
          "advance_pct": {
            "type": "number",
            "description": "invoice-finance initial advance % (default 85, max 95)"
          }
        }
      },
      "returns": "plan: { on_date, product_type, duty_plan (VPD or SDIL), compliance.items[], runway: { stacked.events[], baseline, working_capital_released_gbp, coverage_pct, funding_gap_gbp, self_funding, invoice_finance_advance_gbp, summary } }"
    },
    {
      "name": "vehicle_lookup",
      "description": "Auto-fill a LogisticsOS vehicle from its UK registration — DVLA Vehicle Enquiry Service (tax + MOT status/expiry, revenue/gross weight, fuel, CO2) enriched with DVSA MOT History (latest result, mileage, advisories). Returns the vehicle object ready to drop into logistics_job. Official data, may lag — confirm before dispatch.",
      "method": "GET",
      "path": "/api/vehicle?reg={registration}",
      "returns": "vehicle: { reg, make, gvw_kg, fuel_type, tax_status, mot_status, mot_due, ved_due, latest_mot_result, advisories[], flags[] }"
    },
    {
      "name": "live_rates",
      "description": "LIVE multi-carrier rates for a shipment via a carrier aggregator (EasyPost by default — 100+ carriers incl. DHL/UPS/FedEx/Royal Mail, no per-carrier contract). Returns the real buy cost per carrier/service + our reseller sell price, cheapest + fastest picks. Turns the indicative FreightOS quote into a live-bookable one. Degrades to indicative when unconfigured; booking + label is a separate human-gated step.",
      "method": "POST",
      "path": "/api/rates",
      "input_schema": {
        "type": "object",
        "properties": {
          "from": {
            "type": "object",
            "description": "{ country, postcode, city, street }"
          },
          "to": {
            "type": "object",
            "description": "{ country, postcode, city, street }"
          },
          "weight_kg": {
            "type": "number"
          },
          "dims_cm": {
            "type": "object",
            "description": "{ l, w, h }"
          },
          "value": {
            "type": "number"
          }
        }
      },
      "returns": "rates: { available, options[]:{ carrier, service, buy_cost, sell_floor, transit_days }, cheapest, fastest }"
    },
    {
      "name": "validate_declaration",
      "description": "CDS pre-submission validation — run a declaration (or a stored quote / consignment, emitted first) through the five-pass CDS pre-flight: mandatory-DE matrix per procedure category, format (EORI/commodity/dates), codelist membership, conditional rules (special procedures need the DE 3/39 authorisation; a non-100 preference needs proof of origin), and cross-field (tax lines when duty/VAT > 0). Returns ready + rule-cited errors so a human clears every issue BEFORE filing. ready:true means the draft passes pre-flight — it is NOT filed. Submitting to CDS is a regulated-filing human gate.",
      "method": "POST",
      "path": "/api/cds-validate",
      "input_schema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Stored quote uuid (emitted into a declaration first)."
          },
          "quote": {
            "type": "object"
          },
          "consignment": {
            "type": "object"
          },
          "declaration": {
            "type": "object",
            "description": "A pre-built declaration (from emit_declaration) to validate directly."
          },
          "type": {
            "type": "string",
            "enum": [
              "import",
              "warehouse_entry",
              "removal",
              "ens"
            ]
          },
          "extras": {
            "type": "object",
            "description": "eori, incoterm, description, warehouse_auth, preference, valuation_method …"
          }
        }
      },
      "returns": "{ ready, errors:[{de, rule_ref, severity, detail}], warnings, procedure_code, procedure_category, human_gate, submission_gate }"
    },
    {
      "name": "control_tower",
      "description": "The exception-ranked cockpit projection: pass the operator’s shipments and get the KPI tiles + a severity-ranked exception queue (sanctions hold > open customs blockers > live tracking exceptions > unclaimed duty saving > clear). Read-only decision-support — it ranks + totals what needs a human; it never clears a hold, files, or books.",
      "method": "POST",
      "path": "/api/control-tower",
      "input_schema": {
        "type": "object",
        "required": [
          "shipments"
        ],
        "properties": {
          "shipments": {
            "type": "array",
            "description": "[{ quote_ref, lane, mode, landed, duty_pct, screening_hit?, blockers?, exceptions?, preferential_pct?, ts }]"
          }
        }
      },
      "returns": "{ kpis:{…}, shipments:[…severity-ranked with sev{level,label,rank}…], top_severity }"
    },
    {
      "name": "period_pl",
      "description": "The haulier MONTHLY P&L — did the month pay, not just the job. Rolls completed jobs into revenue → variable cost → gross margin → allocated fixed overhead → net profit, plus true cost per mile (including empty running), utilisation, period-over-period trend, and best/worst jobs by margin AND by margin-per-hour. With no fixed_costs supplied the overhead is UNALLOCATED and net profit returns null — gross margin is NOT profit and the engine will not pretend otherwise. Management information, not statutory accounts.",
      "method": "POST",
      "path": "/api/period-pl",
      "input_schema": {
        "type": "object",
        "required": [
          "jobs"
        ],
        "properties": {
          "jobs": {
            "type": "array",
            "description": "[{ date, revenue_gbp, fuel_cost_gbp, driver_cost_gbp, subcontract_cost_gbp, other_variable_cost_gbp, miles, laden_miles, empty_miles, working_hours, vehicle_reg }] — supply empty_miles (or `miles` as the run total alongside laden_miles) or empty running is reported as an unknown FLOOR, never a measured 0%."
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "fixed_costs": {
            "type": "object",
            "description": "vehicle_finance_gbp, insurance_gbp, o_licence_gbp, depot_gbp, transport_manager_gbp, other_gbp — omit and overhead stays UNALLOCATED (net profit returns null rather than equalling gross margin)"
          },
          "available_days": {
            "type": "number"
          },
          "trucks": {
            "type": "number"
          },
          "prior_periods": {
            "type": "array",
            "description": "earlier period_pl results (oldest → newest) to enable the period-over-period trend"
          }
        }
      },
      "limits": {
        "max_jobs": 1000,
        "max_prior_periods": 24
      },
      "returns": "{ period_pl:{revenue_gbp, variable_cost_gbp, gross_margin_gbp, fixed_costs_gbp, net_profit_gbp, overhead_allocated, decision, caveats[]}, cost_per_mile:{empty_running_pct, empty_miles_complete, variable_cost_per_laden_mile_gbp, total_cost_per_laden_mile_gbp, caveats[]}, utilisation:{revenue_per_available_day_gbp, revenue_per_truck_gbp, caveats[]}, ranking:{best_by_margin, worst_by_margin, best_by_margin_per_hour, rankings_diverge, insight}, trend:{comparable, biggest_mover, headline}, human_gate }"
    }
  ],
  "capabilities": [
    "live UK Trade Tariff duty (erga-omnes MFN)",
    "origin-aware preferential duty (real geographical-area membership + proof-of-origin gate)",
    "import VAT 20/5/0 with an honesty flag",
    "multi-currency customs valuation (live ECB rate)",
    "public freight-rate-index bands (FBX / BAI / RHA) on every freight figure",
    "real-geography multimodal route optimiser with chokepoint (Suez/Panama/Malacca) disruption",
    "OFSI + OFAC + UN + EU sanctions party-name screening (distinctive-core fuzzy match across the four consolidated lists, hard compliance stop)",
    "commodity-code classification",
    "bonded-warehouse decision: pay-at-border vs PVA vs deferment vs customs-warehousing, quantified for one consignment (decide → then operate with the bond engine)",
    "customs-warehouse duty + import VAT suspension, stock record, partial draw-down (CDS 7100/4071), CCG guarantee headroom, working-capital released",
    "O-licence van-fleet job costing, driver-hours (EU/GB) + vehicle compliance, load utilisation, dispatch clearance",
    "vehicle auto-fill from registration (DVLA VES + DVSA MOT History — tax/MOT/gross-weight/advisories)",
    "live multi-carrier rates via aggregator (EasyPost/DHL/UPS/FedEx) — indicative FreightOS quote becomes live-bookable, reseller margin applied",
    "AI Clerk paperwork across import/bond/delivery — checklist, field pre-fill, structured drafts, human-gated filings",
    "FMCG duty layer: Vaping Products Duty (from 1 Oct 2026, stamps + excise-suspension aware) + Soft Drinks Industry Levy (bands, quarterly-return cashflow, 2028 reform)",
    "funded cash-conversion cycle: supplier terms + PVA + DDA + bond/excise suspension + invoice-finance sizing — peak cash need before/after the stack",
    "one shared consignment object (WCO DUCR-shaped UCR) joining quote → bond → fleet → documents",
    "human gates on: live price, production deploy, partner send, regulated filing (CDS declaration, POD, walkaround), insurance bind"
  ]
}