tz-at-point 1.0.0

package/dist/lookup.js

@@ -0,0 +1,103 @@
+import { metres, mod, RAD } from './geo.js';
+import { keyOf, latLng } from './key.js';
+import { isZone, readTable } from './table.js';
+/**
+ * Near search reads one grid cell. Rows are 0.01° of latitude. Each row has fewer columns the nearer it
+ * is to a pole, so every cell is at least ~1.1km wide, and an entry (radius at most 1km) reaches a
+ * handful of cells anywhere on Earth. A lookup's cost depends on how many entries overlap that spot.
+ */
+const CELL = 0.01;
+const EQUATOR_COLUMNS = 36_000;
+/** Metres per degree of latitude, rounded down so an entry's span errs wide. */
+const METRES_PER_DEGREE = 110_000;
+/** Columns in a row, sized by the cosine of its poleward edge. */
+const columnsIn = (row) => Math.max(1, Math.floor(EQUATOR_COLUMNS * Math.cos(Math.min(90, Math.max(Math.abs(row), Math.abs(row + 1)) * CELL) * RAD)));
+const columnOf = (lng, columns) => Math.floor(((lng + 180) / 360) * columns);
+const cellId = (row, column, columns) => row * EQUATOR_COLUMNS + mod(column, columns);
+/** Every cell an entry's radius reaches. Exported for tests. */
+export function* cellsReached({ lat, lng, radius }) {
+    const dLat = radius / METRES_PER_DEGREE;
+    const dLng = dLat / Math.max(Math.cos((Math.abs(lat) + dLat) * RAD), 1e-9);
+    for (let row = Math.floor((lat - dLat) / CELL); row <= Math.floor((lat + dLat) / CELL); row++) {
+        const columns = columnsIn(row);
+        const west = columnOf(lng - dLng, columns);
+        const east = Math.min(columnOf(lng + dLng, columns), west + columns - 1);
+        for (let column = west; column <= east; column++)
+            yield cellId(row, column, columns);
+    }
+}
+/**
+ * Build a lookup that answers only from the table (`tz-at-point/core`). `tz-at-point` re-exports this with the
+ * raster fallback applied; import from here when you never want that 73KB in your bundle.
+ *
+ * Build a lookup from a table made by `npx tz-at-point build points.json -o zones.json`.
+ *
+ * Call it once, at module scope, with the table imported as JSON so your bundler embeds it; the lookup
+ * then reads no files, which is what makes it safe in serverless functions. The table is validated here
+ * (it is typed `unknown` because JSON imports are typed loosely): a malformed table throws a TypeError at
+ * startup. The returned function never throws.
+ *
+ * @example
+ * import { createLookup } from 'tz-at-point';
+ * import table from './zones.json' with { type: 'json' };
+ *
+ * const zoneAt = createLookup(table);
+ *
+ * const { zone } = zoneAt(51.5561, -0.2794); // 'Europe/London'
+ * const local = zone && new Intl.DateTimeFormat('en-GB', { timeZone: zone, timeStyle: 'short' }).format(new Date('2026-11-14T19:45:00Z')); // '19:45'
+ */
+export function createLookup(table, options) {
+    const fallback = options?.fallback ?? null;
+    const exact = new Map();
+    const cells = new Map();
+    for (const entry of readTable(table)) {
+        exact.set(entry.key, entry.zone);
+        if (entry.radius === 0)
+            continue;
+        for (const id of cellsReached(entry)) {
+            const list = cells.get(id);
+            if (list)
+                list.push(entry);
+            else
+                cells.set(id, [entry]);
+        }
+    }
+    return (lat, lng) => {
+        const point = latLng(lat, lng);
+        if (!point)
+            return { zone: null, source: null };
+        const [y, x] = point;
+        const hit = exact.get(keyOf(y, x));
+        if (hit !== undefined)
+            return { zone: hit, source: 'table' };
+        const row = Math.floor(y / CELL);
+        const columns = columnsIn(row);
+        const near = nearest(cells.get(cellId(row, columnOf(x, columns), columns)), y, x);
+        if (near !== null)
+            return { zone: near, source: 'table-near' };
+        if (fallback) {
+            try {
+                const zone = fallback(y, x);
+                if (isZone(zone))
+                    return { zone, source: 'raster' };
+            }
+            catch {
+                // A fallback failure is an unresolved point, not a crash.
+            }
+        }
+        return { zone: null, source: null };
+    };
+}
+/** Zone of the nearest entry whose own radius covers the point. */
+function nearest(entries, lat, lng) {
+    let zone = null;
+    let best = Infinity;
+    for (const e of entries ?? []) {
+        const d = metres(lat, lng, e.lat, e.lng);
+        if (d <= e.radius && d < best) {
+            best = d;
+            zone = e.zone;
+        }
+    }
+    return zone;
+}

