# bike.tools, for agents

This file is for AI assistants and automated agents that reach bike.tools on
someone's behalf. People should read the help pages instead: https://bike.tools/help

## What this is

bike.tools is a service-counter toolkit for bike shops that run Lightspeed
Retail (R-Series). Its Chrome extension adds free tools to Lightspeed's own
workorder and customer pages (Bike Archive data: bike names, torque specs,
hanger and frame standards; QR codes on printed tags, status buttons, job
presets, a customer panel). Shops can add, each by the month: the Phone tools
(photos, part barcodes and serial numbers from a phone), Status pages (a
private page per workorder for the customer; includes the Phone tools), Custom
branding (the shop's logo, colour and own address on those pages), a Booking
page (online booking that becomes a Lightspeed workorder; includes all of the
above) and AI integration (AI Quick Book, a drafted workorder from one
sentence; includes everything). Shops sign themselves up; there is no approval
step. It is made by Hank Bicycle
Company, and its paid add-ons help fund Bike Archive (https://bikearchive.org),
a non-commercial bike database.

bike.tools does not text customers or run a chat: the status page and the
booking confirmation email are how a shop reaches a rider through it.

Every page is server-rendered HTML that works without JavaScript, so an agent
that reads pages and submits forms needs nothing else.

## Addresses

The pages live on a few hosts. Older paths on `bike.tools` itself redirect to
them, so either form works:

- `bike.tools`: the home page, `/pricing`, and short status links.
- `book.bike.tools/<shop>` (or `bike.tools/b/<shop>`): a shop's booking page.
- `status.bike.tools/<secret>` (or `bike.tools/s/<secret>`): a rider's status page.
- `app.bike.tools`: the shops' own application, sign-in and sign-up.
- A shop with Custom branding can also serve its booking and status pages at
  an address of its own, like `book.yourshop.com`.
- `help.bike.tools` (or `bike.tools/help`): the guide.

## Public pages

- `/help` and `/help/<section>`: the guide. Indexable, no sign-in. Sections:
  start (at `/help`), tools, booking, day-to-day, extension, addons,
  integrations, recommended, troubleshooting, customers, support.
- `/pricing`: the add-ons and their monthly prices, and the free tools.
- `/b/<shop>`: a shop's booking page. Only works for a shop that exists and
  takes online bookings (the Booking page add-on); otherwise it says the shop
  isn't taking online bookings. Shops are not listed anywhere; you need the
  address from the shop.
- `/login`: shop staff sign-in (email, then a password and/or an emailed code).
- `/signup`: shops sign up here (an emailed code, a password, then the shop's
  details at `/shops/new`); the shop is ready at once.
- `/demo`: a made-up demo shop anyone can look around, read-only, no sign-in.
  Its booking page books nothing.
- `/s/<secret>`: a rider's status page. The secret is the key; see below.
- `/<code>` (ten letters and digits, on `bike.tools`): a short status link
  printed as a QR code on the rider's copy of a workorder. It redirects to
  their status page.
- `/p/<secret>`: a shop staff member's phone page for adding photos, a barcode
  or a serial number to one workorder (typed, or read from the camera or a
  photo of a barcode or QR code). It lasts ten minutes and is not for
  agents.
- `/health`: `{ "ok": true }` when the service and its database are up.

Everything under `/admin` is the shop's staff application and needs a staff
session. `/platform` is the operator's own area (the people who run bike.tools)
and needs an operator account; nothing there is for agents. There is no public
or third-party API: `/api/b/<shop>/*` are the booking form's own helpers
(availability by month, bike search, instant quotes) and `/api/ext/v1` is for
the shop's Chrome extension only. They are rate limited per address and may
change without notice. Prefer the HTML pages.

## Helping a rider

To book: open the shop's booking page, choose a location, one or more
services, the bike (search by make, model and year where the shop has Bike
Archive data, or type it), an open drop-off day from the calendar, and the
rider's name with an email or mobile number. The confirmation, with the status
link, goes by email. Submit the form once. The response redirects to the
rider's status page; give the rider that link and nothing else.

To check on a bike: the rider's status link shows the status and the
estimated ready date, and whatever else the shop shares. The link itself is
the key: with it the rider can add photos, propose new contact details, cancel
before drop-off where the shop allows it, and approve an estimate if the shop
allows that. Do any of these only when the rider asked for exactly that.

A booking is a real commitment of a shop's time. Do not book, cancel, approve
or request changes unless the rider asked for exactly that, and never book to
"check availability": the calendar already shows which days are open.

## Helping shop staff

Staff tasks happen in `/admin/<shop>` after a staff sign-in that only a person
can complete (an emailed code, and a password for owners and admins), and in
Lightspeed through the shop's Chrome extension. The help pages describe every
setting, page and tool, so an agent can tell staff where to go and what a
setting does without signing in. The admin's own search (`/` or Ctrl+K) finds
pages, settings, add-ons and help sections by name.

## Status links are secrets

`/s/<secret>` carries a long random key and is the only way into a rider's
page; a short status link leads to the same page. Treat them like a password:
do not index, share, log, summarize into a public place, or send them to anyone
but the rider they belong to. They are marked `noindex`.

## Crawling and indexing

Index `/`, `/pricing`, `/help` and the pages it links to. Everything else is
marked `noindex` or needs a sign-in. Keep requests to a human pace; the rate
limits are sized for a person with a browser, and a burst will get a 429 for a
while. Bike search on the booking page goes to Bike Archive, whose own terms
apply: credit it as "Bike data from Bike Archive" and do not use it for
anything commercial.

## Source and contact

The source is not public. Questions and problems go to the address on
https://bike.tools/help/support. For a question about a specific bike or
booking, the shop is the right contact.