# AI search

> Let readers ask questions in plain language and get answers drawn from your docs, with links to the pages behind them.

AI search adds **Ask AI** to your site: a chat beside your docs. Readers ask a question, Typemark answers from your published docs and lists the pages it used, and they can keep asking follow-ups. It's available on Pro and Enterprise.

## Turn it on

Go to **Settings** > **Reader features** and turn on **AI search**. Search has to be on too: without it, readers don't see Ask AI.

In `typemark.json`:

```json
"features": {
  "search": true,
  "ai_search": true
}
```

The plan that counts is the project owner's, so everyone on the team gets the same site. On the Free plan, the toggle shows a **Pro** badge and readers don't see Ask AI.

## What readers see

**Ask AI** in the site header opens a chat panel docked on the right of the page. On phones it fills the screen.

- The answer streams in, with a **Sources** list under it of the pages it drew on. Each source links to its page, and so do page titles cited in the answer.
- Readers can ask follow-up questions, like "and on Windows?". Typemark keeps the last few questions and answers in mind.
- **Stop** ends an answer that's still coming. **New chat** starts over.
- Opening a cited page keeps the conversation, so readers can read the page and carry on asking.
- <kbd>Esc</kbd> or the close button closes the panel.

Readers can also start from search. In the search dialog, the **Ask AI** row at the bottom hands whatever they typed to the panel. <kbd>Cmd</kbd>+<kbd>Enter</kbd> (<kbd>Ctrl</kbd>+<kbd>Enter</kbd> on Windows) does the same from anywhere in the dialog. On phones, that's how readers open Ask AI.

Questions can be between two and 500 characters long. On a site in [several languages](https://docs.typemark.dev/configuration/languages), Ask AI answers from the default language. [Preview deployments](https://docs.typemark.dev/github/previews) don't have Ask AI.

## How answers are made

<Steps>
  <Step title="Find the pages">
    Typemark runs the question through your site's full-text search and takes the five best-matching pages. For a follow-up, it tops these up with pages that matched the earlier questions.
  </Step>
  <Step title="Answer from those pages only">
    The model gets the text of those pages and is told to answer only from them, to cite pages by title, and to say so when the answer isn't there.
  </Step>
  <Step title="Show the sources">
    The matching pages are shown as sources before the answer starts, so readers have somewhere to go even if the answer falls short.
  </Step>
</Steps>

Answers use your published content. In [manual deploy](https://docs.typemark.dev/configuration/publishing#manual-deploy) mode, unpublished edits aren't used.

If no page matches, readers are asked to rephrase instead of getting an answer.

## Privacy

Questions and page text go to the AI model through OpenRouter. Typemark only routes them to model providers that don't store prompts or train on them.

## Limits

| Limit | What happens |
|-------|--------------|
| 10 questions per minute per reader | Further questions get a "try again in a minute" message. |
| 300 AI answers per site per day | Readers still get the matching pages, with a note that AI answers are paused for today. Answers resume the next day. |
| 500 AI answers per day across all of an owner's sites | The same, on each of that owner's sites. Answers resume the next day. |
| 30 seconds per answer | Readers are asked to try a simpler question. |

## Tips for better answers

- Give every page a clear `title` and `description`. Both are searched, and they help the right pages rank first.
- Use the words your readers use. Search matches words, so a page about "API keys" won't be found for "access tokens" unless it says so.
- Keep pages focused. Each source page contributes a limited amount of text, so one topic per page works better than one long page.
