Interactive Map Builder is a Codex-first Agent Skill for turning GeoJSON, GeoPackage,
Shapefile, CSV, Excel, and ArcGIS data into portable map products. The Agent recognizes the goal
from ordinary language—even when the user never says GIS, Leaflet, web map, or the Skill name—then
inspects the data, closes only blocking requirements gaps, writes an auditable MapSpec, resolves
a restrained geometry-aware visual starting point, builds a self-contained Leaflet app, verifies
the result, and exports slide or paper figures only when requested.

User intent + spatial data → inspect → confirm → MapSpec → build → verify → HTML + optional PNG/SVG/PDF

No frontend build system, no hand-written Folium page, and no hidden cleanup.

Highlights

• Intent-based activation — recognizes requests such as “make this spreadsheet searchable on a
  map” or “combine roads, water, green space, and parking in one presentation page.”
• Agent-guided setup — works from the user's question and inspected data instead of requiring
  GIS terminology up front.
• Deterministic builds — the Agent writes MapSpec 1.1; the Python engine owns loading,
  normalization, visual resolution, rendering, and validation.
• Atlas Studio Light defaults — omitted visual values are resolved from geometry, coarse
  density, and layer role so the first result is coordinated without pretending to finish the
  designer's work.
• Two polished map products — a searchable map-and-list explorer and a toggleable multilayer
  explorer for points, lines, and polygons.
• Saved Views in v0.5.0 — save up to eight named map centers and zoom levels in the browser,
  then jump between Overview and key sites during analysis or presentation without changing MapSpec.
• Portable local delivery — Leaflet, interface code, and business geometry are embedded in one
  map.html; only online basemap tiles require a network connection.
• Opt-in report exports — generate 16:9 PNG or publication PNG/SVG/PDF from the same visual
  plan only when those files are explicitly requested.
• Auditable handoff — every build records inspection results, repairs, generated IDs,
  performance warnings, source notes, hashes, and portability.
• Cached, non-mutating release preflight — Skill tasks check the official Release at most once
  per 24 hours, never modify the running installation, and keep offline work unblocked.
• Install self-check — interactive-map-builder doctor runs a complete offline build and hash
  verification after installation.
• Reliable map controls — multilayer maps open in a neutral overview, use one compact layer
  selector for search focus, keep visibility switches separate, and provide CARTO Positron,
  OpenStreetMap Standard, plus a no-basemap fallback.
• Cross-agent evaluation — 40 English and Chinese cases cover activation, optional planning,
  local-versus-public delivery, and out-of-scope requests.

Live demos

Search, filter, compare	Explore independent layers
Map + list. Search addresses and attributes, filter categories and numeric ranges, sort records, watch KPIs update, and inspect a selected parcel.	Multilayer. Start from a neutral overview, choose one layer to search and emphasize, toggle visibility independently, switch basemaps, and inspect feature details.
Open live demo →	Open live demo →

Both demos are generated by the repository's deterministic engine from fixed
NYC Open Data snapshots; they are not separate design mockups.

Ask for the outcome, not the tool

The Skill is designed to activate from requests like these:

This Excel sheet has longitude and latitude. Make a browser page where I can search facilities,
filter by type, click a record, and share the result.

Combine the parcel, road, water, green-space, and parking layers into one planning presentation
map with layer switches and object details.

My colleagues do not have ArcGIS. Turn these existing layers into one HTML file and export a 16:9
figure for the meeting.

The user can still invoke $interactive-map-builder explicitly, but naming the Skill is not
required for a matching Agent task.

Quick start

1. Install the Skill in Codex

Open a new Codex task and send:

$skill-installer Install the Skill from https://github.com/xlbaoxl/interactive-map-builder and install its Python dependencies. Run interactive-map-builder doctor and interactive-map-builder update --preflight after installation.

Create a new task after installation. Restart Codex once only when the Skill does not appear.
Starting with v0.4.3, a repository-copy install can become update-managed automatically only when
all Release-owned files exactly match the checksum-verified official package.

2. Attach spatial data and describe the result

Turn my attached spatial data into a searchable, filterable interactive map. Use English for the map audience and export a 16:9 presentation figure.

The Skill first inspects the inputs, then keeps a compact requirements checklist while choices
remain unresolved:

- [x] Confirmed: supplied by the user or established by the data
- [~] Inferred: proposed by the Skill and easy to revise
- [ ] Needs confirmation: required before the build can start

It asks one consolidated round only for blocking choices such as CRS, template, primary layer,
category meaning, display fields, output formats, and audience locale.

3. Verify the installation

