@globalfishingwatch/skills 0.0.1

package/dist/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@globalfishingwatch/skills",
+  "version": "0.0.1",
+  "description": "Agent skills for the GFW map: encode/decode app URLs for chatbot navigation",
+  "homepage": "https://github.com/GlobalFishingWatch/frontend#readme",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./encode-url": {
+      "types": "./src/encode-url/index.ts",
+      "default": "./dist/encode-url/index.js"
+    },
+    "./decode-url": {
+      "types": "./src/decode-url/index.ts",
+      "default": "./dist/decode-url/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GlobalFishingWatch/frontend.git"
+  },
+  "dependencies": {
+    "tslib": "2.x"
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@globalfishingwatch/skills",
+  "version": "0.0.1",
+  "description": "Agent skills for the GFW map: encode/decode app URLs for chatbot navigation",
+  "homepage": "https://github.com/GlobalFishingWatch/frontend#readme",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./encode-url": {
+      "types": "./src/encode-url/index.ts",
+      "default": "./dist/encode-url/index.js"
+    },
+    "./decode-url": {
+      "types": "./src/decode-url/index.ts",
+      "default": "./dist/decode-url/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GlobalFishingWatch/frontend.git"
+  },
+  "dependencies": {
+    "tslib": "2.x"
+  }
+}

package/src/decode-url/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: decode-url
+description: Decode a GFW map URL into structured context of what the user is currently seeing — route (map/report/vessel/search), visible layers with filters, time range and viewport. Use whenever you receive the user's current URL and need to understand or describe their view, or to modify it (decode, edit the raw state, re-encode with the encode-url skill).
+---
+
+# Decode GFW map URL
+
+```bash
+node scripts/decode-url.mjs '<url or path>'
+```
+
+Accepts a full URL (`https://globalfishingwatch.org/map/...`) or just the path. Output:
+
+```json
+{
+  "route": {
+    "type": "report",
+    "category": "fishing-activity",
+    "workspaceId": "default-public",
+    "datasetId": "public-eez-areas",
+    "areaId": "5682"
+  },
+  "workspaceName": "Default public workspace",
+  "timeRange": { "start": "2025-08-01T00:00:00.000Z", "end": "2026-08-01T00:00:00.000Z" },
+  "viewport": { "latitude": 40.7, "longitude": 12.4, "zoom": 4.7 },
+  "timebarVisualisation": "events",
+  "layers": [
+    {
+      "id": "ais",
+      "name": "Apparent fishing effort (AIS)",
+      "category": "activity",
+      "visible": true,
+      "filters": { "geartype": ["trawlers"] }
+    }
+  ],
+  "report": { "reportBufferValue": 50 },
+  "vessel": { "vesselSelfReportedId": "..." },
+  "search": { "query": "lake aurora" },
+  "raw": {}
+}
+```
+
+How to narrate it:
+
+- `route.type` says where the user is: `workspace` (map browsing), `report` (area report — `areaId` within `datasetId`, e.g. `public-eez-areas`; no `datasetId`/`areaId` = global report), `ports-report`, `vessel` (vessel profile), `vessel-search`, `vessel-group-report`, `user`, `workspaces-list`.
+- `workspaceName` (when present) names a curated workspace: Marine Manager MPAs (`category: "marine-manager"`, e.g. Palau, Galapagos and Hermandad) or global curated reports (`activity-report`, `detections-report`, `events-report`, Deep Sea Mining Watch). Lead with it — "you're looking at the Palau Marine Manager workspace" beats reciting layers.
+- Describe only `visible: true` layers; mention hidden ones only if relevant. Layer `filters` use API values: `flag` is ISO3 (translate to country names), `matched: ["false"]` on detections means dark vessels (no AIS match), `geartype`/`vessel_type` are fleet filters.
+- `timeRange` is the analyzed period; no `timeRange` means the app default (roughly the last year).
+- `raw` is the full parsed workspace state — edit it and feed it back to the encode-url skill (`{"route": <route>, "state": <raw>}`) to produce a modified view that keeps everything else identical.
+
+Requires node >= 23 (uses `module.registerHooks`). In the monorepo run `pnpm nx dist skills` once so `dist/` exists.