package/dist/points.d.ts

@@ -0,0 +1,8 @@
+export interface Point {
+    lat: number;
+    lng: number;
+}
+/** Points from parsed JSON: an array of `[lat, lng]` or `{ lat, lng }`. */
+export declare function pointsFromJson(rows: unknown): Point[];
+/** Points from CSV text with `lat` and `lng` header columns, in any order. */
+export declare function pointsFromCsv(text: string): Point[];

package/dist/points.js

@@ -0,0 +1,62 @@
+import { latLng } from './key.js';
+/** A plain decimal: no hex, exponents or blanks, which Number() would otherwise accept. */
+const DECIMAL = /^\s*-?\d+(\.\d+)?\s*$/;
+/** Points from parsed JSON: an array of `[lat, lng]` or `{ lat, lng }`. */
+export function pointsFromJson(rows) {
+    if (!Array.isArray(rows))
+        throw new Error('JSON points must be an array');
+    return rows.map((row, i) => {
+        const point = Array.isArray(row) ? row.length === 2 && latLng(row[0], row[1]) : latLng(row?.lat, row?.lng);
+        if (!point)
+            throw new Error(`row ${i + 1}: expected [lat, lng] or { lat, lng } with numbers in range`);
+        return { lat: point[0], lng: point[1] };
+    });
+}
+/** Points from CSV text with `lat` and `lng` header columns, in any order. */
+export function pointsFromCsv(text) {
+    const [header, ...lines] = text.split(/\r?\n/);
+    const columns = (splitCsv(header) ?? []).map((h) => h.trim().toLowerCase());
+    const latAt = columns.indexOf('lat');
+    const lngAt = columns.indexOf('lng');
+    if (latAt < 0 || lngAt < 0)
+        throw new Error('CSV header must have lat and lng columns');
+    const points = [];
+    for (const [i, line] of lines.entries()) {
+        if (line.trim() === '')
+            continue;
+        const cells = splitCsv(line);
+        if (!cells)
+            throw new Error(`line ${i + 2}: unterminated quote (quoted line breaks are not supported)`);
+        const [lat, lng] = [cells[latAt], cells[lngAt]].map((c) => (DECIMAL.test(c) ? Number(c) : NaN));
+        const point = latLng(lat, lng);
+        if (!point)
+            throw new Error(`line ${i + 2}: lat and lng must be decimal numbers in range`);
+        points.push({ lat: point[0], lng: point[1] });
+    }
+    return points;
+}
+/** One CSV record: comma-separated, fields optionally in double quotes, "" for a literal quote. Null if a quote is left open. */
+function splitCsv(line) {
+    const cells = [];
+    let cell = '';
+    let quoted = false;
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (quoted && c === '"' && line[i + 1] === '"') {
+            cell += '"';
+            i++;
+        }
+        else if (c === '"') {
+            quoted = !quoted;
+        }
+        else if (c === ',' && !quoted) {
+            cells.push(cell);
+            cell = '';
+        }
+        else {
+            cell += c;
+        }
+    }
+    cells.push(cell);
+    return quoted ? null : cells;
+}

package/dist/radius.d.ts

