The assistant

Every map has an assistant: an agent that helps the learner while they walk the route. It is not a chat window off to the side. It is offered on the thing it would act on, and it answers right there:

Where	Action	What it does
The step in hand (Do, Observe)	Walk me through it	Says what to do and what to see, and lights up the concepts the step touches.
A step’s note, once written	Check what I noticed	Says whether the learner’s observation matches what the step should show.
A concept	Explain for this stage	What the concept is for in the task in hand, not in general.
Each of a concept’s connections	Explain connection	Why the one relates to the other, and what that means in practice.
A region of the map	Summarise this region	What it covers, what on the route passes through it, what can wait.
The reading	What to take away	The two or three things from the reading the stage needs.
The checkpoint	Check my understanding	Asks a few questions, one at a time, and says whether each answer holds.
A goal part	How does this fit?	What it is built from, and which stages build it.
The compass next to the theme	Ask about the map	A free question, with the learner’s position already known.

Every answer can be followed up in place, and each place remembers what was asked there.

It acts on the map

The assistant uses the map the way the learner does. It can point at concepts, which lights them up with a caption saying why; open a concept to read next; and go to a stage when asked. Each answer lists what it touched (“Opened · Velocity”), and a move comes with Back to where you were. When an answer takes the learner to another concept, the answer comes along, above it.

Progress is the learner’s. The assistant can offer to mark a concept read or move on to the next step; the learner answers Yes or Not now. It never writes in the learner’s notes.

Answers say which model wrote them, so they are never taken for the map’s own text. A learner’s note is sent to the model only when they press Check what I noticed, and only that note.

Turn it off, or preset it

Every map has the assistant; each learner picks a provider the first time they ask for help. To turn it off for a map:

export default defineMap({
  // …
  assistant: { enabled: false },
});

Everything in it is optional and none of it is secret:

Field	Holds
`enabled`	`false` turns the assistant off for this map. Default: on.
`provider`	The provider offered first: `openrouter`, `anthropic`, `openai`, `google`, `azure`, `ollama`, `lmstudio`, `custom`.
`model`	The model id to start with; for Azure, the deployment name.
`baseURL`	Azure resource URL, a local server, or your organisation’s OpenAI-compatible proxy.
`instructions`	Said to the model before anything else: house rules, tone, what not to do.
`keyless`	The proxy at `baseURL` holds the key; learners are never asked for one.

validate checks the block: an unknown provider, a baseURL that is not a URL, Azure without its URL and deployment name, or enabled/keyless that are not true or false are errors with an assistant.* path.

Keys stay with the learner

The page calls the provider straight from the learner’s browser; there is no server in between. A key is kept in that browser (on the device, or only for the session, as the learner chooses) and is sent only to the provider it belongs to. A map is a static site, so there is nowhere else for it to go.

If your organisation does not hand out keys, run an OpenAI-compatible proxy that holds one and point the map at it:

assistant: {
  provider: 'custom',
  baseURL: 'https://ai-gateway.example.com/v1',
  model: 'gpt-5-mini',
  keyless: true,
},

Setting up a provider

This is the same guidance the learner sees in the map when they first ask for help.

OpenRouter

One key for models from every vendor, Claude and GPT included.

Sign in, open Keys and press "Create". Copy it now: it is shown once.openrouter.ai/settings/keys ↗
Add credit; most models need it.Credits ↗
Pick a model and copy its id (the vendor/model line under its name). It must support tool calling.openrouter.ai/models ↗
Paste the key and the model id below.

Asks for: API key, Model · default model anthropic/claude-sonnet-5

Anthropic (Claude)

Claude models, billed to your Anthropic Console account.

Sign in to the Claude Console, open API keys and press "Create Key". Copy it now: it is shown once.platform.claude.com/settings/keys ↗
Buy credit under Billing; the API does not work on an empty balance.Billing ↗
Paste the key below.

Asks for: API key, Model · default model claude-sonnet-5

A Claude.ai Pro or Max plan does not include API access; the Console is billed separately.

OpenAI

GPT models, billed to your OpenAI account.

Sign in and open API keys, then press "Create new secret key". Copy it now: it is shown once.platform.openai.com/api-keys ↗
Add credit under Billing. A new account has none, and requests fail until it does.Billing ↗
Paste the key below.

Asks for: API key, Model · default model gpt-5.4-mini

A ChatGPT subscription does not include API access; the API is billed separately.

Google Gemini

Gemini models, with a free tier to start on.

Sign in to Google AI Studio and press "Create API key". Pick or create a Google Cloud project when asked.aistudio.google.com/apikey ↗
Paste the key below.

Asks for: API key, Model · default model gemini-3.5-flash

The free tier has low rate limits; if answers stop mid-way, wait a minute or add billing.

Azure OpenAI

OpenAI models in your organisation's Azure subscription.

Open Azure AI Foundry, then your project, then "Models + endpoints".ai.azure.com ↗
Deploy a model if the list is empty ("Deploy model", then "Deploy base model"). Note the deployment name you give it.
Open the deployment. Copy the Target URI up to and including the host (https://<resource>.openai.azure.com) and the Key.
Paste the URL, the key and the deployment name below.

Asks for: Endpoint URL, API key, Deployment name

The model field is your deployment name, not the model family.

Azure may refuse calls made straight from a browser. If the test says the request was blocked, ask whoever runs your Azure subscription for a proxy URL and choose "Your organisation" instead.

Ollama

Runs on your own machine; nothing leaves it.

Install Ollama.ollama.com/download ↗
Download a model that can call tools.ollama pull qwen3
Quit Ollama if it is running, then start it allowing this page to reach it.Allowing browser access ↗OLLAMA_ORIGINS=https://your-map-address ollama serve

Asks for: Model · default model qwen3 · endpoint http://localhost:11434/v1

Small models follow the map less well; pick the largest your machine runs comfortably.

LM Studio

Runs on your own machine, with a desktop app to manage models.

Install LM Studio and download a model that can call tools.lmstudio.ai ↗
Open the Developer tab, load the model, turn on "Enable CORS" in the server settings and start the server.
Copy the model's id from the Developer tab and paste it below.

Asks for: Model · endpoint http://localhost:1234/v1

Your organisation

An OpenAI-compatible endpoint your organisation runs.

Ask whoever runs your internal AI gateway for its OpenAI-compatible URL (it usually ends in /v1), a key if it needs one, and a model name.
Paste them below.

Asks for: Endpoint URL, API key, Model

Which models work

The assistant calls tools (pointing at the map, opening concepts), so the model must support tool calling. Small local models follow the map less well; the larger the better.

It answers from the map and the model’s own knowledge. It does not search the web.