package/src/decode-url/decode.ts

@@ -0,0 +1,87 @@
+import type { BaseUrlWorkspace } from '@globalfishingwatch/dataviews-client'
+import { parseWorkspace } from '@globalfishingwatch/dataviews-client'
+
+import type { LayerCategory } from '../encode-url/dictionary'
+import { getLayerInfo } from '../encode-url/dictionary'
+import type { MapRoute } from '../encode-url/routes'
+import { DEFAULT_BASENAME, matchRoutePath } from '../encode-url/routes'
+
+import { HIGHLIGHTED_WORKSPACES } from './workspaces'
+
+export type DecodedLayer = {
+  id: string
+  dataviewId?: string
+  name: string
+  category: LayerCategory
+  visible: boolean
+  filters?: Record<string, unknown>
+  color?: string
+}
+
+export type DecodedMapUrl = {
+  route: MapRoute
+  /** Curated workspace name (marine-manager, global reports…) when the workspaceId is a known one */
+  workspaceName?: string
+  timeRange?: { start?: string; end?: string }
+  viewport?: { latitude?: number; longitude?: number; zoom?: number }
+  timebarVisualisation?: string
+  layers: DecodedLayer[]
+  report?: Record<string, unknown>
+  vessel?: Record<string, unknown>
+  search?: Record<string, unknown>
+  /** Full parsed workspace state, pass it back to encodeMapUrl to reproduce the url */
+  raw: BaseUrlWorkspace & Record<string, unknown>
+}
+
+const pickByPrefix = (state: Record<string, unknown>, prefixes: string[]) => {
+  const entries = Object.entries(state).filter(([key]) =>
+    prefixes.some((prefix) => key.startsWith(prefix))
+  )
+  return entries.length ? Object.fromEntries(entries) : undefined
+}
+
+export const decodeMapUrl = (
+  url: string,
+  { basename = DEFAULT_BASENAME }: { basename?: string } = {}
+): DecodedMapUrl => {
+  const { pathname, search } = new URL(url, 'https://globalfishingwatch.org')
+  const appPathname = pathname.startsWith(basename) ? pathname.slice(basename.length) : pathname
+  const route = matchRoutePath(appPathname)
+  const state = parseWorkspace(search) as DecodedMapUrl['raw']
+
+  const layers: DecodedLayer[] = (state.dataviewInstances || []).flatMap((instance) => {
+    if (!instance?.id) return []
+    const { name, category } = getLayerInfo(instance.id)
+    return [
+      {
+        id: instance.id,
+        ...(instance.dataviewId && { dataviewId: String(instance.dataviewId) }),
+        name,
+        category,
+        visible: instance.config?.visible !== false,
+        ...(instance.config?.filters && { filters: instance.config.filters }),
+        ...(instance.config?.color && { color: instance.config.color }),
+      },
+    ]
+  })
+
+  const { start, end, latitude, longitude, zoom, timebarVisualisation } = state as Record<
+    string,
+    any
+  >
+
+  const workspaceName = route.workspaceId && HIGHLIGHTED_WORKSPACES[route.workspaceId]
+
+  return {
+    route,
+    ...(workspaceName && { workspaceName }),
+    ...((start || end) && { timeRange: { start, end } }),
+    ...(latitude !== undefined && { viewport: { latitude, longitude, zoom } }),
+    ...(timebarVisualisation && { timebarVisualisation }),
+    layers,
+    report: pickByPrefix(state, ['report', 'portsReport']),
+    vessel: pickByPrefix(state, ['vessel', 'visibleEvents']),
+    search: pickByPrefix(state, ['query', 'searchOption', 'infoSource']),
+    raw: state,
+  }
+}

package/src/decode-url/index.ts

@@ -0,0 +1,4 @@
+export * from '../encode-url/dictionary'
+export * from '../encode-url/routes'
+export * from './decode'
+export * from './workspaces'

