> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md).

# Snapfix AI

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). Platforms: web, iOS and Android. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/ai/assistant.md).
{% endhint %}

Chat with Snapfix AI (Simon) about the site: ask questions, tap suggested prompts, answer its questions and open the tasks it creates and the documents it cites.

![Snapfix AI](https://3653879137-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FsVVGa79QbcEkJ7n8srxe%2Fuploads%2Fgit-blob-e3dc48b13fa7493e48418f4e42926970e10f1315%2Fassistant.png?alt=media)

* **Where:**
  * web: the round "Snapfix AI" button at the top right of every page of the app, shown while the panel is closed. It opens a panel on the right, over the page (web\_app\_v2 @ 0989b8e685, `src/app/app.component.html:25-28`, `src/app/pages/simon/simon-fab/simon-fab.component.html:1-20`). Full-screen pages such as [Source document](https://docs.snapfix.com/how-the-apps-work/screens/ai/source-document.md) have no button.
  * iOS: the round Snapfix AI button in the shared top bar of the main screens, on Home, on the chat tab (which has its own copy; the shared bar's copy is hidden there) and on the task page (ios @ aa31967ac8, `SnapFix/TopNavigationBarView.swift:69-72`, `SnapFix/Storyboards/NewHomeSB.storyboard:189`, `SnapFix/Storyboards/MyNetworkSB.storyboard:838`, `SnapFix/Storyboards/MessageSB2.storyboard:238`). It opens the chat as a card over the current screen (`SnapFix/SimonAI/SimonAIHostingController.swift:13-24`, `:84-89`).
  * Android: the Snapfix AI icon in the top bar of the group list and of a group's task list (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:1729-1731`, `app/src/main/java/gmail/com/snapfixapp/activity/TaskListingActivity.java:2340-2347`). It opens the chat as a sheet over the screen, which grows out of the icon (`app/src/main/java/gmail/com/snapfixapp/activity/SimonAiActivity.kt:236-258`, `:300-336`).
* **Who:** every signed-in member of a site where Snapfix AI is on; no role changes the screen. The switch is `fAiAgentEnabled` in [tPri\_SettingsParent](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md), and no repo has a way to turn it on \[[ASK-181](https://github.com/snapfix/docs/blob/main/ASK.md#ask-181-who-switches-snapfix-ai-and-snapfix-recommends-on-for-a-site)].
  * web: the site's `aiAgentEnabled` setting is on, no multi-site is selected and the account list has loaded (web\_app\_v2 @ 0989b8e685, `src/app/services/simon/simon-helper/simon-helper.service.ts:66-73`). When the switch goes off, an open panel closes.
  * iOS: the selected site's `fAiAgentEnabled` is 1 (ios @ aa31967ac8, `Models/UserParent.swift:192-226`), checked again on each tap.
  * Android: the same setting, as stored on the phone, is 1 (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/SimonAiAvailability.kt:12-24`).
  * Debug builds show the button on every site: on iOS only in the simulator, on Android in every debug build.
  * Simon acts on the Snapfix APIs as the signed-in user. Its own checks are in the [AI API](https://docs.snapfix.com/engineering-reference/api/ai.md#post-simonchatstream), which describes the v2 agent: it reads the user from the sign-in token without checking its signature, and checks that the user has groups at the site, except while the site's details are cached or when the lookup fails. The production agent's checks were not read \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].
* **Feature:** [Snapfix AI](https://docs.snapfix.com/product/features/ai/snapfix-ai.md). Suggestions while a task is created are a different feature, [Snapfix Recommends](https://docs.snapfix.com/product/features/ai/snapfix-recommends.md).

Production (`ai-agent.snapfix.com`) runs the older Simon agent, `snapfix-taskops-agent` 0.2.0, whose code is on the `refactor/development` branch (snapfix\_ai\_agent @ bcbd010 (refactor/development), `app/api/simon.py`, `app/modules/brand_standards/router.py`). The test host runs the v2 rewrite on `main` (e5e18caef5), which most of the [AI API](https://docs.snapfix.com/engineering-reference/api/ai.md) describes (merge probe, 2026-11-14) \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]. This doc describes the apps against production; where v2 will change what users see once it replaces production, the doc says so.

## Layout

### Web

A panel fixed to the right side of the window, over the page (`src/app/pages/simon/simon-panel/simon-panel.component.html:1-9`). Top to bottom:

1. **Header.** The pen icon and "Snapfix AI", a "Refresh" button that starts a new chat and a "Close" button.
2. **Conversation.** With no messages, the empty state (see [States](#states)). Otherwise the messages, oldest first, each answer with its cards and chips. Older messages load when the user scrolls to the top. While a reply is pending, the thinking indicator shows below the last message.
3. **Question card**, when Simon asks questions ([Question card](#question-card)).
4. **Message box.** "Message Snapfix AI..." and a "Send" button. The attachment and camera buttons are in the template but commented out (`simon-panel.component.html:122-135`, `:150-162`).

### iOS

A card inset over the current screen, which stays visible and dimmed behind it. Tapping the dimmed area does nothing; only the close icon closes the card (ios @ aa31967ac8, `SnapFix/SimonAI/SimonAIView.swift:43-47`).

1. **Header.** "Snapfix AI", a refresh icon that starts a new chat and a close icon. Neither icon has an accessibility label.
2. **Conversation**, or the empty state.
3. **Above the composer:** a card of choices when Simon asks one question or offers a step of choices, or the question wizard when it asks several questions (`SimonAIView.swift:163-171`, `SimonAIViewModel.swift:158-164`).
4. **Composer.** A text box, "Message Snapfix AI...", of up to three lines; a send button that appears beside it once there is text; and a microphone at the end of the bar that records while it is held (`SnapFix/SimonAI/Subviews/SimonAIComposerView.swift:17-22`, `:51-58`). Screen readers call the microphone "Record" in every language. A "Done" bar sits above the keyboard.

### Android

A sheet over the current screen, which stays visible and dimmed behind it.

1. **Header.** "Snapfix AI", a "New chat" icon and a "Close" icon.
2. **Body.** The empty state or the message list. While a question is open, the question card sits under the list.
3. **Voice error line**, above the input bar, for four seconds after a voice error (`SimonAiActivity.kt:585-590`).
4. **Input bar.** A text box, "Message Snapfix AI...", of up to three lines, whose keyboard key sends; a voice button (described as "Voice note") while the box is empty; and a send button once there is text (`app/src/main/res/layout/activity_simon_ai.xml:285-336`, `SimonAiActivity.kt:652-657`). Screen readers call the send button "Snapfix AI".

### Cards in an answer

* **Task cards.** When Simon prepares or creates tasks, the answer shows each task with rows such as "Group", "Room", "Area", "Priority", "Assign to" and "Status". On the web these labels are written in English in the code (web\_app\_v2 @ 0989b8e685, `src/app/services/simon/simon-helper/simon-helper.service.ts:286-296`). The web's intro is "Here is the task you requested" or "Task successfully created" for one task, and "Here are the tasks you requested" or "{N} Tasks successfully created" for several, with a "Task created" or "Tasks created" divider above created tasks. A created task has "View Task". Several created tasks also have "View All {N} Tasks", which opens the group's task list, or `/fix` when the tasks are in more than one group (`src/app/pages/simon/simon-task-card/simon-task-card.component.ts:21-52`). The apps word their cards in their own string files.
* **Bulk review.** When Simon proposes one task per room, the answer lists them; each then shows as created, or with an "Error" row, as the results arrive (`simon-helper.service.ts:252-280`).
* **Document cards.** One card per cited document, with its name, a format label and "View document", which opens [Source document](https://docs.snapfix.com/how-the-apps-work/screens/ai/source-document.md). The web labels each card by the file's extension; iOS and Android label every card "PDF". Production sends these cards: on the live web, an answer about the QA site's brand standards showed one for a PDF ([live notes](https://github.com/snapfix/docs/blob/main/notes/crawl/ai.md)) \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]. The v2 agent sends no document sources (snapfix\_ai\_agent @ e5e18caef5, `src/api/models.py:162-171`), so the cards will stop once it replaces production \[[ASK-180](https://github.com/snapfix/docs/blob/main/ASK.md#ask-180-which-service-indexes-and-serves-the-brand-standards-documents-and-does-it-check-the-callers-site-and-group)].
* **Chips.** Follow-up suggestions and choices appear under the answer. A chip shows its label and sends its value. Tapping a choice ticks it and hides the other choices under that answer; sending a new message removes the choices nobody picked (`src/app/pages/simon/simon-panel/simon-panel.component.ts:235-241`, `:730-735`; `src/app/pages/simon/simon-message-list/simon-message-list.component.ts:156-162`).

## Inputs

| Field                   | Type                                      | Required                      | Default | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------- | ----------------------------------------- | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Message Snapfix AI..." | Text, several lines                       | Yes, to send                  | Empty   | Trimmed; blank text is not sent. Disabled while a reply streams and, on the web, while a chat is restored. Web: Enter sends, Shift+Enter starts a new line (`simon-panel.component.ts:326-341`). No app limits the length. The v2 agent refuses a message over 4,000 characters ([POST /simon/chat/stream](https://docs.snapfix.com/engineering-reference/api/ai.md#post-simonchatstream)), and the web then offers a "Retry" that fails the same way; the production agent's limit was not read \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].                                                                                                                                                                                     |
| Answer to a question    | Choice, or text after "Something else..." | Every question, before "Send" | Empty   | Web: "Send" stays off until every question has an answer (`simon-panel.component.ts:127-131`); in single-answer mode a tap sends at once (`:280-284`). "Something else..." turns into a text field, "Write something else...", and Enter keeps the text. iOS: "Send" once every question has an answer (`SnapFix/SimonAI/SimonAIQuestionWizard.swift:60-63`). Android: "Send" only on the last question, once every question has an answer (`app/src/main/java/gmail/com/snapfixapp/utils/SimonQuestionCard.kt:210-215`).                                                                                                                                                                                                                                                                                      |
| Voice                   | Hold to talk                              | No                            | Off     | iOS and Android only. Hold the microphone: the words heard show as your message while you speak and are sent when you let go. Slide left to cancel (64 points on iOS); the bar shows a timer and "Slide To Cancel". Android: when a reply is still streaming, the words go into the text box instead (`SimonAiActivity.kt:554-566`), and a press shorter than a second shows "Hold to record, release to add". The phone's speech recognizer makes the text, and no audio goes to Snapfix; on iOS the recognition may run on Apple's servers, because on-device recognition is not required (`SnapFix/SimonAI/SimonAISpeechRecognizer.swift:45`). Messages: "We couldn't hear anything. Try again.", "We couldn't transcribe your voice note." and, on Android, "Connection lost. Please check your internet." |
| Photo on a question     | Image                                     | No                            | None    | Android only: on a free-text question, the camera ("Add photo") adds a placeholder picture that is never sent. Photos and files cannot be sent anywhere else.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## Actions

| Action                                                             | Who                                                                            | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open                                                               | Any member                                                                     | Web: when the browser tab holds a chat ID for the site, a loader covers the panel while the chat is checked and its newest 20 messages load, as text only \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]. With no chat ID, an empty chat, or a failed restore, the panel asks for the starter chips. iOS: asks for the site's newest chat, then its newest 20 messages, and adds the cards and chips from the phone's copy when that copy is of the same chat; with no chat it asks for the starter chips (ios @ aa31967ac8, `SnapFix/SimonAI/SimonAIViewModel.swift:330-361`) \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]. The v2 agent has no `GET /simon/sessions`, so iOS will start a new chat at each open once v2 replaces production. Android: reuses the chat while the app runs; after a restart it restores the chat's recent turns as text, the ones the agent keeps for the model (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/model/simon/SimonSessionPayloads.kt:34-72`; snapfix\_ai\_agent @ bcbd010 (refactor/development), `app/api/simon.py:124-162`) \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]. v2 returns no turns, so the restored chat will come back empty. With nothing to restore it asks for the starter chips. | Web: [`GET /simon/session/{session_id}`](https://docs.snapfix.com/engineering-reference/api/ai.md#get-simonsessionsession_id), then [`GET /simon/messages`](https://docs.snapfix.com/engineering-reference/api/ai.md#get-simonmessages). iOS: `GET /simon/sessions?limit=1` ([AI API, Simon versions](https://docs.snapfix.com/engineering-reference/api/ai.md)), then [`GET /simon/messages`](https://docs.snapfix.com/engineering-reference/api/ai.md#get-simonmessages). Android: [`GET /simon/session/{session_id}`](https://docs.snapfix.com/engineering-reference/api/ai.md#get-simonsessionsession_id). All: `__simon:open__` on [`POST /simon/chat/stream`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-simonchatstream) |
| Send a message                                                     | Any member                                                                     | The message appears and the reply streams in. The message box is off until the reply ends. The request names the site, and where the user is: on the web, the group and task of a group's task page; on iOS, the group while a task list is open, the task on the task page, and a building (the room's or area's, else the site's first AI-enabled one); on Android, the group when opened from a task list, and the site's first active building.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [`POST /simon/chat/stream`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-simonchatstream)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Tap a chip                                                         | Any member                                                                     | Shows the chip's label and sends its value. The web's built-in topics send their text. iOS's built-in "Something else..." chip sends its own text as a message. On iOS, a chip the server marks `dismiss_auto_prompts` sends `__simon:dismiss_starters__` with no bubble. The v2 agent runs and saves a model turn on it; how the production agent handles it was not read \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | [`POST /simon/chat/stream`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-simonchatstream)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Answer the questions, then "Send"                                  | Any member                                                                     | Keeps each answer while the user pages through the questions. "Send" posts every answer in one turn, with the command `submit clarification`. The web shows the answers joined by commas as your message, and Android one per line; iOS shows the text "submit clarification".                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | [`POST /simon/chat/stream`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-simonchatstream) with `clarificationAnswers`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| New chat (web "Refresh", the iOS refresh icon, Android "New chat") | Any member                                                                     | Web: deletes the chat on the server without asking, then empties the panel; the starter chips already shown stay, and no open command is sent (`simon-panel.component.ts:372-375`). Android: deletes the chat, then starts a new one and asks for starter chips. iOS: starts a new chat on the phone and asks for starter chips; the old chat stays on the server. What the button should do is open \[[ASK-184](https://github.com/snapfix/docs/blob/main/ASK.md#ask-184-what-should-snapfix-ais-refresh-button-do)].                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Web and Android: [`DELETE /simon/session/{session_id}`](https://docs.snapfix.com/engineering-reference/api/ai.md#delete-simonsessionsession_id). Android and iOS: `__simon:open__`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Close                                                              | Any member                                                                     | Closes the panel, card or sheet. The web stops a reply that is still streaming. The chat stays on the server.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | None                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Retry                                                              | Any member, when offered                                                       | The retry icon by the failed message sends the same command again. The web and Android also resend the answers to a question card; iOS sends the command only, so a retried set of answers is lost.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [`POST /simon/chat/stream`](https://docs.snapfix.com/engineering-reference/api/ai.md#post-simonchatstream)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Older messages                                                     | Any member                                                                     | Web: scrolling to the top loads the 20 messages before the oldest one shown. iOS: the same, in a restored chat (`SimonAIViewModel.swift:364-386`) \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]; a chat started in the card has nothing older. Android: shows the earlier turns it already holds, 20 at a time, with no request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Web and iOS: [`GET /simon/messages`](https://docs.snapfix.com/engineering-reference/api/ai.md#get-simonmessages) with `before`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| "View document"                                                    | Any member                                                                     | Opens [Source document](https://docs.snapfix.com/how-the-apps-work/screens/ai/source-document.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | See there                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| "View Task", "View All {N} Tasks"                                  | Any member                                                                     | Web: opens `/group/{group}/task/{task}`, or the list above; the panel stays open over the page. iOS: closes the card, then opens the task, fetching it first ("Refreshing...") when the phone does not have it; "View All" opens the task list, switched to the tasks' group when the card names one. Android: opens the task, syncing first ("Please wait...") when the phone does not have it; "View All" opens the group's task list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | None on the web                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Translation                                                        | Any member, on a site with AI translation on (`fAiLanguageTranslationEnabled`) | Answers show in the user's language. Web: "Translating..." while it works, then "See original" or "Show translation" under the answer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `POST /v1/app/translations/batch` ([Reference API](https://docs.snapfix.com/engineering-reference/api/reference.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Switch site (web)                                                  | Any member                                                                     | Stops the reply and loads the new site's chat (`simon-panel.component.ts:159-181`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | As "Open"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Tour                                                               | Users whose `showAiAgentTooltip` flag is 1                                     | See [First-run tour](#first-run-tour).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Web: [`PUT /v1/app/user`](https://docs.snapfix.com/engineering-reference/api/account.md#put-v1appuser). iOS and Android: `save_pri_user_v7` ([Users API](https://docs.snapfix.com/engineering-reference/api/users.md))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

## States

* **Loading:** web: a loader covers the conversation while a chat restores (its status label is "Loading..."), and the message box is off. While a reply is pending, the thinking indicator shows a label and, under it, "This usually takes a few seconds." on all three platforms.
  * web: "Understanding your request...", then Simon's step labels, and "Taking a little longer than usual..." when a label has not changed for 8 seconds (`simon-panel.component.ts:825-869`). The string "Snapfix is Thinking..." exists but nothing shows it.
  * iOS: "Understanding your request...", then Simon's step labels; known phases read "Retrieving data…", "Creating tasks…", "Assigning…" and "Finishing up…". After 8 seconds on one label it shows "Taking a little longer than usual…", and 8 seconds later "Still working…" (ios @ aa31967ac8, `SnapFix/SimonAI/SimonAIViewModel.swift:1083-1150`).
  * Android: Simon's step label, or "Snapfix AI is Thinking..." when there is none (`SimonAiActivity.kt:815-824`). It has no longer-wait text.
* **Empty:** the greeting by the device's hour, "Good Morning, {name}!", "Good Afternoon, {name}!" or "Good Evening, {name}!", then "How can I assist with today's housekeeping operations?" on every site \[[ASK-188](https://github.com/snapfix/docs/blob/main/ASK.md#ask-188-should-snapfix-ais-empty-screen-ask-about-housekeeping-on-every-site)]. The hours and the name differ by platform ([Platform differences](#platform-differences)). Under it, the starter chips the server sends. Before they arrive, or when the request fails, the web shows four built-in topics: "Room Status Summary", "Yesterday Operations Summary", "Operational Risks Today" and "What should I focus today?" (`simon-message-list.component.ts:82-87`). iOS shows no chips while the open request runs, then five built-in prompts if none arrived: the same four and "Something else..." (`SimonAIViewModel.swift:83-89`, `:150-156`). Android shows only the server's chips. The iOS greeting and prompts are English in every language.
* **Error:**
  * web: the error shows under your message: the server's message, or "Couldn't generate a response.". "Retry" shows when the server marks the error retryable, and after every HTTP or network failure. A reply that sends nothing for 120 seconds fails (`simon-panel.component.ts:72`, `:530`).
  * iOS: for `llm_timeout`, `internal_error` and `usage_limit_exceeded`, "Couldn't generate a response." shows under your message whatever the server said. Other failures show an error line at the end of the chat, with the server's text or "Something went wrong" (`SnapFix/SimonAI/Subviews/SimonAIConversationListView.swift:54-57`, `:161-176`). The retry icon shows when the server marks the error retryable, and for HTTP 500 and up, network failures and cut-off replies (`SnapFix/SimonAI/SimonAIStreamClient.swift:185-217`, `:300-316`).
  * Android: under your message, the server's text for an error that is not retryable, else "Couldn't generate a response.", with the retry icon when retryable (`SimonAiActivity.kt:893-910`). When no message can hold the error, as on open, a toast shows its text: "Couldn't reach Snapfix AI. Check your connection and try again.", "The response was cut short. Please try again." or "Something went wrong. Please try again." (`:1081-1092`). An expired sign-in is refreshed once and the turn sent again; when the refresh fails, "Your session expired. Please sign in again." shows, with no retry, and a second refusal after a refresh shows "Your session expired. Please try again." (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/repository/SimonRepository.kt:50-86`, `app/src/main/java/gmail/com/snapfixapp/network/simon/SimonSseClient.kt:136-150`).
  * On the v2 agent, a user without access to the site gets a generic retryable error, not an access message; the production agent was not checked \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].
* **No permission:** with the site's switch off there is no button and no message. A refused microphone stops voice input; typing still works. A usage limit, where the server sets one, comes back as an error from the server ([POST /simon/chat/stream](https://docs.snapfix.com/engineering-reference/api/ai.md#post-simonchatstream)).
* **Offline (mobile):** iOS checks no connection; a failed send shows "Something went wrong" with the retry icon. Android shows "Couldn't generate a response." with the retry icon under a failed message, or the network text as a toast. Voice input that loses the network shows "Connection lost. Please check your internet." on Android.

## Dialogs and sheets

### First-run tour

Shown to users whose `showAiAgentTooltip` flag is 1, on a site with Snapfix AI on.

* **Web:** three steps. "Meet Snapfix 👋. Your AI assistant is always here to help. Click anytime to ask questions, find information, or get things done faster." on the button; "Ask Snapfix anything" when the pointer moves over the button; "Type a question or choose one of the suggested prompts." on the message box once the panel opens. Clicking into the message box after all three ends the tour and sets the flag to 0 (web\_app\_v2 @ 0989b8e685, `src/app/services/simon/simon-tour/simon-tour.service.ts:161-195`). A click anywhere else ends it without saving, so it shows again later. The flag comes with the account list (`src/app/components/side-menu/account-list-menu/account-list-menu.component.ts:268`).
* **iOS:** the same three texts: two tips on the button, then the composer tip inside the card, which goes when it is tapped or a message is sent. When the first tip shows, iOS sets the flag to 0 on the phone and sends the user's row to the server; the later tips follow a step kept on the phone (ios @ aa31967ac8, `SnapFix/SimonAI/SimonAITooltipCoach.swift:245-291`, `Models/User.swift:588-617`).
* **Android:** two tips on the group list, 1.5 seconds after the icon appears: "Meet Snapfix AI 👋 Your AI assistant is always here to help. Click anytime to ask questions, find information, or get things done faster." and "Ask Snapfix AI anything". A tap anywhere moves on, and the second tip opens Snapfix AI with "Type a question or choose one of the suggested prompts." over the input bar. When the first tip shows, Android sets the flag to 0 on the phone and, when online, sends the user's row to the server (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:4513-4578`, `app/src/main/java/gmail/com/snapfixapp/utils/SimonAiTooltipManager.kt:60-100`). A user who has just joined by invitation sees it on a later launch.

### Question card

Shown when Simon asks several questions; it pages through them.

* **Web:** the question, its options numbered, "Something else..." for a typed answer, "Previous" and "Next" with the step (for example "1 of 3"), "Send" (not in single-answer mode) and a close button.
* **iOS:** the wizard above the composer, with the step ("1 of 3") and "Send".
* **Android:** the options, "Something else...", "Previous question" and "Next question", the step ("1 of 3"), "Send" and a close button.

Closing the card answers nothing: the question stays in the chat, and the user can reply in the message box.

### Microphone access

* **iOS:** when the microphone or speech permission is refused, an alert says "We need to access your microphone to capture audio for the purposes of sending video and voice messages, and creating voice tasks. You can proceed without granting the permissions, but you will not be able to use these features." "GO TO SETTINGS" opens Settings; "Cancel" closes it (`SimonAIViewModel.swift:714-750`).
* **Android:** the permission request explains "To record voice message allow Snapfix to access your microphone and your device storage." Once the permission is refused for good, a dialog says "To record voice message allow Snapfix to access your microphone and your device storage. Tap on Go to settings > permission and allow permissions." with "Go to settings" and "Not now" (`SimonAiActivity.kt:600-622`).

## Platform differences

| Topic                  | Web                                      | iOS                                                                                                                                                                                             | Android                                                                                                                                                                                              |
| ---------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Where it opens         | A side panel, on every page              | A card, from the main screens, Home, the chat tab and the task page                                                                                                                             | A sheet, from the group list and a group's task list                                                                                                                                                 |
| Restore on open        | The browser tab's chat for the site      | The site's newest chat, with the phone's copy of its cards \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]; none on v2 | In memory while the app runs; the recent turns after a restart \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]; empty on v2 |
| New chat               | Deletes the server chat                  | Keeps the server chat                                                                                                                                                                           | Deletes the server chat                                                                                                                                                                              |
| Retry offered          | Retryable errors and every HTTP failure  | Retryable errors, HTTP 500 and up, network failures                                                                                                                                             | Retryable errors, HTTP 500 and up, network failures, cut-off replies, a refused sign-in                                                                                                              |
| Server's error text    | Always shown                             | Hidden for three codes                                                                                                                                                                          | Shown for errors that are not retryable                                                                                                                                                              |
| Greeting hours         | Morning before 12:00, afternoon to 16:59 | Morning 05:00 to 11:59, afternoon to 16:59, otherwise evening                                                                                                                                   | Morning before 12:00, afternoon to 16:59                                                                                                                                                             |
| Greeting name          | First name, else name, else username     | First name only, English text                                                                                                                                                                   | First name, else name                                                                                                                                                                                |
| Built-in starter chips | Four, translated                         | Five, English, including "Something else..."                                                                                                                                                    | None; five prompt strings are unused                                                                                                                                                                 |
| Longer-wait text       | After 8 seconds                          | After 8 seconds, then "Still working…"                                                                                                                                                          | None                                                                                                                                                                                                 |
| Voice                  | None                                     | Hold the microphone                                                                                                                                                                             | Hold the voice button                                                                                                                                                                                |
| Stream wait            | Fails after 120 seconds without data     | 600 seconds per request (`SimonAIStreamClient.swift:101`)                                                                                                                                       | The app's shared client: 10 minutes without data (`app/src/main/java/gmail/com/snapfixapp/network/RetrofitClient.java:82-83`)                                                                        |
| Tour flag              | Saved when the tour ends                 | Saved when the first tip shows                                                                                                                                                                  | Saved when the first tip shows                                                                                                                                                                       |
| Logs                   | Nothing printed                          | Stream frames printed in every build                                                                                                                                                            | Frame logs in debug builds only                                                                                                                                                                      |

The iOS client calls the test host `ai-agent-test.snapfix.com` in testing mode and `ai-agent.snapfix.com` otherwise (`SimonAIStreamClient.swift:86-89`) \[[ASK-8](https://github.com/snapfix/docs/blob/main/ASK.md#ask-8-confirm-the-environments)].


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/how-the-apps-work/screens/ai/assistant.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