@@ -0,0 +1,12 @@
+export type Find = (lat: number, lng: number) => string | undefined;
+/**
+ * The widest radius (a multiple of RADIUS_STEP, at most `max`) around a point that the probes vouch for.
+ *
+ * Probes fill the disc on a ~10m lattice, ring by ring. A ring only samples its circle at intervals, so a
+ * narrow lobe of another zone can cross it between two probes; the radius therefore stops a whole ring
+ * short of the frontier, and the ring beyond `max` is probed as well. Even so this is sampling, not proof:
+ * a piece of another zone smaller than the lattice's ~7m cover radius can sit inside the radius unseen.
+ */
+export declare function safeRadius(find: Find, lat: number, lng: number, zone: string, max: number): number;
+/** A point's zone and safe radius: what build stores, and what check expects to find again. */
+export declare function resolve(find: Find, lat: number, lng: number, max: number): [zone: string | undefined, radius: number];

package/dist/radius.js

@@ -0,0 +1,27 @@
+import { destination } from './geo.js';
+import { RADIUS_STEP } from './table.js';
+/**
+ * The widest radius (a multiple of RADIUS_STEP, at most `max`) around a point that the probes vouch for.
+ *
+ * Probes fill the disc on a ~10m lattice, ring by ring. A ring only samples its circle at intervals, so a
+ * narrow lobe of another zone can cross it between two probes; the radius therefore stops a whole ring
+ * short of the frontier, and the ring beyond `max` is probed as well. Even so this is sampling, not proof:
+ * a piece of another zone smaller than the lattice's ~7m cover radius can sit inside the radius unseen.
+ */
+export function safeRadius(find, lat, lng, zone, max) {
+    if (max < RADIUS_STEP)
+        return 0;
+    for (let ring = RADIUS_STEP; ring <= max + RADIUS_STEP; ring += RADIUS_STEP) {
+        const bearings = Math.ceil((2 * Math.PI * ring) / RADIUS_STEP);
+        for (let i = 0; i < bearings; i++) {
+            if (find(...destination(lat, lng, ring, (360 * i) / bearings)) !== zone)
+                return Math.max(0, ring - 2 * RADIUS_STEP);
+        }
+    }
+    return Math.floor(max / RADIUS_STEP) * RADIUS_STEP;
+}
+/** A point's zone and safe radius: what build stores, and what check expects to find again. */
+export function resolve(find, lat, lng, max) {
+    const zone = find(lat, lng);
+    return [zone, zone === undefined ? 0 : safeRadius(find, lat, lng, zone, max)];
+}

package/dist/table.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The table `tz-at-point build` writes: point key → [IANA zone, safe radius in metres]. Commit it and don't
+ * edit it by hand; `tz-at-point build` adds points and `tz-at-point build --refresh` re-resolves them.
+ *
+ * @example
+ * { "v": 1, "points": { "51.5561,-0.2794": ["Europe/London", 250], "51.4394,4.9275": ["Europe/Amsterdam", 0] } }
+ */
+export interface Table {
+    v: 1;
+    /** The OpenStreetMap/ODbL credit, written into every generated table so the file explains itself. */
+    attribution?: string;
+    /** The `--max-radius` the table was built with, so a later build can tell its radii apart from probed ones. */
+    maxRadius?: number;
+    /** The geo-tz version whose boundaries produced these zones, so a data bump is visible in the diff. */
+    geoTz?: string;
+    points: Record<string, [zone: string, radius: number]>;
+}
+export interface Entry {
+    key: string;
+    lat: number;
+    lng: number;
+    zone: string;
+    radius: number;
+}
+/** Radii are multiples of the probe spacing, up to a kilometre. */
+export declare const RADIUS_STEP = 10;
+export declare const MAX_RADIUS = 1000;
+export declare const isRadius: (n: unknown) => n is number;
+/** An IANA zone name: `UTC`, `Etc/GMT+12`, `America/Argentina/Buenos_Aires`. Nothing else reaches callers. */
+export declare const isZone: (zone: unknown) => zone is string;
+/** Validate a table and return its entries. Throws a TypeError, prefixed with `name`, naming the first problem. */
+export declare function readTable(table: unknown, name?: string): Entry[];
+/** Serialise a table with sorted keys, one entry per line, so diffs stay readable. */
+export declare function formatTable(points: Map<string, [string, number]>, maxRadius: number, geoTz?: string): string;
+/** The geo-tz version a table was built with, if it recorded one. */
+export declare const tableGeoTz: (table: unknown) => string | undefined;
+/** The `--max-radius` a table was built with, if it recorded one. */
+export declare const tableMaxRadius: (table: unknown) => number | undefined;