package/src/decode-url/scripts/decode-url.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import './register-gfw-resolver.mjs'
+
+const url = process.argv[2]
+if (!url) {
+  console.error(`Usage: node decode-url.mjs '<map url or path>'`)
+  process.exit(1)
+}
+
+const { decodeMapUrl } = await import('@globalfishingwatch/skills/decode-url')
+
+try {
+  const result = decodeMapUrl(url)
+  console.log(JSON.stringify(result, null, 2))
+} catch (error) {
+  console.error(error.message)
+  process.exit(1)
+}

package/src/decode-url/scripts/register-gfw-resolver.mjs

@@ -0,0 +1,24 @@
+import { existsSync } from 'node:fs'
+import { registerHooks } from 'node:module'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+// Each skill ships its own self-contained bundle next to it. Resolve it from either layout:
+// - dist/<skill>/scripts (dist output, this skill copied standalone) -> ../index.js
+// - <skill>/scripts (monorepo source, unbuilt) -> ../../dist/<skill>/index.js
+const skillDir = fileURLToPath(new URL('..', import.meta.url))
+const skillName = path.basename(skillDir)
+const SPECIFIER = `@globalfishingwatch/skills/${skillName}`
+const BUNDLE = [
+  path.join(skillDir, 'index.js'),
+  path.join(skillDir, '..', '..', 'dist', skillName, 'index.js'),
+].find(existsSync)
+
+registerHooks({
+  resolve(specifier, context, nextResolve) {
+    if (specifier === SPECIFIER && BUNDLE) {
+      return { url: pathToFileURL(BUNDLE).href, format: 'module', shortCircuit: true }
+    }
+    return nextResolve(specifier, context)
+  },
+})

package/src/decode-url/workspaces.ts

@@ -0,0 +1,34 @@
+import { DEFAULT_WORKSPACE_ID } from '@fishing-map/config'
+
+/**
+ * Curated public workspace names, to describe what the user is looking at.
+ * Sources: apps/fishing-map/data/highlighted-workspaces/{marine-manager,reports}.ts
+ * + public/locales/source/workspaces.json
+ */
+export const HIGHLIGHTED_WORKSPACES: Record<string, string> = {
+  [DEFAULT_WORKSPACE_ID]: 'Default public workspace',
+  // Marine Manager
+  'ascension-public': 'Ascension Island',
+  'fiji-public': 'Fiji',
+  'guyana-public': 'Guyana',
+  'micronesia-public': 'Federated States of Micronesia',
+  'maldives-public': 'Maldives',
+  'niue-public': 'Niue',
+  'palau-public': 'Palau',
+  'tristan-public': 'Tristan da Cunha',
+  'mediterranean-public': 'Mediterranean and Black Sea',
+  'costa_rica-public': 'Costa Rica',
+  'colombia-public': 'Colombia',
+  'panama-public': 'Panama',
+  'cmar_core_mpas-public': 'CMAR core MPAs',
+  'galapagos_and_hermandad-public': 'Galapagos and Hermandad',
+  'rapanui-public': 'Rapa Nui',
+  'revillagigedo-public': 'Revillagigedo',
+  'revillagigedo_mexico-public': 'Revillagigedo (report)',
+  // Curated reports
+  'activity-report': 'Global Vessel Activity report',
+  'detections-report': 'Global Dark Vessel Detections report',
+  'events-report': 'Global Vessel Events report',
+  'deep-sea-mining-public': 'Deep Sea Mining Watch',
+  'deep_sea_mining-public': 'Deep Sea Mining Watch (report)',
+}

package/src/encode-url/MAINTENANCE.md

