SETUP & HELP

From trailhead to first guide.

Five waypoints. Most teams publish their first verified guide the same afternoon.

  1. Install the kit

    One package: the CLI, the runner, and the MCP server. Runs on any Mac that can reach the app you’re documenting.

    $ brew install walkabout

  2. Pair your runner

    Grab a pairing token from the web app. The runner connects outbound-only — nothing to expose, nothing to firewall.

    $ walkabout runner pair WB-XXXX-XXXX

  3. Capture a session

    A visible window opens on your Mac. Log in however you normally do — magic link, SSO, password. Walkabout keeps only the session.

    $ walkabout session capture prod-login

  4. Author your first guide

    Tell the agent what the guide should teach, from the web app or your MCP client. Review the route it brings back, fix captions, accept.

    > "Write a guide for inviting a teammate"

  5. Publish and gate CI

    Render to your repo, optionally host on walkabout.run, and add the run to CI so a drifting guide fails the build — not your reader.

    $ walkabout render && walkabout run --all

Trail notes

  • Why does the runner need a real Mac?

    Native automation does. WebKit and the macOS accessibility APIs only exist on macOS — it’s also why guides for native apps work at all, which recorder tools can’t do.

  • Do replays cost anything?

    No. Intelligence is spent once, at authoring and healing time. Replay is deterministic code — run it on every push for free.

  • What happens when my UI changes?

    The next run flags the exact step as changed or broken with a diff. You accept the new baseline in one click, or send the agent to heal the step.

  • Where do my guides live?

    In your git repo as Markdown + PNGs (the source of truth), as portable HTML you can host anywhere, and optionally on walkabout.run for stable URLs. Your choice, changeable anytime.

  • Can Walkabout log into my app?

    It never automates a login page. You log in once in a visible window; Walkabout keeps only the resulting session, encrypted on your machine.

  • Is my production data safe?

    Mutating steps are marked and dry-runnable, creation guides use reset hooks, and production environments refuse mutating replays unless you explicitly override.

Stuck on the trail? Write to help@walkabout.run — a human answers within a day.