package/dist/table.js

@@ -0,0 +1,76 @@
+import { keyOf, latLng, parseKey } from './key.js';
+import { quote } from './text.js';
+/** Radii are multiples of the probe spacing, up to a kilometre. */
+export const RADIUS_STEP = 10;
+export const MAX_RADIUS = 1000;
+export const isRadius = (n) => Number.isInteger(n) && n >= 0 && n <= MAX_RADIUS && n % RADIUS_STEP === 0;
+/** An IANA zone name: `UTC`, `Etc/GMT+12`, `America/Argentina/Buenos_Aires`. Nothing else reaches callers. */
+// Also not a name Object.prototype already has: a consumer that keys a plain object by zone would
+// otherwise have "__proto__" or "constructor" handed to it from a hostile table. No IANA name collides.
+export const isZone = (zone) => typeof zone === 'string' && /^[\w+-]{1,32}(\/[\w+-]{1,32}){0,2}$/.test(zone) && !(zone in Object.prototype);
+/** True for a JSON-ish object, including one from another realm (whose Object.prototype is not ours). */
+const isPlainObject = (value) => {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || Object.getPrototypeOf(proto) === null;
+};
+/** Validate a table and return its entries. Throws a TypeError, prefixed with `name`, naming the first problem. */
+export function readTable(table, name = 'tz-at-point table') {
+    if (!isPlainObject(table))
+        throw new TypeError(`${name}: must be a plain object`);
+    // `import * as table from './zones.json'` gives a module namespace, not the table.
+    if (table[Symbol.toStringTag] === 'Module') {
+        throw new TypeError(`${name}: got a module namespace; pass the JSON module's default export`);
+    }
+    if (!Object.hasOwn(table, 'v') || table.v !== 1)
+        throw new TypeError(`${name}: unsupported version ${quote(table.v)}`);
+    if (!Object.hasOwn(table, 'points') || !isPlainObject(table.points))
+        throw new TypeError(`${name}: points must be a plain object`);
+    if (Object.hasOwn(table, 'attribution') && typeof table.attribution !== 'string')
+        throw new TypeError(`${name}: attribution must be a string`);
+    const zones = new Set(); // valid names already seen: a table repeats a few hundred at most
+    const entries = [];
+    for (const [key, value] of Object.entries(table.points)) {
+        const fail = (problem) => new TypeError(`${name}: entry ${quote(key)} ${problem}`);
+        const [lat, lng] = parseKey(key);
+        if (!latLng(lat, lng) || keyOf(lat, lng) !== key)
+            throw fail('is not a canonical point key');
+        if (!Array.isArray(value) || value.length !== 2)
+            throw fail('must map to [zone, radius]');
+        const [zone, radius] = value;
+        if (!zones.has(zone)) {
+            if (!isZone(zone))
+                throw fail('has an invalid zone name');
+            zones.add(zone);
+        }
+        if (!isRadius(radius))
+            throw fail(`has radius ${quote(radius)}; expected a multiple of ${RADIUS_STEP} from 0 to ${MAX_RADIUS}`);
+        entries.push({ key, lat, lng, zone, radius });
+    }
+    return entries;
+}
+/**
+ * Where the zones came from. Not required: the OSM Foundation's geocoding guideline treats a collection
+ * of query results like this as an insubstantial extract. It travels with the file so that whoever finds
+ * it later knows to credit OpenStreetMap in anything they ship.
+ */
+const ATTRIBUTION = 'Timezone boundaries from OpenStreetMap (https://www.openstreetmap.org/copyright), '
+    + 'ODbL 1.0. Zone names from the IANA tz database, public domain.';
+/** Serialise a table with sorted keys, one entry per line, so diffs stay readable. */
+export function formatTable(points, maxRadius, geoTz) {
+    const lines = [...points.keys()].sort().map((key) => `    ${JSON.stringify(key)}: ${JSON.stringify(points.get(key))}`);
+    const lineage = geoTz === undefined ? '' : `  "geoTz": ${JSON.stringify(geoTz)},\n`;
+    return `{\n  "v": 1,\n  "attribution": ${JSON.stringify(ATTRIBUTION)},\n${lineage}  "maxRadius": ${maxRadius},`
+        + `\n  "points": {\n${lines.join(',\n')}${lines.length ? '\n' : ''}  }\n}\n`;
+}
+/** The geo-tz version a table was built with, if it recorded one. */
+export const tableGeoTz = (table) => {
+    const value = table?.geoTz;
+    return typeof value === 'string' && /^[\w.+-]{1,32}$/.test(value) ? value : undefined;
+};
+/** The `--max-radius` a table was built with, if it recorded one. */
+export const tableMaxRadius = (table) => {
+    const value = table?.maxRadius;
+    return isRadius(value) ? value : undefined;
+};