@@ -0,0 +1,53 @@
+# Maintaining the encode-url skill
+
+Not loaded at skill runtime — this is the prompt/checklist for keeping the skill docs in sync with the app. Run it after changes to the fishing-map state types, URL encoding, or dataview/layer config.
+
+## Update prompt
+
+Paste (or point Claude at) the following:
+
+> Sync the `encode-url` skill docs (`libs/skills/src/encode-url/`) with the app source. Requirements:
+>
+> 1. **Diff params against the documented types.** The four source-of-truth files carry JSDoc on every state field, all under `apps/fishing-map/`: `types/index.ts` (`WorkspaceState`/`AppState`/`QueryParams`), `features/reports/reports.types.ts`, `features/vessel/vessel.types.ts`, `features/search/search.types.ts`. Compare against `references/query-params.md`; add new intent-useful params, remove deleted ones.
+> 2. **Diff every enumerated value.** The "Value sources (for update checks)" table in `libs/skills/src/encode-url/MAINTENANCE.md` maps each param to the exact symbol and file its values were copied from. Read each symbol; diff its values against the doc tables in `references/query-params.md`; fix drift. Add a row for any newly documented enum param.
+> 3. **Coverage policy: curated, not exhaustive.** Document params a URL-building intent can actually use. Internal/auto-generated params stay out of the tables and go in the "never set" footnote near the top of `references/query-params.md` — that footnote is the authoritative list; keep it current instead of documenting those params.
+> 4. **URL param names, not state field names.** A `state` param must match a key in `PARAMS_TO_ABBREVIATED` (`libs/dataviews-client/src/url-workspace/url-workspace.ts`) or serialize under its full name. Known trap: URL param `reportResultsPerPage` vs type field `reportVesselResultsPerPage`. Advanced search fields (`transmissionDateFrom/To`, from `ADVANCED_SEARCH_QUERY_FIELDS` in `libs/api-client/src/utils/search.ts`) are a different namespace from `firstTransmissionDate`/`lastTransmissionDate` (`fTD`/`lTD`).
+> 5. **Layer/instance ids** come from `apps/fishing-map/config/src/workspaces.ts` constants and must resolve in the encoder dictionary `libs/skills/src/encode-url/dictionary.ts` (known trap: the FAO context instance is `context-layer-fao-areas`, not `context-layer-fao`).
+> 6. **Defaults** come from `DEFAULT_WORKSPACE` (`apps/fishing-map/data/config.ts`) and `DEFAULT_REPORT_STATE` (`apps/fishing-map/features/reports/reports.config.ts`) — mark them `(default)` in the tables.
+> 7. **Examples live in two files.** `references/examples.md` holds input recipes; `references/examples-conversations.md` holds conversation transcripts with expected output URLs. Update transcripts if encoder output changes.
+> 8. **Verify, don't trust.** `pnpm nx dist skills`, then run `node scripts/encode-url.mjs` (node >= 23) with inputs exercising every param you touched; confirm expected abbreviations/pass-through names in the output path. Round-trip against the transcripts in examples-conversations.md. Finish with `pnpm prettier --write` on every markdown file touched.
+
+## Value sources (for update checks)
+
+Every enumerated value in `references/query-params.md` is copied from one of these symbols. To check for updates: read each symbol and diff its values against the tables in that file. This table lives here (not in the reference) to keep skill-runtime token cost down.
+
+| Param(s)                                                                               | Symbol                                                                                                                                                             | File                                                        |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| `timebarVisualisation`                                                                 | `TimebarVisualisations` enum                                                                                                                                       | `apps/fishing-map/types/index.ts`                           |
+| `timebarGraph`                                                                         | `TimebarGraphs` enum                                                                                                                                               | `apps/fishing-map/types/index.ts`                           |
+| `visibleEvents`                                                                        | `EventTypes` enum (app toggles use `Gaps = 'gaps'`, not `Gap`)                                                                                                     | `libs/api-types/src/events.ts`                              |
+| `activityVisualizationMode`, `detectionsVisualizationMode`                             | `FOURWINGS_VISUALIZATION_MODES`                                                                                                                                    | `libs/deck-layers/src/layers/fourwings/fourwings.config.ts` |
+| `environmentVisualizationMode`                                                         | `HEATMAP_ID`, `HEATMAP_LOW_RES_ID`                                                                                                                                 | `libs/deck-layers/src/layers/fourwings/fourwings.config.ts` |
+| `vesselGroupsVisualizationMode`                                                        | `FOOTPRINT_ID`, `FOOTPRINT_HIGH_RES_ID`                                                                                                                            | `libs/deck-layers/src/layers/fourwings/fourwings.config.ts` |
+| `vesselsColorBy`                                                                       | `VesselsColorByProperty`                                                                                                                                           | `libs/deck-layers/src/layers/vessel/vessel.config.ts`       |
+| `mapDrawing`                                                                           | `DrawFeatureType`                                                                                                                                                  | `libs/deck-layers/src/layers/draw/DrawLayer.ts`             |
+| `colorRamp`/`color` palette                                                            | `FILL_COLOR_BAR_OPTIONS`                                                                                                                                           | `libs/ui-components/src/color-bar/color-bar-options.ts`     |
+| `reportCategory`                                                                       | `ReportCategory` enum                                                                                                                                              | `apps/fishing-map/features/reports/reports.types.ts`        |
+| `reportActivitySubCategory`, `reportDetectionsSubCategory`, `reportVesselsSubCategory` | `ReportActivitySubCategory`, `ReportDetectionsSubCategory`, `ReportVesselsSubCategory` types (built on `DatasetSubCategory` from `libs/api-types/src/datasets.ts`) | `apps/fishing-map/features/reports/reports.types.ts`        |
+| `reportEventsSubCategory`                                                              | `EventType` (= `EventTypes` values)                                                                                                                                | `libs/api-types/src/events.ts`                              |
+| `reportActivityGraph`                                                                  | `REPORT_ACTIVITY_GRAPH_*` consts                                                                                                                                   | `apps/fishing-map/features/reports/reports.config.ts`       |
+| `reportEventsGraph`                                                                    | `REPORT_EVENTS_GRAPH_*` consts                                                                                                                                     | `apps/fishing-map/features/reports/reports.config.ts`       |
+| `reportVesselGraph`                                                                    | `REPORT_VESSELS_GRAPH_*` consts                                                                                                                                    | `apps/fishing-map/features/reports/reports.config.ts`       |
+| `reportVesselOrderProperty`/`Direction`                                                | `REPORT_VESSEL_ORDER_PROPERTIES`, `REPORT_VESSEL_ORDER_DIRECTIONS`                                                                                                 | `apps/fishing-map/features/reports/reports.types.ts`        |
+| `reportBufferUnit`, `reportBufferOperation`                                            | `BUFFER_UNITS`, `BUFFER_OPERATIONS`                                                                                                                                | `apps/fishing-map/types/index.ts`                           |
+| `vesselSection`, `vesselArea`, `vesselRelated`, `vesselActivityMode`                   | `VESSEL_SECTIONS`, `VESSEL_AREA_SUBSECTIONS`, `VESSEL_RELATED_SUBSECTIONS`, `VESSEL_PROFILE_ACTIVITY_MODES`                                                        | `apps/fishing-map/features/vessel/vessel.types.ts`          |
+| advanced search fields                                                                 | `ADVANCED_SEARCH_QUERY_FIELDS`                                                                                                                                     | `libs/api-client/src/utils/search.ts`                       |
+| `userTab`                                                                              | `UserTab` enum                                                                                                                                                     | `apps/fishing-map/types/index.ts`                           |
+| URL param abbreviations                                                                | `PARAMS_TO_ABBREVIATED` (params NOT listed there serialize under their full name)                                                                                  | `libs/dataviews-client/src/url-workspace/url-workspace.ts`  |
+
+## Doc structure invariants
+
+- Each reference file's header names its source-of-truth files.
+- The "Value sources" table above stays current — symbol + file, no line numbers (they rot). It lives in MAINTENANCE.md, not in the references, to avoid skill-runtime token cost.
+- SKILL.md points agents at the typed JSDoc for params not covered in query-params.md.
+- Format touched markdown with `pnpm prettier --write`.

