Build your fleet by photographing each car — AI instantly identifies the car type, reporting marks, road number, and color.

• Click + Add Car via Photo to photograph or upload an image. AI fills in all fields automatically.
• Click 🗄️ Select From Library to pick from previously uploaded photos.
• Use ✨ Generate Stylized Illustration to create an artistic rendering of your car.
• Click + Add Car Manually to enter car details without a photo. Select a car type and, if a default image has been assigned to that type, a banner will offer to use it automatically.
• Cars without a personal photo display their car type's default image on the roster grid, detail view, and operations list — if one has been assigned in Layout Setup → Car Types.
• Click any car card to open its full details: waybills, movement history, location.
• Edit or delete a car from its detail view. Deleting a car removes all associated waybills and movement history.

Waybills route cars between locations. Each car can have up to 4 sequential waybill slots — a full operating cycle.

• Open a car's detail view and use the Waybills tab to add, edit, or reorder waybill slots.
• Each waybill defines: origin, destination, industry, commodity, and whether the car travels loaded or empty.
• Use Generate Waybills (Waybills tab) to automatically create waybills from your layout industries.
• Use Auto-Assign to match unassigned waybills to available cars by type and routing logic.
• Define commodity rules (e.g. grain → covered hopper) in Layout Setup to guide auto-assignment.
• At session end, each car's active waybill slot advances automatically to the next slot.

Define the geography of your model railroad: locations, industries, car types, and commodity rules.

• Locations have four types: Yard (staging hub), Industry (car destination), Staging (off-layout staging), Storage (parked cars awaiting assignment).
• Industries are attached to locations and have a role:
  • Consumer — receives loaded cars inbound; define inbound car types and inbound commodities.
  • Producer — ships loaded cars outbound; define outbound car types and outbound commodities.
  • Transload — both receives and ships; configure both inbound and outbound fields.
• Use ✨ AI Suggest next to any industry name to let AI fill in role, commodities, and accepted car types automatically. AI reuses existing commodity names where possible.
• Car Types — add or remove car types available in the roster. Each car type can have a default image assigned from the Photo Library; this image is shown for any car of that type that has no personal photo.
  • Bundled default images in static/images/car-types/ are assigned automatically at startup (named by car type, e.g. boxcar.png).
  • Use Set image on any car type row to pick a different image from the Photo Library.
  • Use Clear to remove the assignment; the bundled default will be restored on next server restart.
• Commodity → Car Type mappings tell the auto-assign system which car type to use for each commodity.
• Use ✨ next to any commodity to get an AI suggestion for the correct car type.
• Use ⚙ Seed Defaults to populate a starter set of commodity→car-type mappings.
• Configure the Fast Clock start time and speed in the Fast Clock section at the bottom.

Run a realistic ops session from plan to wrap-up. The Quick Op Session tab drives the session lifecycle.

• Click 🚆 Start Quick Op Session to generate the session's switch list from current car positions and waybills.
• The switch list is divided into three groups: Set out from staging (cars arriving at industries), Cars to spot (storage cars needing placement), and Pick up for staging (cars departing industries).
• For each car, tap Done when the car has been moved to its destination, or CP (Car Placement) to temporarily park it at another location.
• Click any car thumbnail to open its full detail view mid-session.
• When all cars are worked, click ⬛ End Session. Waybill slots auto-advance and car locations update.
• CP cars require you to assign a location before the session can end.
• Use ✕ Cancel Session to abandon a session without saving any moves.
• Session state persists across browser refresh — pick up where you left off.

The fast clock simulates prototypical railroad time during a session. A 4× clock means 15 real minutes = 1 model hour.

• Configure Start Time and Speed in Layout Setup → Fast Clock section.
• Speed options: 1× (real time), 2×, 4×, 6×, or 12×.
• The clock starts automatically when you begin a session. If another session is already running (on another browser or tab), the existing clock continues — it is not reset.
• Click ⏸ to pause the clock; click ▶ to resume.
• Click ↺ to reset the clock back to the configured start time. All connected browsers re-sync within 15 seconds.
• Clock state is stored on the server — refreshing the page resumes the clock from the correct model time.
• The clock stops automatically when the session ends or is cancelled.

