Trailgen

Trailgen is a native Rust workbench for finding, drawing, inspecting, and keeping long-day hiking routes. The GUI is the product frontend. Its vector map, trail acquisition, route search, editor, project Library, and GPX export share one engine.

Install

cargo install trailgen --locked
trailgen

Cargo places the unified trailgen binary under its configured binary root. For a checkout build, ./scripts/install-local.sh installs the same binary beneath ~/.local/bin. Bare trailgen resumes the last chosen project or opens the project deck. New projects conventionally live beneath the host platform's Documents directory in trailgen/; Trailgen honors the directory reported by the operating system and never invents a Linux ~/Documents.

Trailgen is release-tested on Linux/X11, Linux/Wayland, macOS on Apple and Intel silicon, and 64-bit Windows. Linux delivery is the ordinary Cargo install above. Releases also carry an unsigned universal macOS disk image and an unsigned current-user Windows installer; Gatekeeper or SmartScreen may therefore require an explicit user override.

Projects are portable directories rooted by trailgen.toml. Project content, including the canonical saved-trail Library, stays in that directory. View and window state belongs under $XDG_STATE_HOME/trailgen, app-wide preferences under $XDG_CONFIG_HOME/trailgen, and shared map cache under $XDG_CACHE_HOME/trailgen.

Workflow

1. Create a project and pan to its territory.
2. Draw one or more bronze-framed map areas. Trailgen acquires and indexes their union.
3. Draw a trail directly from support points, or place a trailhead and search by distance, moving time, climb, target lower-limb load, and shape.
4. Inspect a trail on the full map and elevation profile. Save it when it deserves durable project identity.
5. In Saved Trails, press ↥ beside its name to export GPX. Unsaved candidates and unfinished edits cannot be exported.

The GPX carries one contiguous hiking track, the Library name, elevations where known, and the saved measurements in its description. Upload that file to AllTrails as a custom route, then open it under Saved → Lists → Custom routes & maps for navigation. See the AllTrails handoff.

The default US corpus combines OpenStreetMap/Overpass, USGS National Digital Trails, spatially applicable state-park authorities, and cached Mapzen terrain tiles. New York and Texas are the first admitted state providers. Provider responses are independently sequestered beneath sources/, fingerprinted, and rebuilt through one graph path before cache/graph.bin becomes ready. Informal standing, wayfinding, terrain, and legal access remain distinct facts. See data sources.

Keyboard

F1 or ? opens the generated command guide for the current workspace. An underlined letter is an Alt mnemonic. Tab and Shift+Tab traverse controls inside the active inspector panel; physical Control+Tab and Control+Shift+Tab move between panels on every platform. Primary shortcuts use Command on macOS and Control elsewhere.

Trailgen declares typed commands once. The same declaration routes their accelerators, supplies button labels and mnemonic underlines, and populates the guide with current availability and refusal reasons. Map gestures and other target-relative interactions remain in the guide without pretending to be global commands.

Debug Shell

The shell is deliberately incomplete. It exposes only operations already owned by the GUI application service:

trailgen gui [PROJECT] [--offline]
trailgen saved PROJECT
trailgen export PROJECT --trail NAME_OR_ID --output route.gpx

Bare trailgen and trailgen gui launch the same native workbench. saved prints durable Library identities and names. export invokes the same saved-trail GPX writer as the ↥ control; it does not regenerate, reinterpret, or select transient candidates. New shell commands belong here only when a concrete debugging need appears and shared product logic already owns the operation.

Verification

scripts/check
scripts/audit
scripts/verify-install
scripts/test-gui
scripts/test-wayland

scripts/verify-install proves a sterile non-default install and Cargo-tracked uninstall. scripts/test-gui is the hermetic X11 acceptance gate. Its complete user stories cover GUI project creation and provider acquisition, saved-trail refinement and restart, twelve-candidate comparison under cadence budgets, manual trail design, saved GPX export, and productive work while graph armament is deliberately stalled. It also proves generated-help presentation, modal key isolation, and inspector-panel traversal. scripts/test-wayland owns the narrower isolated Wayland contract: native launch, first presentation, semantic witness, and nonblack compositor capture.

scripts/package executes a locked workspace package transaction for every publishable crate without relying on already-published internal versions. scripts/release VERSION publish requires the pushed commit and a valid signed tag, repeats every gate, publishes the five-crate graph in dependency order, then verifies the complete registry-resolved package graph. The pinned Foundry workflow publishes the unsigned native artifacts and a machine-readable support receipt only after the declared proof graph passes.

See installation, project state, model, physical load and moving time, and known limitations.

License

Licensed under either Apache-2.0 or MIT, at your option.