interactive-map-builder doctor
interactive-map-builder update --preflight

doctor creates a temporary coordinate table, builds a map without network access, verifies the
packaged Leaflet resources and output hashes, prints a JSON result, and removes the temporary
files. It does not download basemaps or send usage telemetry. The update command prints structured
JSON containing the local version, official version when known, source, installation type, and
status.
For a cached status-only query, run interactive-map-builder update --check.

Prefer interactive-map-builder doctor after installation. In a source checkout where the console
command is not yet available, use python scripts/cli.py doctor. The internal
python scripts/map_builder.py --help command intentionally lists only build commands and
must not be used to conclude that the package lacks doctor.

Use one active Codex Skill directory rather than keeping duplicate .codex and .agents copies.
A legacy Windows location may be $HOME\.agents\skills; archive it before using the active Codex directory below.

Windows PowerShell

$CodexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME\.codex" }
New-Item -ItemType Directory -Force "$CodexHome\skills" | Out-Null
git clone https://github.com/xlbaoxl/interactive-map-builder.git `
  "$CodexHome\skills\interactive-map-builder"
Set-Location "$CodexHome\skills\interactive-map-builder"
py -m pip install .
interactive-map-builder doctor
interactive-map-builder update --preflight

macOS or Linux

CODEX_ROOT="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_ROOT/skills"
git clone https://github.com/xlbaoxl/interactive-map-builder.git \
  "$CODEX_ROOT/skills/interactive-map-builder"
cd "$CODEX_ROOT/skills/interactive-map-builder"
python3 -m pip install .
interactive-map-builder doctor
interactive-map-builder update --preflight

Every v0.3.1+ GitHub Release publishes:

• interactive-map-builder-skill-vX.Y.Z.zip — a lean Agent Skill package containing SKILL.md,
  Agent metadata, references, the deterministic engine, and its packaged web resources;
• a Python wheel and source archive for conventional package installation;
• SHA256SUMS.txt for release-asset verification and managed Skill updates.

The Skill ZIP intentionally excludes demos, screenshots, tests, and CI files. Extract it into an
Agent Skills directory, run python -m pip install ., then run interactive-map-builder doctor.

Copy the complete repository or the versioned Skill ZIP into a Skill or rules directory that the
client can read, let it load SKILL.md, and install the deterministic engine once:

python -m pip install .
interactive-map-builder doctor

The workflow is client-neutral: inspect data, maintain the requirements checklist, write the
canonical MapSpec, build with the packaged engine, verify, and deliver the complete dist
directory.

Updates, planning, and public deployment

At the start of a Skill task, the Agent runs interactive-map-builder update --preflight from the
Skill root. This is a cached, check-only request: it reuses a valid result for up to 24 hours, never
modifies files, stays silent when the installed version is current, and reports only an available
update or a failed check. Offline access never blocks map construction. Set
IMB_DISABLE_AUTO_UPDATE=1 to opt out.

Applying an update is a separate maintenance action. update --apply and the legacy non-fatal
update --auto --force retain checksum, manifest, exact-copy adoption, local-change protection,
duplicate-root refusal, post-install doctor verification, and rollback.

Versions v0.3.2–v0.4.2 do not contain the copy-adoption fix. An already installed unmanaged copy of
one of those versions needs one official v0.4.3 reinstall. Later compatible releases can then be
adopted and applied automatically.

Updates are transactional: after replacing a verified release, the updater reinstalls the engine
and runs the offline doctor. A failed install or doctor check restores the prior Git commit or the
previous manifest-owned files. Confirmed release metadata is preserved when application fails, so
an Agent cannot silently convert “an update is available” into “no update available.” See
the verified update policy.

For a genuinely complex Codex task—multiple independent layers, several unresolved design choices,
or coordinated HTML/slide/paper outputs—the Agent may suggest Plan mode once as an optional
convenience. It continues inspecting immediately whether or not the user switches, and clear
single-layer requests do not receive the suggestion.

The normal deliverable is a portable local map.html. “Share with colleagues” means sending that
file, not publishing embedded data on the internet. A public URL is discussed only when explicitly
requested, after confirming a hosting target and permission to expose the data. Hosting remains a
separate workflow from map construction.

Atlas Studio Light

Version 0.4 introduces a lightweight visual-default resolver rather than a full automatic design
system. When MapSpec omits low-level visual values, the engine uses geometry family, coarse
feature/coordinate density, template role, and stable draw order to choose a restrained first
render:

• dense point layers use smaller symbols and lower fill intensity;
• lines and polygons receive separate weights, fills, and outlines;
• map-list primary layers stay prominent while context layers recede;
• multilayer maps open with all visible layers at their base style, then focus a layer only after the user selects it;
• HTML, legends, cards, PNG, SVG, and PDF consume the same resolved visual plan;
• automatic categorical colors stop at eight distinct classes instead of cycling into a rainbow.

Explicit MapSpec values always win. The goal is a credible, presentation-ready starting point—not
a replacement for a planner or designer. Users can keep refining color, size, opacity, fields, and
hierarchy through natural-language instructions or direct MapSpec edits. Every inferred decision
is recorded in build_report.json under visual and visual_system.

Choose the right map product

A map-list may also include context layers. With multiple inputs, the Skill never guesses the
business intent from geometry type alone; it asks the user to confirm the template and primary
layer.

Basemaps and multilayer controls

New MapSpec files include two credential-free online basemaps: CARTO Positron as the quiet
default and OpenStreetMap Standard for detailed street context. The selector also includes
No basemap, and repeated tile failures automatically fall back to it, so business layers and
interactions remain usable without tiles. Esri World Imagery can be added only when the user
provides an authorized service URL or token and accepts that browser-delivered credentials can be
visible in the generated HTML.

In the multilayer product, visibility switches are kept in a fixed upper section. The legend is
stacked below them, scrolls when long, and starts collapsed at narrow widths, so a large categorical
legend cannot cover the layer controls.

Supported inputs

The inspection step reports feature count, geometry type, CRS, field samples, likely ID, label,
and category roles, ambiguities, and performance signals before a map is proposed.

Deliverables

A normal build keeps source paths relative to the original project and treats map_spec.json as a
build record. Use --bundle-sources when the deliverable must rebuild independently after it is
moved.

How it works

User request + spatial files
           │
           ▼
       inspect inputs
  CRS · geometry · fields · scale
           │
           ▼
  confirm unresolved intent once
           │
           ▼
        MapSpec 1.1
           │
           ▼
 Atlas Studio Light resolver
 geometry · density · role · order
           │
           ▼
 deterministic Python engine
 load · normalize · render
           │
           ▼
 verify counts, files, QA hooks,
 provenance, hashes, and browser UI
           │
           ▼
  portable HTML + report figures

The packaged JSON Schema is the only
machine-readable MapSpec contract. Canonical keys use snake_case; unsupported fields and schema
versions are rejected instead of being silently migrated.

For one unambiguous layer:

interactive-map-builder run data.geojson --locale en-US --output dist

For an explicit, reproducible workflow:

interactive-map-builder inspect sites.geojson districts.geojson \
  --output inspection.json

interactive-map-builder init-spec inspection.json \
  --template map-list \
  --primary-layer sites \
  --locale en-US \
  --output map_spec.json

interactive-map-builder build --spec map_spec.json --out dist --bundle-sources
interactive-map-builder verify --dist dist

For independent point, line, and polygon layers, use --template multilayer and omit
--primary-layer.

Scope

Interactive Map Builder focuses on existing spatial data → finished map product. It does not
currently provide:

• address geocoding;
• buffers, overlays, routing, site-selection models, or statistical inference;
• vector-tile services or million-feature WebGIS infrastructure;
• offline basemap acquisition;
• CRS guessing from coordinate ranges;
• 3D terrain, buildings, or digital twins;
• general maintenance of an existing custom Leaflet or React application;
• automatic public hosting without an explicit deployment request and data-publication approval.

For large GeoJSON payloads, the build report recommends light or medium geometry simplification
but does not silently switch rendering engines.

Project status

The v0.5.0 release adds browser-persistent Saved Views to both existing map products: save up to
eight named center-and-zoom positions, return to Overview or key sites with one click, and manage
those views without changing MapSpec or the delivered HTML file. MapSpec remains 1.1 and the two
existing template families remain unchanged.

See the changelog for completed work.

Development

python -m pip install -r requirements-dev.txt
python scripts/evaluate_triggers.py validate
python -m pytest -q -m "not browser"
python -m playwright install chromium
python -m pytest -q -m browser

Build the localized demo site and lean Skill package:

python scripts/build_demo_site.py --output _site
python scripts/build_skill_package.py

The CI matrix covers Python 3.9, 3.10, and 3.12, trigger-suite validation, Chromium interaction
tests, wheel creation, the offline installation doctor, a clean out-of-repository build, and the
Skill distribution archive. After a new package version passes main CI, the Release workflow
creates the tag and assets or repairs an incomplete Release without moving an existing tag.

License

MIT