WAYPOINT uses AI in several places to reduce manual data entry. All AI features require an API key configured in your .env file.

• Car identification — Upload a photo of a car and AI identifies type, reporting marks, road number, and color.
• Stylized illustration — The ✨ AI panel on the car add/edit form generates an artistic rendering using an image-generation model.
• Industry suggest — The ✨ AI Suggest button in the industry form fills in commodities, car types, and role based on the industry name.
• Commodity suggest — The ✨ button in the commodity mapping form suggests the correct car type for any commodity.
• Supported providers: Gemini (default), Claude (Anthropic), GPT-4o (OpenAI), or a local Ollama model. Set VISION_PROVIDER in .env.
• AI calls automatically retry on transient provider errors (rate limits, overloads) before failing.

Use Import Cars in Layout Setup → Data to bulk-load your roster from a CSV file or a JMRI roster XML export.

• Column order does not matter — the importer matches columns by header name.
• Required columns (rows missing either are skipped):
  • Reporting marks — header: reporting_marks, road, marks, or railroad
  • Car number — header: car_number, number, no, or num
• Optional columns:
  • Car type — header: car_type, type, or kind
  • Color — header: color or colour
• Example minimal CSV:
  road,number
UP,12345
BNSF,98765
• Import shows a preview before committing. Choose Skip duplicates or Replace for cars already in the roster.
• For JMRI XML, export your roster from JMRI (File → Export Roster) and import the resulting .xml file directly.

The Photo Library stores all uploaded images and bundled car type defaults. Access it from Layout Setup → Data → Photo Library.

• Click ⬆ Load File(s) to upload one or more images at once — select multiple files in the file picker.
• Images marked in use (blue badge) are attached to a car. Images marked default (green badge) are the bundled car type defaults.
• To delete uploaded images, click thumbnails to select them (a checkmark appears), then click 🗑 Delete Selected and confirm. Default images cannot be selected for deletion.
• 🗑 Purge Unused removes all uploaded images not currently assigned to any car or car type default in one step.
• Images assigned to a car or set as a car type default are always protected from purge.
• When opened via Set image in Car Types, clicking a thumbnail assigns it as the default for that car type and closes the library.

The Virtual Dispatcher builds capacity-aware consists and manages multiple trains simultaneously from the Operations tab.

• Building a consist — select an origin (staging yard) and a switching area, then click + Build Consist. The dispatcher finds cars at the origin whose waybill points into the switching area (setouts), and cars already in the area whose waybill points back to a yard (pickups). The inbound count is capped by available spots.
• Multiple consists — you can build as many consists as needed. Each appears as a collapsible card. Cars claimed by one consist are automatically excluded from others.
• Capacity math — available spots = capacity − cars currently in area + cars being picked up this run.
• Train identity — expand a consist card to assign a train number, name, departure time, engineer, and conductor. Click Save Identity to persist.
• Assign power — expand the card and select locomotives (and optionally a caboose). The same locomotive cannot be assigned to two consists. Start Session is disabled until at least one locomotive is assigned.
• Operations mode — set the layout protocol in Layout Setup (Free, TT&TO, or TWC). This changes the label on the special instructions field in each consist card.
• Starting a session — click Start Session on a consist card to hand it off to the Quick Op workflow. Setouts appear as arrivals; pickups appear as departures.
• Rebuild — click ↺ Rebuild to refresh the car list for a consist while keeping its identity and power assignment.
• Layout Status — the strip at the top of the Operations tab shows current car counts for every switching area and yard. Click any row to expand and see individual cars with their destinations.

Export and restore your entire layout — locations, industries, cars, waybills, photos, and movement logs — in a single ZIP file.

• Use Export Backup in the Layout Setup Data section to download a complete snapshot.
• Use Import Backup to restore from a ZIP. This replaces all current data.
• Backups are useful for sharing layouts with other operators or recovering from errors.
• Each car's detail view shows its last 5 movements with timestamps and notes.