edits from review suggestions

docs/content/basic/app-assistant.md

@@ -8,7 +8,7 @@ slug: /concepts/assistant
 If you don't have a paid workspace for development, you can join the [Developer Program](https://api.slack.com/developer-program) and provision a sandbox with access to all Slack features for free.
 :::
 
-Agents and assistants comprise a new messaging experience for Slack. If you're unfamiliar with using agents and assistants within Slack, you'll want to read the [API documentation on the subject](https://api.slack.com/docs/apps/ai). Then, come back here to implement them with Bolt!
+Agents and assistants comprise a new messaging experience for Slack. If you're unfamiliar with using agents and assistants within Slack, you'll want to read the [API documentation on the subject](https://api.slack.com/docs/apps/ai). Then come back here to implement them with Bolt!
 
 ## Configuring your app to support assistants 
 
@@ -30,6 +30,12 @@ You _could_ implement your own assistants by [listening](/concepts/event-listeni
 
 ## The `Assistant` class instance
 
+The [`Assistant`](/reference#the-assistantconfig-configuration-object) can be used to handle the incoming events expected from a user interacting with an assistant in Slack. A typical flow would look like:
+
+1. [The user starts a thread](#handling-new-thread). The `Assistant` class handles the incoming [`assistant_thread_started`](https://api.slack.com/events/assistant_thread_started) event.
+2. [The thread context may change at any point](#handling-context-changes). The `Assistant` class can handle any incoming [`assistant_thread_context_changed`](https://api.slack.com/events/assistant_thread_context_changed) events. The class also provides a default `context` store to keep track of those changes as the user moves through Slack.
+3. [The user responds](#handling-user-response). The `Assistant` class handles the incoming [`message.im`](https://api.slack.com/events/message.im) event. 
+
 ```ts
 const assistant = new Assistant({
   threadContextStore: {
@@ -42,11 +48,19 @@ const assistant = new Assistant({
 });
 ```
 
-You can store context through the `threadContextStore` property but it must feature `get` and `save` methods. If not provided, a `DefaultThreadContextStore` instance is utilized instead, which is a reference implementation that relies on storing and retrieving message metadata as the context changes.
+While the `assistant_thread_started` and `assistant_thread_context_changed` events do provide Slack-client context information, the `message.im` event does not. Any subsequent user message events won't contain context data. For that reason, Bolt not only provides a way to store context — the `threadContextStore` property — but it also provides a `DefaultThreadContextStore` instance that is utilized by default. This implementation relies on storing and retrieving [message metadata](https://api.slack.com/metadata/using) as the user interacts with the assistant. 
+
+If you do provide your own `threadContextStore` property, it must feature `get` and `save` methods.
+
+:::tip
+Be sure to give the [assistants reference docs](/reference#assistants) a look!
+:::
 
-## Handling a new thread
+## Handling a new thread {#handling-new-thread}
 
-The `threadStarted` event handler allows your app to respond to new threads opened by users. In the example below, the app is sending a message — containing context message metadata — to the user, along with a single [prompt](https://api.slack.com/methods/assistant.threads.setSuggestedPrompts).
+When the user opens a new thread with your assistant, the [`assistant_thread_started`](https://api.slack.com/events/assistant_thread_started) event will be sent to your app. Capture this with the `threadStarted` handler to allow your app to respond. 
+
+In the example below, the app is sending a message — containing context [message metadata](https://api.slack.com/metadata/using) — to the user, along with a single [prompt](https://api.slack.com/methods/assistant.threads.setSuggestedPrompts).
 
 ```js
 ...
@@ -75,9 +89,9 @@ The `threadStarted` event handler allows your app to respond to new threads open
 When a user opens an assistant thread while in a channel, the channel info is stored as the thread's `AssistantThreadContext` data. You can grab that info using the `getThreadContext()` utility, as subsequent user message event payloads won't include the channel info. 
 :::
 
-## Handling context changes 
+## Handling context changes {#handling-context-changes}
 
-When the user switches channels, the `assistant_thread_context_changed` event will be sent to your app. Capture this with the `threadContextChanged` handler.
+When the user switches channels, the [`assistant_thread_context_changed`](https://api.slack.com/events/assistant_thread_context_changed) event will be sent to your app. Capture this with the `threadContextChanged` handler.
 
 ```js
 ...
@@ -89,12 +103,14 @@ When the user switches channels, the `assistant_thread_context_changed` event wi
 
 If you use the built-in `AssistantThreadContextStore` without any custom configuration the updated context data is automatically saved as message metadata on the first reply from the assistant bot.
 
-## Handling the user response
+## Handling the user response {#handling-user-response}
+
+When the user messages your assistant, the [`message.im`](https://api.slack.com/events/message.im) event will be sent to your app. Capture this with the `userMessage` handler. 
 
-User messages are handled with the `userMessage` event handler. The `setTitle` and `setStatus` utilities are useful in curating the user experience. 
+The `setTitle` and `setStatus` [utilities](/reference#the-assistantconfig-configuration-object) are useful in curating the user experience. 
 
 :::warning
-Messages sent to the assistant do not contain a subtype and must be deduced based on their shape and any provided metadata.
+Messages sent to the assistant do not contain a subtype and must be deduced based on their shape and any provided [metadata](https://api.slack.com/metadata/using).
 :::
 
  ```js