docs: fix critical inaccuracies in English documentation (#1512)

Co-authored-by: Claude <svc-devxp-claude@slack-corp.com>

Author: lukegalbraithrussell

docs/english/concepts/adding-agent-features.md

@@ -190,7 +190,7 @@ def handle_message(
         # Add eyes reaction only to the first message (DMs only — channel
         # threads already have the reaction from the initial app_mention)
         if is_dm and not existing_session_id:
-            await client.reactions_add(
+            client.reactions_add(
                 channel=channel_id,
                 timestamp=event["ts"],
                 name="eyes",
@@ -274,7 +274,7 @@ The `say_stream` utility streamlines calling the Python Slack SDK's [`WebClient.
 | `recipient_team_id` | Sourced from the event `team_id` (`enterprise_id` if the app is installed on an org).
 | `recipient_user_id` | Sourced from the `user_id` of the event.
 
-If neither a `channel_id` or `thread_ts` can be sourced, then the utility will be `None`.
+If either `channel_id` or `thread_ts` cannot be sourced, the utility will be `None`.
 
 ```python
 streamer = say_stream()
@@ -571,7 +571,7 @@ def handle_app_mentioned(
 
     except Exception as e:
         logger.exception(f"Failed to handle app mention: {e}")
-        await say(
+        say(
             text=f":warning: Something went wrong! ({e})",
             thread_ts=event.get("thread_ts") or event["ts"],
         )

docs/english/concepts/message-sending.md

@@ -54,7 +54,7 @@ The `say_stream` utility streamlines calling the Python Slack SDK's [`WebClient.
 | `recipient_team_id` | Sourced from the event `team_id` (`enterprise_id` if the app is installed on an org).
 | `recipient_user_id` | Sourced from the `user_id` of the event.
 
-If neither a `channel_id` or `thread_ts` can be sourced, then the utility will be `None`.
+If either `channel_id` or `thread_ts` cannot be sourced, the utility will be `None`.
 
 For information on calling the `chat_*Stream` API methods directly, see the [_Sending streaming messages_](/tools/python-slack-sdk/web#sending-streaming-messages) section of the Python Slack SDK docs.
 
@@ -79,7 +79,7 @@ def handle_app_mention(client: WebClient, say_stream: SayStream):
 def handle_message(client: WebClient, say_stream: SayStream):
   stream = say_stream()
 
-  stream.append(markdown_text="Let me consult my *vast knowledge database*...)
+  stream.append(markdown_text="Let me consult my *vast knowledge database*...")
   stream.stop()
 
 if __name__ == "__main__":

docs/english/concepts/updating-pushing-views.md

@@ -1,6 +1,6 @@
 # Updating & pushing views
 
-Modals contain a stack of views. When you call [`views_open`](https://api./reference/methods/views.open/slack.com/methods/views.open), you add the root view to the modal. After the initial call, you can dynamically update a view by calling [`views_update`](/reference/methods/views.update/), or stack a new view on top of the root view by calling [`views_push`](/reference/methods/views.push/)
+Modals contain a stack of views. When you call [`views_open`](/reference/methods/views.open/), you add the root view to the modal. After the initial call, you can dynamically update a view by calling [`views_update`](/reference/methods/views.update/), or stack a new view on top of the root view by calling [`views_push`](/reference/methods/views.push/)
 
 ## The `views_update` method
 

docs/english/concepts/using-the-assistant-class.md

@@ -51,7 +51,7 @@ You _could_ go it alone and [listen](/tools/bolt-python/concepts/event-listening
 
 While the `assistant_thread_started` and `assistant_thread_context_changed` events do provide Slack-client thread context information, the `message.im` event does not. Any subsequent user message events won't contain thread context data. For that reason, Bolt not only provides a way to store thread 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](/messaging/message-metadata/) as the user interacts with the app. 
 
-If you do provide your own `threadContextStore` property, it must feature `get` and `save` methods.
+If you do provide your own `threadContextStore` property, it must feature `find` and `save` methods.
 
 :::tip[Refer to the [reference docs](https://docs.slack.dev/tools/bolt-python/reference/kwargs_injection/args.html) to learn the available listener arguments.]
 :::
@@ -138,10 +138,10 @@ Messages sent to the app do not contain a [subtype](/reference/events/message#su
 
 There are three utilities that are particularly useful in curating the user experience:
 * [`say`](https://docs.slack.dev/tools/bolt-python/reference/#slack_bolt.Say)
-* [`setTitle`](https://docs.slack.dev/tools/bolt-python/reference/#slack_bolt.SetTitle)
-* [`setStatus`](https://docs.slack.dev/tools/bolt-python/reference/#slack_bolt.SetStatus)
+* [`set_title`](https://docs.slack.dev/tools/bolt-python/reference/#slack_bolt.SetTitle)
+* [`set_status`](https://docs.slack.dev/tools/bolt-python/reference/#slack_bolt.SetStatus)
 
-Within the `setStatus` utility, you can cycle through strings passed into a `loading_messages` array.
+Within the `set_status` utility, you can cycle through strings passed into a `loading_messages` list.
 
 ```python
 # This listener is invoked when the human user sends a reply in the assistant thread

docs/english/concepts/view-submissions.md

@@ -90,6 +90,6 @@ def handle_submission(ack, body, client, view, logger):
     # Message the user
     try:
         client.chat_postMessage(channel=user, text=msg)
-    except e:
+    except Exception as e:
         logger.exception(f"Failed to post a message {e}")
 ```

docs/english/experiments.md

@@ -1,30 +1,11 @@
 # Experiments
 
-Bolt for Python includes experimental features still under active development. These features may be fleeting, may not be perfectly polished, and should be thought of as available for use "at your own risk." 
+Bolt for Python occasionally includes experimental features still under active development. These features may be fleeting, may not be perfectly polished, and should be thought of as available for use "at your own risk." 
 
 Experimental features are categorized as `semver:patch` until the experimental status is removed.
 
 We love feedback from our community, so we encourage you to explore and interact with the [GitHub repo](https://github.com/slackapi/bolt-python). Contributions, bug reports, and any feedback are all helpful; let us nurture the Slack CLI together to help make building Slack apps more pleasant for everyone.
 
 ## Available experiments
-* [Agent listener argument](#agent)
 
-## Agent listener argument {#agent}
-
-The `agent: BoltAgent` listener argument provides access to AI agent-related features.
-
-The `BoltAgent` and `AsyncBoltAgent` classes offer a `chat_stream()` method that comes pre-configured with event context defaults: `channel_id`, `thread_ts`, `team_id`, and `user_id` fields. 
-
-The listener argument is wired into the Bolt `kwargs` injection system, so listeners can declare it as a parameter or access it via the `context.agent` property.
-
-### Example
-
-```python
-from slack_bolt import BoltAgent
-
-@app.event("app_mention")
-def handle_mention(agent: BoltAgent):
-    stream = agent.chat_stream()
-    stream.append(markdown_text="Hello!")
-    stream.stop()
-```
+There are currently no active experiments. We're steadily staying stable.

docs/english/tutorial/custom-steps-workflow-builder-existing/custom-steps-workflow-builder-existing.md

@@ -14,7 +14,7 @@ In this tutorial we will:
 
 ## Prerequisites {#prereqs}
 
-The custom steps feature is compatible with Bolt version 1.20.0 and above. First, update your `package.json` file to reflect version 1.20.0 of Bolt, then run the following command in your terminal:
+The custom steps feature is compatible with Bolt version 1.20.0 and above. First, update your `requirements.txt` file to reflect version 1.20.0 of Bolt (e.g., `slack-bolt>=1.20.0`), then run the following commands in your terminal:
 
 ```sh
 python3 -m venv .venv 
@@ -215,9 +215,8 @@ def manager_resp_handler(ack: Ack, action, body: dict, client: WebClient, comple
 
         client.chat_update(
             channel=body['channel']['id'],
-            message=body['message'],
             ts=body["message"]["ts"],
-            text=f'Request {"approved" if request_decision == 'approve' else "denied"}!'
+            text=f"Request {'approved' if request_decision == 'approve' else 'denied'}!"
         )
 
         complete({

docs/english/tutorial/custom-steps-workflow-builder-new/custom-steps-workflow-builder-new.md

@@ -47,7 +47,9 @@ You can also open a terminal window from inside VSCode like this: `Ctrl` + `~`
 Once in VSCode, open the terminal. Let's install our package dependencies: run the following command(s) in the terminal inside VSCode:
 
 ```sh
-npm install
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
 ```
 
 We now have a Bolt app ready for development! Open the `manifest.json` file and copy its contents; you'll need this in the next step.
@@ -99,7 +101,7 @@ You will then have a bot token. Again, copy that value and save it somewhere acc
 
 ## Starting your local development server {#local}
 
-While building your app, you can see your changes appear in your workspace in real-time with `npm start`. Soon we'll start our local development server and see what our sample code is all about! But first, we need to store those tokens we gathered as environment variables. 
+While building your app, you can see your changes appear in your workspace in real-time with `python app.py`. Soon we'll start our local development server and see what our sample code is all about! But first, we need to store those tokens we gathered as environment variables. 
 
 Navigate back to VSCode. Rename the `.env.sample` file to `.env`. Open this file and update `SLACK_APP_TOKEN` and `SLACK_BOT_TOKEN` with the values you previously saved. It will look like this, with your actual token values where you see `<your_app_token>` and `<your_bot_token>`:
 
@@ -111,7 +113,7 @@ SLACK_BOT_TOKEN=<your_bot_token>
 Now save the file and try starting your app:
 
 ```sh
-npm start
+python app.py
 ```
 
 You'll know the local development server is up and running successfully when it emits a bunch of `[DEBUG]` statements to your terminal, the last one containing `connected:ready`.

docs/english/tutorial/custom-steps.md

@@ -111,9 +111,9 @@ Here is a sample app manifest laying out a step definition. This definition tell
                 "name": "user_id"
             }
           },
-          "required": {
+          "required": [
             "user_id"
-          }
+          ]
         },
         "output_parameters": {
           "properties": {
@@ -124,9 +124,9 @@ Here is a sample app manifest laying out a step definition. This definition tell
                 "name": "user_id"
             }
           },
-          "required": {
+          "required": [
             "user_id"
-          }
+          ]
         },
     }
 }
@@ -157,7 +157,7 @@ Notice in the example code here that the name of the step, `sample_step`, is the
 
 ```py
 @app.function("sample_step")
-def handle_sample_step_event(inputs: dict, fail: Fail, complete: Complete,logger: logging.Logger):
+def handle_sample_step_event(client: WebClient, inputs: dict, fail: Fail, complete: Complete, logger: logging.Logger):
     user_id = inputs["user_id"]
     try:
         client.chat_postMessage( 
@@ -226,7 +226,7 @@ The second argument is the callback function, or the logic that will run when yo
 Field | Description
 ------|------------
 `client` | A `WebClient` instance used to make things happen in Slack. From sending messages to opening modals, `client` makes it all happen. For a full list of available methods, refer to the [Web API methods](/reference/methods). Read more about the `WebClient` for Bolt Python [here](https://docs.slack.dev/tools/bolt-python/concepts/web-api/).
-`complete` | A utility method that invokes `functions.completeSuccess`. This method indicates to Slack that a step has completed successfully without issue. When called, `complete` requires you include an `outputs` object that matches your step definition in [`output_parameters`](#inputs-outputs).
+`complete` | A utility method that invokes `functions.completeSuccess`. This method indicates to Slack that a step has completed successfully without issue. When called, `complete` accepts an optional `outputs` object that matches your step definition in [`output_parameters`](#inputs-outputs).
 `fail` | A utility method that invokes `functions.completeError`. True to its name, this method signals to Slack that a step has failed to complete. The `fail` method requires an argument of `error` to be sent along with it, which is used to help users understand what went wrong.
 `inputs` | An alias for the `input_parameters` that were provided to the step upon execution.