package/dist/text.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Escape everything outside printable ASCII, so input cannot forge log lines or send terminal control codes.
+ * `keepNewlines` is for the usage text, which tz-at-point wrote itself and which spans lines.
+ */
+export declare const printable: (text: string, keepNewlines?: boolean) => string;
+/** A short, printable rendering of an untrusted value for an error message. */
+export declare function quote(value: unknown): string;

package/dist/text.js

@@ -0,0 +1,16 @@
+/**
+ * Escape everything outside printable ASCII, so input cannot forge log lines or send terminal control codes.
+ * `keepNewlines` is for the usage text, which tz-at-point wrote itself and which spans lines.
+ */
+export const printable = (text, keepNewlines = false) => text.replace(keepNewlines ? /[^\n\x20-\x7e]/g : /[^\x20-\x7e]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+/** A short, printable rendering of an untrusted value for an error message. */
+export function quote(value) {
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = Object.prototype.toString.call(value);
+    }
+    return printable(text.length > 40 ? `${text.slice(0, 40)}...` : text);
+}

package/llms.txt

@@ -0,0 +1,18 @@
+# tz-at-point
+
+> The IANA timezone at a coordinate, exact at the points you list, with no file reads at runtime. Build a small JSON table offline with `npx tz-at-point build`, commit it, and call `createLookup(table)` in serverless code.
+
+tz-at-point is a TypeScript/JavaScript library and CLI for Node 20.19+ or 22.12+. geo-tz is needed only at build time, as a dev dependency.
+
+## Docs
+
+- [README](README.md): overview, install, quick start, troubleshooting
+- [Agent skill](skills/tz-at-point/SKILL.md): the workflow and rules a coding agent should follow
+- [API reference](skills/tz-at-point/references/api.md): `createLookup`, `pointKey`, types and the table format
+- [CLI reference](skills/tz-at-point/references/cli.md): every command, flag, message and exit code
+- [Setup guide](skills/tz-at-point/references/setup.md): points files, JSON imports in TypeScript and bundlers, CI
+
+## Optional
+
+- [Architecture notes](https://github.com/oo-pibe/tz-at-point/blob/main/AGENTS.md): invariants, layout and tests for working on tz-at-point itself
+- [Contributing](https://github.com/oo-pibe/tz-at-point/blob/main/CONTRIBUTING.md): how to propose a change

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "tz-at-point",
+  "version": "1.0.0",
+  "description": "Offline IANA timezone lookup for known coordinates in serverless and edge functions.",
+  "keywords": [
+    "timezone",
+    "iana",
+    "timezone-lookup",
+    "coordinates",
+    "offline",
+    "serverless",
+    "edge-runtime",
+    "geo-tz",
+    "build-time",
+    "lambda",
+    "latitude",
+    "longitude"
+  ],
+  "license": "MIT",
+  "author": "oo-pibe",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oo-pibe/tz-at-point.git"
+  },
+  "homepage": "https://github.com/oo-pibe/tz-at-point#readme",
+  "bugs": {
+    "url": "https://github.com/oo-pibe/tz-at-point/issues",
+    "email": "contact@roadtokickoff.com"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/lookup.d.ts",
+      "default": "./dist/lookup.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "typesVersions": {
+    "*": {
+      "core": [
+        "./dist/lookup.d.ts"
+      ]
+    }
+  },
+  "bin": {
+    "tz-at-point": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "llms.txt"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc",
+    "test": "node --test test/*.test.ts",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@photostructure/tz-lookup": "^11.6.1"
+  },
+  "peerDependencies": {
+    "geo-tz": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "geo-tz": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "esbuild": "^0.28.2",
+    "geo-tz": "8.1.9",
+    "typescript": "^7.0.2"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/tz-at-point/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: tz-at-point
+description: Use when a JavaScript or TypeScript project needs the IANA timezone or local time at latitude/longitude coordinates (venues, stadiums, stores, airports), when geo-tz fails with ENOENT on missing data files in a bundled or serverless function (Vercel, AWS Lambda, Netlify, Next.js), when a raster timezone lookup such as tz-lookup is an hour wrong near a border, or when working with the tz-at-point package, its zones.json table, or output from `tz-at-point build` or `tz-at-point check`.
+license: MIT
+---
+
+# tz-at-point
+
+tz-at-point answers the IANA timezone at a coordinate. `tz-at-point build` resolves your points offline against geo-tz's polygons into a small `zones.json`. At runtime, `createLookup(table)` answers from that table, then from the nearest table entry within its safe radius, then from a bundled raster for everything else. The runtime reads no files.
+
+The messages and signatures below are checked against the package source by its test suite. You don't need to read tz-at-point's `dist/` source: the answers are here and in `references/`.
+
+tz-at-point answers with a zone name, never a UTC offset. Get the offset for a given moment from `Intl.DateTimeFormat` with that `timeZone`.
+
+## When not to use it
+
+- Every point is far from any border and an approximate answer is fine: `@photostructure/tz-lookup` alone is enough.
+- Browser-only code with no build step to produce the table.
+
+## Checklist
+
+Copy this and tick it off.
+
+```
+- [ ] npm install tz-at-point && npm install --save-dev geo-tz   (if geo-tz is in dependencies, this moves it out)
+- [ ] Points file: .csv with `lat` and `lng` header columns, or .json array of [lat, lng] / { lat, lng } (extra fields ignored)
+- [ ] npx tz-at-point build <points> -o <zones.json>        (warnings go to stderr: read them)
+- [ ] Commit zones.json next to the code that imports it
+- [ ] Import the table as JSON and call createLookup(table) once, at module scope
+- [ ] Remove every runtime readFileSync of data files: import them as JSON too (see "Data the function reads")
+- [ ] Handle { zone: null } and treat source 'raster' for a known point as a stale table
+- [ ] CI step 1: npx tz-at-point build <points> -o <zones.json> --check   (a point was added without rebuilding)
+- [ ] CI step 2: npx tz-at-point check <zones.json>                      (table edited, or geo-tz/Node changed)
+- [ ] Once, to see what the table is worth here: npx tz-at-point check <zones.json> --raster
+- [ ] After any geo-tz, tz-at-point or Node version change (npm update included): build --refresh, check, review the diff
+```
+
+## Data the function reads
+
+`tz-at-point build` reads CSV directly, so `build` never needs a converter. The runtime is different: a serverless function can't `readFileSync` a CSV any more than geo-tz can read its data files. If the handler needs the venue list itself, keep that list as JSON, import it, and pass the same JSON file to `build`. One file, so the two cannot drift. Only if people must keep editing a CSV, generate the JSON from it in a script and check both in. If the columns are named differently (`latitude`, `lon`), see `references/setup.md`.
+
+## Migrating from geo-tz
+
+`build` uses `geo-tz/all`, not the default `geo-tz` export, which merges zones that have kept the same clocks since 1970. After migrating, some names change with identical local times: Baarle-Nassau `Europe/Brussels` becomes `Europe/Amsterdam`, Tromsø `Europe/Berlin` becomes `Europe/Oslo`. That is expected, not a bug. To double-check a point, compare with `import { find } from 'geo-tz/all'`, never the default export.
+
+## Runtime rules
+
+```js
+import { createLookup } from 'tz-at-point';
+import table from './zones.json' with { type: 'json' };
+
+const zoneAt = createLookup(table); // once, at module scope
+
+export function localKickoff(lat, lng, utcIso) {
+  const { zone, source } = zoneAt(lat, lng);
+  if (zone === null) return null; // not a coordinate, or no fallback answer
+  return new Intl.DateTimeFormat('en-GB', {
+    timeZone: zone, weekday: 'short', day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit', hourCycle: 'h23',
+  }).format(new Date(utcIso)); // 'Mon 21 Sept, 00:30' on Node 22.12+; punctuation varies with the runtime's ICU
+}
+```
+
+The local date can differ from the UTC date. If the user asks for a time only (`'20:45'`), give them that (`hour`, `minute`, `hourCycle: 'h23'`), but say that late kickoffs fall on the next local day and offer a date field.
+
+```js
+// Tests (not the handler) may read files. Every known point must come from the table:
+for (const v of venues) assert.ok(['table', 'table-near'].includes(zoneAt(v.lat, v.lng).source), `${v.name}: zones.json is stale`);
+// not notEqual(source, 'raster'): that also passes for { zone: null } from bad coordinates
+```
+
+- The JSON import is what puts the table inside the bundle. Reading `zones.json` with `fs` at runtime brings back the serverless file problem.
+- geo-tz is a dev dependency, used only by `build` and `check`. Never import it at runtime.
+- `createLookup` validates the table and throws a `TypeError` if it is malformed. The returned lookup never throws.
+- `source`:
+  - `table`: the point rounds to a table key (4 decimals, a cell about 11m across).
+  - `table-near`: within an entry's safe radius. Correct and normal; not a warning sign.
+  - `raster`: outside the table, approximate near borders. For a point that is in your points file this means the committed table is stale. Worth a test: every known point should resolve with source `table` or `table-near` (the snippet above; not `!== 'raster'`, which a bad coordinate also passes).
+
+## Never
+
+- Hand-edit `zones.json`. Change the points file and run `build`.
+- Run `build` or import geo-tz in a request handler.
+- Use flags that don't exist. `build` takes `-o/--out`, `--check`, `--refresh`, `--max-radius` (multiple of 10, up to 1000, default 250), `-h/--help`. `check` takes the table path, `--raster` and `-h/--help`.
+- Expect `build` to delete entries for removed points. It only adds. To prune, delete `zones.json` and build again.
+
+## Reading the output
+
+| Output | Meaning | Action |
+|---|---|---|
+| `wrote zones.json: N points (M resolved)` | Table written | Commit it |
+| `up to date: 5 points` | No point is missing. The count is table entries, not lines in your points file. `build` never re-validates existing entries; that is `check`'s job | None |
+| `1 point missing from …` (exit 1) | `--check` found points not in the table, or there is no table yet | Run the `run: npx tz-at-point build …` line it prints, commit |
+| `warning: KEY is within 10m of another zone; …` | That entry has radius 0: its whole ~11m key cell answers one zone, even the part across the border. Repeats on every build | Nothing, unless the point should be in the other zone. When both zones keep the same clocks (Amsterdam and Brussels), local times are unaffected either way. To check a specific point, resolve it with `geo-tz/all` yourself |
+| `warning: LAT,LNG is in A, but its key KEY is in B; …` | The point itself is across the border from its rounded key. Printed only when that key is first added, so silence does not prove a point is on its key's side | Lookups there answer B. Nudge the coordinate onto the correct side if it matters |
+| `FAIL KEY: table says A, polygons say B` (exit 1) | Table disagrees with the installed geo-tz (edited, merged badly, or boundaries changed) | `npx tz-at-point build <points> -o <zones.json> --refresh` with the same `--max-radius` you built with, then `check`, review `git diff`, commit |
+| `FAIL KEY: radius Rm reaches another zone` | Boundaries moved closer | Same as above |
+| `FAIL ZONE: not a zone this runtime's Intl accepts` | The Node running `check` is too old for that zone | Update Node. Refreshing won't change the name, unless the same entry also failed with `table says …` |
+| `tz-at-point: …` (exit 2) | Bad arguments or input | Read the message; see references/cli.md |
+
+Exit codes: 0 success, 1 a check found a problem, 2 bad arguments or input.
+
+## References
+
+- [references/api.md](references/api.md): `createLookup`, `pointKey`, types, table format, performance. Open when writing code against the API.
+- [references/cli.md](references/cli.md): every flag, message and exit code. Open when a command prints something not in the table above.
+- [references/setup.md](references/setup.md): points files from other data, TypeScript and bundler JSON imports, CI workflow, upgrading geo-tz, tests. Open when wiring tz-at-point into a project.