package/src/encode-url/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: encode-url
+description: Build a GFW map URL (and TanStack Router navigation config) that matches exactly what the fishing-map app generates. Use when the user wants to see, compare or review ocean activity (fishing effort, vessel presence, detections, encounters, loitering, port visits, environment layers), open a report over an area or port, open a vessel profile, or search vessels — and you need to produce the link or in-app navigation for it.
+---
+
+# Encode GFW map URL
+
+Turn a navigation intent into `{ navigation, path }`:
+
+- `navigation`: TanStack Router config (`to`, `params`, `search`) — use to navigate from inside the map app.
+- `path`: path + encoded query string (e.g. `/map/fishing-activity/default-public?...`) — for external navigation prepend the origin `https://globalfishingwatch.org`.
+
+Never hand-build the query string: params are abbreviated (`dataviewInstances`→`dvIn`, `config`→`cfg`, `visible`→`vis`…) and repeated values are tokenized (`~0`). The script does this with the app's own encoder.
+
+## Workflow
+
+1. **Pick the route type** from the user intent (details in [references/routes.md](references/routes.md)):
+   - browse/compare activity on the map → `workspace`
+   - a marine protected area / region with a curated workspace (Galapagos, Palau, Fiji, Mediterranean…) or a global curated report (activity, dark vessel detections, events, deep sea mining) → ids in [references/highlighted-workspaces.md](references/highlighted-workspaces.md) only when marine manager is mentioned
+   - aggregated report over an area (EEZ, FAO, RFMO) → `report` (needs `datasetId` + `areaId`)
+
+- An area report must ALSO include the matching **context layer** as a visible instance so the area outline renders: `context-layer-eez` / `context-layer-fao-areas` / `context-layer-rfmo` / `context-layer-mpa` (pick by area type; dataviewId in [references/layers.md](references/layers.md)), `{ "config": { "visible": true } }`. Missing it drops the area boundary.
+
+- Multiple areas in one report → pass `datasetId`/`areaId` as comma-joined lists of equal length (one datasetId per areaId), e.g. `"datasetId":"public-fao-major,public-fao-major","areaId":"41,87"` → path `/report/public-fao-major%2Cpublic-fao-major/41%2C87`. Adding an area to an existing report = append its dataset+id to both. Re-center viewport (`latitude`/`longitude`/`zoom`) on the combined area set rather than keeping the source values.
+  - port activity profile → `ports-report` (needs `portId`)
+  - vessel profile → `vessel` (needs `vesselId`)
+  - find a vessel by name/MMSI/IMO/owner → `vessel-search`
+  - user account / saved workspaces → `user`
+
+- marine-manager workspaces index → static path `/map/marine-manager` (no state/query at all)
+  - If both a `workspace` (browse on the map) and a `report` (aggregated stats over an area) could serve the intent, return both results — the map view and the report — so the user picks.
+
+2. **Pick layers** as `state.dataviewInstances` using the instance ids in [references/layers.md](references/layers.md). Rules:
+   - A layer the user wants: `{ "id": "<instance-id>", "config": { "visible": true, ... } }`.
+   - Default-workspace layers the user does NOT want (`ais`, `vms` are visible by default) must be included with `"config": { "visible": false }` — otherwise the app shows them anyway. This `ais`/`vms` default is for `default-public` ONLY — a curated workspace (see [highlighted-workspaces.md](references/highlighted-workspaces.md)) bakes in its own different default ids and must be checked there (or decoded live) before assuming.
+   - Generic "fishing" intent → show AIS fishing effort (`ais`) and hide `vms` with `"config": { "visible": false }` unless the user specifically wants VMS. Only keep `vms` visible when asked for VMS/national-fleet data.
+   - Layers not in the default workspace need `dataviewId` too (see layers.md). Versioned dataview slugs take the literal `{PIPE_DATASET_VERSION}` token (e.g. `sar-v-{PIPE_DATASET_VERSION}`) — the script resolves it from the `PIPE_DATASET_VERSION` env variable so URLs always target the latest dataset pipeline version.
+   - Multiple visible instances of the same category (e.g. two fishing-effort layers filtered per flag): give each a distinct color so they're visually separable. `color` and `colorRamp` are one choice — set both to a matching palette entry (ramp id + its paired hex, table in query-params.md); don't repeat a ramp within the category.
+3. **Set filters** in `config.filters` — valid filter ids and enum values per dataset are in [references/filters.md](references/filters.md). Flags are ISO3 codes (`ESP`, `FRA`, `CHN`).
+   - Multiple flags → one instance per flag (each with its own `filters.flag` + distinct color/colorRamp per the rule above), so they compare side by side. Only combine flags into a single instance's `filters.flag` array when the user asks for the combined/total (e.g. "Spain and France together").
+4. **Set the rest of the state** ([references/query-params.md](references/query-params.md)): `start`/`end` (ISO datetimes), `latitude`/`longitude`/`zoom`, and `timebarVisualisation` (`heatmap` for activity, `heatmapDetections` for detections, `events` for encounters/loitering/port visits).
+
+- **Relative time periods**: compute `start`/`end` with plain date math from the current datetime (e.g. "last year" = now minus 1 year → now). The encoder snaps both to the map's interval resolution automatically
+  - **Report viewport = don't set it.** For an area report the tools is going to calculate it dinamycally.
+
+5. **Look up ids when needed**: grep [references/areas.json](references/areas.json) for EEZ/FAO/RFMO area ids and [references/ports.json](references/ports.json) for port ids (large file — always grep by name, never read it whole).
+   - Region not in areas.json → no area `report` possible (needs a real `areaId`). Options: (a) a `workspace` framed by viewport — set `latitude`/`longitude`/`zoom` to your best estimate of the region's center; (b) a **global report** for whole-world stats. Global report = `route.type` `report` with NO `datasetId`/`areaId` (→ `/reports/default-public/report`); set viewport to world (`latitude: 0`, `longitude: 0`, `zoom: ~0.8`, not `0`). A global/whole-world report keeps ALL default-workspace layers VISIBLE (`ais`, `vms`, `presence`, `sar`, `sentinel2`, `viirs`, `encounters`, `loitering`, `port-visits`) — do not hide them and do not include only the one the user named. Use the global report when the user wants aggregated numbers but no specific area matches.
+6. **Run the script**:
+
+```bash
+node scripts/encode-url.mjs '{"route":{"type":"report","datasetId":"public-eez-areas","areaId":"5682"},"state":{...}}'
+# or pipe: echo '<json>' | node scripts/encode-url.mjs
+```
+
+Input shape:
+
+```json
+{
+  "route": {
+    "type": "workspace|report|vessel|vessel-search|ports-report|vessel-group-report|user",
+    "category": "fishing-activity",
+    "workspaceId": "default-public",
+    "datasetId": "...",
+    "areaId": "...",
+    "vesselId": "...",
+    "portId": "...",
+    "vesselGroupId": "..."
+  },
+  "state": {
+    "dataviewInstances": [],
+    "start": "...",
+    "end": "...",
+    "latitude": 0,
+    "longitude": 0,
+    "zoom": 1,
+    "timebarVisualisation": "events"
+  }
+}
+```
+
+`category`/`workspaceId` default to `fishing-activity`/`default-public` when omitted.
+
+Worked examples of real intents → inputs: [references/examples.md](references/examples.md). Real conversation transcripts with expected output URLs: [references/examples-conversations.md](references/examples-conversations.md).
+
+A state param not covered in query-params.md may still exist — the app state types carry full JSDoc: `apps/fishing-map/types/index.ts`, `features/reports/reports.types.ts`, `features/vessel/vessel.types.ts`, `features/search/search.types.ts`.
+
+## Working from an existing map URL
+
+When the input gives a **current map URL** (a follow-up like "and by flag?", "what about other gear types?", "are there non-fishing vessels?"), decode it into the full state first and treat that as the base. Make the **smallest change** that answers the intent, then re-run the encoder on the whole state. Output = input state minus nothing, plus/edited only the user's delta.
+
+- **Preserve everything unmentioned, verbatim.** Params commonly dropped by accident that MUST carry over:
+  - viewport: `latitude`, `longitude`, `zoom` (keep the exact input values; don't recompute).
+  - time: `start`, `end` (change only when the user gives a new period).
+  - report buffer: `rBO`/`rBU`/`rBV` (`reportBufferOperation`/`reportBufferUnit`/`reportBufferValue`).
+  - temporal filters: `fTD`/`lTD` (even when empty — emit `fTD=&lTD=`).
+  - every existing `dataviewInstances` entry at its current visibility (id, category, dvId, color, colorRamp, filters). Do NOT hide, drop, reorder, or strip filters from a layer the user didn't ask to change.
+- **Add, don't replace.** "Also show / are there also X" ADDS a new instance for X while leaving current layers visible — not toggle the current one off.
+- **Minimal filter change, no enumeration.** "Other / the rest / remaining / non-<current>" relative to an applied filter means **clear/broaden that filter** (set it to `''` / remove it) on the existing layer. Never enumerate the complement as an explicit value list, and never fabricate a new layer to hold it.
+
+- **A country/region constraint is an area report, not just a flag filter.** "only in <country>", "restricted to <region>" → convert the route to a `report` over that country's EEZ (grep [references/areas.json](references/areas.json) for its `datasetId`/`areaId`), keeping all existing layers/filters.
+- **Re-encode, never string-edit.** Feed the full decoded+modified state through `scripts/encode-url.mjs`; hand-patching the query string leaves stale/duplicated params (e.g. a stale `zoom`) and skips normalization.
+
+Requires node >= 23 (uses `module.registerHooks`). In the monorepo run `pnpm nx dist skills` once so `dist/` exists.
+
+## Getting it right — priority rules (read first)
+
+These exist because the same mistakes recur. They override any instinct to hand-build.
+
+### 1. Preserve on follow-ups — and the global-report exception is narrow
+
+- Carry over every unmentioned param verbatim: viewport, `start`/`end`, `rBO`/`rBU`/`rBV`, `fTD=`/`lTD=`, and every existing layer at its current visibility/filters.
+
+### 2. Filter-refinement follow-ups modify the existing layer in place — do NOT add a new one
+
+- Questions like "any passenger boats?", "squid jiggers?", "only trawlers?" refine an EXISTING layer: set that filter on the layer already present, keep its id/color/category. Do NOT create a second layer for the filtered subset.
+- Reserve "add a new instance" for genuinely additive intents that introduce a DIFFERENT category or data source ("also show detections", "add SAR").
+- "Other / the rest / remaining / non-<current>" = clear/broaden the existing filter to empty; never enumerate the complement.
+
+### 3. Clearing a filter emits it empty — never drop the key
+
+- To broaden/clear a filter, output it as empty (`geartype=`), not by omitting it. An omitted key scores as `None` and fails; the app expects the empty value. This is a persistent, repeated loss.
+
+### 4. AIS fishing-effort carries a default `distance_from_port_km=3`
+
+- Every AIS apparent-fishing-effort layer (`ais` and `fishing-effort-ais__*`) includes `filters.distance_from_port_km=3` unless the user overrides it. Include it even when the user only mentioned a gear/flag filter.
+
+### 5. Multi-country fishing intent = WORKSPACE with one layer per flag, not a multi-area report
+
+- "Fishing of Peru, Argentina, Brazil and Chile" → a `workspace` with one fishing-effort-ais layer per flag, each with `filters.flag` and a distinct color/colorRamp
+
+### 6. Curated workspaces have their own defaults, and their own EEZ may have a national dataset
+
+- Don't carry the `default-public` assumption (`ais`/`vms` visible by default) into a curated workspace — check its real default ids in [highlighted-workspaces.md](references/highlighted-workspaces.md) (or decode the bare workspace URL) and hide the ones the user doesn't want.
+- If the workspace's EEZ has a national fishing-effort dataset (e.g. Ecuador for Galapagos, Brazil), prefer it over plain global `ais` for that flag/region — pattern in [layers.md](references/layers.md#national-fishing-effort-datasets).
+- Set the viewport to the region's center for a curated `workspace` route (not `0,0`) — the "don't set viewport" rule only applies to `report` routes.

package/src/encode-url/config.ts

@@ -0,0 +1,8 @@
+import { PIPE_DATASET_VERSION as DEFAULT_PIPE_DATASET_VERSION } from '@globalfishingwatch/datasets-client'
+
+export const PIPE_DATASET_VERSION: string = DEFAULT_PIPE_DATASET_VERSION || '4'
+
+export const PIPE_DATASET_VERSION_TOKEN = '{PIPE_DATASET_VERSION}'
+
+export const resolveDataviewSlug = (dataviewId: string): string =>
+  dataviewId.replaceAll(PIPE_DATASET_VERSION_TOKEN, PIPE_DATASET_VERSION)