stealth 2.0.0.beta5 → 2.0.0.beta7

data/docs/controllers/route.md

@@ -0,0 +1,70 @@
+---
+description: Describes the route method in BotController.
+---
+
+# route
+
+The `route` method in `BotController` is the primary entry point for messages into your bot. This method is left open for you to edit in order for you to customize that process. Here is the method after having been generated:
+
+```ruby
+def route
+  if current_message.payload.present?
+    handle_payloads
+    # Clear out the payload to prevent duplicate handling
+    current_message.payload = nil
+    return
+  end
+
+  # Allow devs to jump around flows and states by typing:
+  #   /flow_name/state_name or
+  #   /flow_name (jumps to first state) or
+  #   //state_name (jumps to state in current flow)
+  # (only works for bots in development)
+  return if dev_jump_detected?
+
+  if current_session.present?
+    step_to session: current_session
+  else
+    step_to flow: 'hello', state: 'say_hello'
+  end
+end
+```
+
+The method, by default, performs three tasks:
+
+1. Handles payloads.
+2. Handles [Dev Jumps](dev-jumps.md).
+3. Routes a user to their existing location based on their session or starts a new session if one does not already exist.
+
+We'll cover 1 and 3 in more detail below. You can learn more about Dev Jumps via the [Dev Jumps docs](dev-jumps.md).
+
+### Payloads
+
+Payloads are used to handle things like buttons in Facebook Messenger. On other platforms, like SMS and Whatsapp, payloads might be global keywords your bot is configured to support.
+
+Payloads have to be handled globally because a button may be tapped (or keyword typed in) at any point during a conversation. Your bot, therefore, needs to be able to handle these in any flow and state.
+
+Line 2 in the code sample above checks if the payload field of a message is present, and if so, calls the `handle_payloads` method. Here is that method:
+
+```ruby
+# Handle payloads globally since payload buttons remain in the chat
+# and we cannot guess in which states they will be tapped.
+def handle_payloads
+  case current_message.payload
+  when 'developer_restart', 'new_user'
+    step_to flow: 'hello', state: 'say_hello'
+  when 'goodbye'
+    step_to flow: 'goodbye'
+  end
+end
+```
+
+By setting the payload value of a Facebook Messenger button to `developer_restart`, for example, you can trigger the conversation to restart.
+
+{% hint style="info" %}
+More information for handling global SMS or Whatsapp keywords and button payloads can be found in the respective documentation for each message platform component.
+{% endhint %}
+
+### Routing Based on Session
+
+In the first code sample, Lines 16-20 handle routing a user to their existing session or starting a new one. For users with an existing session, you'll likely want to keep that code the same. For users without session, you may want to customize the starting flow.

data/docs/controllers/sessions/README.md

@@ -0,0 +1,2 @@
+# Sessions
+

data/docs/controllers/sessions/do_nothing.md

@@ -0,0 +1,17 @@
+# do\_nothing
+
+This method is available for overriding the default behavior of Stealth which fires a [CatchAll](../catch-alls.md) in cases where a controller action fails to the update a session or send replies. See the documentation on [failing to progress a user](../controller-overview.md#failing-to-progress-a-user) for more information.
+
+It's primarily used in states that "trap" the user (like your bot's last state or the last level of your `catch_all` flow).
+
+It's usage is straightforward:
+
+```ruby
+def  
+  do_nothing
+end
+```
+
+{% hint style="info" %}
+You might also use `do_nothing` within an if/else block.
+{% endhint %}

data/docs/controllers/sessions/intro.md

@@ -0,0 +1,37 @@
+# Session Overview
+
+Sessions in Stealth allow your bot to maintain a state for each user. If you come from the web development world, they are very similar to HTTP sessions. If you don't come from that world, no worries, we'll explain how sessions work without needing to know. If you haven't yet read the primer on [Flows and States](../../flows/overview.md), we recommend you do that first. 
+
+### How are sessions stored?
+
+Sessions in Stealth are backed by Redis. Each user interacting with your bot has a unique ID assigned by the messaging platform that identifies them. With Facebook Messenger, it's a page-scoped ID (PSID). With SMS and Whatsapp it's a phone number. These unique IDs are used as the key in Redis.
+
+Regardless of what it is, it allows Stealth to find and load a user's session each time a message is received.
+
+#### Session Slugs
+
+With the unique messaging platform ID used as the Redis key, the value is the session slug. This is a canonical string that represents a user's current flow and state. A session slug looks like this: `flow->state`. So if a user's session is currently pointing to the `hello` flow and the `say_hola` state, then the slug would be `hello->say_hola`.
+
+{% hint style="info" %}
+If a user has not interacted with your bot before, the key will therefore be `nil` indicating there is no session for the user.
+{% endhint %}
+
+#### Session Expiration
+
+By default, sessions do not expire. This is however configurable as a [setting](../../config/settings.md).
+
+{% hint style="warning" %}
+If your bot sends re-engagements, make sure your session's expiration is set to be _after_ the last re-engagement message is sent.
+{% endhint %}
+
+#### Previous Session
+
+In addition to storing a user's current session, Stealth also automatically maintains a copy of the previous session. This allows you to send a user "back" from a catch-all scenario.
+
+{% hint style="info" %}
+Previous sessions also expire at the same time as primary sessions.
+{% endhint %}
+
+#### State Transitions
+
+State transitions are performed via [step\_to](step\_to.md), [step\_to\_in](step\_to\_in.md), [step\_to\_at](step\_to\_at.md), [step\_back](step\_back.md), and [update\_session\_to](update\_session\_to.md). You can also manually manipulate the key in Redis, but these are currently the only ways to alter a user's session via Stealth.

data/docs/controllers/sessions/step_back.md

@@ -0,0 +1,88 @@
+# step\_back
+
+Used in conjunction with `set_back_to`, `step_back` will step the user to the flow and state specified by `set_back_to`. This is a useful feature when you're building shared flows. Like for example, if you ask a user for their name in multiple places throughout your bot. This allows you to keep your flows [DRY](https://en.m.wikipedia.org/wiki/Don't\_repeat\_yourself).
+
+{% hint style="warning" %}
+If a `back_to` session has not been set before `step_back` is called, Stealth will raise a `Stealth::Errors::InvalidStateTransition` exception.
+{% endhint %}
+
+## set\_back\_to
+
+`set_back_to` serves a similar purpose as [previous\_session](intro.md#previous-session), however, instead of being automatically set by Stealth, `set_back_to` is  user configurable.
+
+It takes the same parameters as `step_to`:
+
+```ruby
+set_back_to state: 'say_hello'
+set_back_to flow: 'hello', state: 'say_hello'
+set_back_to session: previous_session
+```
+
+All three commands above are valid and will store the `back_to` session. 
+
+{% hint style="info" %}
+`back_to` sessions also expire along with the primary session and previous session (if an expiration has been set).
+{% endhint %}
+
+## Example
+
+```ruby
+class DataHelpersController < BotController
+  
+  def ask_for_email_address
+    send_replies
+    update_session_to state: :get_email_address
+  end
+
+  def get_email_address
+    unless message_is_a_valid_email?
+      step_to state: :say_invalid_email
+      return
+    end
+
+    current_user.store(email: current_message.message)
+
+    step_back
+  end
+  
+  def say_invalid_email
+    send_replies
+    update_session_to state: :get_email_address
+  end
+  
+end
+
+
+class QuestionsController < BotController
+
+  def ask_if_interested
+    send_replies
+    update_session_to state: :get_interest_response
+  end
+
+  def get_interest_response
+    handle_message(
+      :yes => proc {
+        set_back_to state: :say_thanks
+        step_to flow: :data_helper, state: :ask_for_email_address
+      },
+      :no => proc {
+        step_to state: :say_no_worries
+      }
+    )
+  end
+  
+  def say_thanks
+    send_replies
+  end
+  
+  def say_no_worries
+    send_replies
+  end
+
+end
+```
+
+In the above example, we have two flows/controllers: `data_helper` and `question`. The `DataHelpersController` contains a few states for asking for an email address for the user and verifying that it looks like a legit email address. Setting it up this way allows any of our other controllers to also ask for an email address without having to duplicate these states.
+
+On Lines 37-38, you see that we set the `back_to` session to be the `say_thanks` state. Then we step to the `data_helper` state directly via `step_to`. From the `DataHelpersController` we can continue to ask questions and update the states as needed like normal. Once we've collected the email address, we send the user "back" to the `back_to` session by calling `step_back` on Line 16.

data/docs/controllers/sessions/step_to.md

@@ -0,0 +1,47 @@
+# step\_to
+
+The `step_to` method is used to update the session and immediately move the user to the specified flow and state. `step_to` can accept a _flow_, a _state_, or both. `step_to` is often used after a `say` action where the next action typically doesn't require user input.
+
+{% hint style="warning" %}
+If the flow and/or action specified in the `step_to` is not declared in the [FlowMap](../../flows/flowmap.md), Stealth will raise an exception.
+{% endhint %}
+
+## Flow Example
+
+```ruby
+step_to flow: 'hello'
+```
+
+Sets the session's flow to `hello` and the state will be set to the **first** state in that flow (as defined by the [FlowMap](../../flows/flowmap.md)). The corresponding controller action in the `HellosController` will also be immediately called.
+
+{% hint style="info" %}
+The flow name can also be specified as a symbol.
+{% endhint %}
+
+## State Example
+
+```ruby
+step_to state: 'say_hello'
+```
+
+Sets the session's state to `say_hello` and keeps the flow the same. The `say_hello` controller action will also be immediately called.
+
+{% hint style="info" %}
+The state name can also be specified as a symbol.
+{% endhint %}
+
+## Flow and State Example
+
+```ruby
+step_to flow: :hello, state: :say_hello
+```
+
+Sets the session's flow to `hello` and the state to `say_hello`. The `say_hello` controller action of the `HellosController` controller will also be immediately called.
+
+## Session Example
+
+```ruby
+step_to session: previous_session
+```
+
+Sets the session to the `previous_session` and immediately calls the respective controller action. This is useful for sending a user "back".

data/docs/controllers/sessions/step_to_at.md

@@ -0,0 +1,43 @@
+# step\_to\_at
+
+The `step_to_at` method is used to update the session and move the user to the specified flow and state **at the specified date and time**. `step_to_at` can accept a _flow_, a _state_, or both. `step_to_at` is often used as a tool for re-engaging a user at a specific time.
+
+{% hint style="info" %}
+The session will only be updated and the controller action called **at the time specified**.
+{% endhint %}
+
+{% hint style="warning" %}
+If the flow and/or action specified in the `step_to_at` is not declared in the [FlowMap](../../flows/flowmap.md) (at the specified date and time), Stealth will raise an exception.
+{% endhint %}
+
+## Flow Example
+
+```ruby
+step_to_at Time.now.next_week, flow: 'hello'
+```
+
+At the specified time (next week in this case), Stealth will set the session's flow to `hello` and the state will be set to the **first** state in that flow (as defined by the [FlowMap](../../flows/flowmap.md)). The corresponding controller action in the `HellosController` will also be called.
+
+{% hint style="info" %}
+The flow name can also be specified as a symbol.
+{% endhint %}
+
+## State Example
+
+```ruby
+step_to_at Time.now.next_week, state: 'say_hello'
+```
+
+At the specified time (next week in this case), Stealth will set the session's state to `say_hello` and keeps the flow the same. The `say_hello` controller action will also be called.
+
+{% hint style="info" %}
+The state name can also be specified as a symbol.
+{% endhint %}
+
+## Flow and State Example
+
+```ruby
+step_to_at Time.now.next_week, flow: :hello, state: :say_hello
+```
+
+At the specified time (next week in this case), Stealth will set the session's flow to `hello` and the state to `say_hello`. The `say_hello` controller action of the `HellosController` controller will also be called.

data/docs/controllers/sessions/step_to_in.md

@@ -0,0 +1,43 @@
+# step\_to\_in
+
+The `step_to_in` method is used to update the session and move the user to the specified flow and state **after a specified duration**. `step_to_in` can accept a _flow_, a _state_, or both. `step_to_in` is often used as a tool for re-engaging a user after a specified duration.
+
+{% hint style="info" %}
+The session will only be updated and the controller action called **after the specified duration has elapsed**.
+{% endhint %}
+
+{% hint style="warning" %}
+If the flow and/or action specified in the `step_to_in` is not declared in the [FlowMap](../../flows/flowmap.md) (after the specified duration), Stealth will raise an exception.
+{% endhint %}
+
+## Flow Example
+
+```ruby
+step_to_in 8.hours, flow: 'hello'
+```
+
+After the specified duration (8 hours in this case), Stealth will set the session's flow to `hello` and the state will be set to the **first** state in that flow (as defined by the [FlowMap](../../flows/flowmap.md)). The corresponding controller action in the `HellosController` will also be called.
+
+{% hint style="info" %}
+The flow name can also be specified as a symbol.
+{% endhint %}
+
+## State Example
+
+```ruby
+step_to_in 8.hours, state: 'say_hello'
+```
+
+After the specified duration (8 hours in this case), Stealth will set the session's state to `say_hello` and keeps the flow the same. The `say_hello` controller action will also be called.
+
+{% hint style="info" %}
+The state name can also be specified as a symbol.
+{% endhint %}
+
+## Flow and State Example
+
+```ruby
+step_to_in 8.hours, flow: :hello, state: :say_hello
+```
+
+After the specified duration (8 hours in this case), Stealth will set the session's flow to `hello` and the state to `say_hello`. The `say_hello` controller action of the `HellosController` controller will also be called.

data/docs/controllers/sessions/update_session_to.md

@@ -0,0 +1,47 @@
+# update\_session\_to
+
+Similar to [step\_to](step\_to.md), `update_session_to` is used to update the user's session to a flow and state. It also accepts the same arguments. However, `update_session_to` does not immediately call the respective controller action. `update_session_to` is typically used after an `ask` action where the next action is waiting for user input. It allows you to set the state that will be responsible for handling that user input, like a `get` action.
+
+{% hint style="warning" %}
+If the flow and/or action specified in the `update_session_to` is not declared in the [FlowMap](../../flows/flowmap.md), Stealth will raise an exception.
+{% endhint %}
+
+## Flow Example
+
+```ruby
+update_session_to flow: 'hello'
+```
+
+Sets the session's flow to `hello` and the state will be set to the **first** state in that flow (as defined by the [FlowMap](../../flows/flowmap.md)). The corresponding controller action in the `HellosController` will **not** be called.
+
+{% hint style="info" %}
+The flow name can also be specified as a symbol.
+{% endhint %}
+
+## State Example
+
+```ruby
+update_session_to state: 'get_hello_response'
+```
+
+Sets the session's state to `get_hello_response` and keeps the flow the same. The `get_hello_response` controller action will **not** called.
+
+{% hint style="info" %}
+The state name can also be specified as a symbol.
+{% endhint %}
+
+## Flow and State Example
+
+```ruby
+step_to flow: :hello, state: :say_hello
+```
+
+Sets the session's flow to `hello` and the state to `say_hello`. The `say_hello` controller action of the `HellosController` controller will also be immediately called.
+
+## Session Example
+
+```ruby
+update_session_to session: previous_session
+```
+
+Sets the session to the `previous_session` and but does **not** call the respective controller action. This is useful for updating a user's session to the previous value.

data/docs/controllers/unrecognized-messages.md

@@ -0,0 +1,2 @@
+# Unrecognized Messages
+

data/docs/deployment/heroku.md

@@ -0,0 +1,2 @@
+# Heroku
+

data/docs/deployment/overview.md

@@ -0,0 +1,2 @@
+# Deployment Overview
+

data/docs/dev-environment/README.md

@@ -0,0 +1,2 @@
+# Dev Environment
+

data/docs/dev-environment/booting-up.md

@@ -0,0 +1,33 @@
+---
+description: Steps for booting up your bot.
+---
+
+# Booting Up
+
+While you can use Docker or anything else to boot up your bot, there is a built-in command that utilizes [foreman](https://github.com/ddollar/foreman) to ensure your _web server_ and your _background job processor_ both boot up. If you boot only the web server bot the the background job processor, your bot will receive message but will fail to reply.
+
+For more info about the different process types, check out [Anatomy of a Stealth bot](../basics.md#anatomy-of-a-stealth-bot).
+
+### Install Gems
+
+```
+bundle install
+```
+
+### Boot Your Bot
+
+```
+stealth s
+```
+
+Or for the full command:
+
+```
+stealth server
+```
+
+### Tunnels to Localhost
+
+After you boot your server, you'll likely want to use a service to create a tunnel to your localhost. This allows message platform like Facebook Messenger and Whatsapp to deliver messages to your laptop.
+
+Check out the [docs for creating your own tunnel](tunnels.md).

data/docs/dev-environment/environment-variables.md

@@ -0,0 +1,54 @@
+---
+description: Tips for streamlining your environment variable management during development.
+---
+
+# Environment Variables
+
+Environment variables (ENV Vars) will likely be an important part of your configuration. Each message platform component, NLP component, and others will likely require one or more API keys. 
+
+Most production environments will provide a way for you to specify your production keys. But for development, we recommend using the [dotenv](https://github.com/bkeepers/dotenv) gem. This gem will allow you to specify a `.env` file in your bot repo from where you can set all of your environment variables.
+
+{% hint style="info" %}
+Stealth will automatically exclude the `.env` file from git.
+{% endhint %}
+
+### Configuring dotenv in Stealth
+
+Add the [dotenv](https://github.com/bkeepers/dotenv) gem to your `Gemfile`:
+
+```ruby
+group :development do
+  gem 'foreman'
+  gem 'listen', '~> 3.3'
+  gem 'dotenv'
+end
+```
+
+Install the gem:
+
+```ruby
+bundle install
+```
+
+Load dotenv on boot via `boot.rb`:
+
+```ruby
+require 'stealth/base'
+if %w(development test).include?(Stealth.env)
+  require 'dotenv/load'
+end
+require_relative './environment'
+```
+
+{% hint style="info" %}
+You'll be adding Lines 2-4 right below Line 1 which will already be there.
+{% endhint %}
+
+That's it! Now you can specify your environment variables via the `.env` file:
+
+```
+FACEBOOK_VERIFY_TOKEN=some_value
+LUIS_APP_ID=1234
+LUIS_ENDPOINT=your_endpoint.cognitiveservices.azure.com
+LUIS_SUBSCRIPTION_KEY=xyz1234
+```

data/docs/dev-environment/hot-code-reloading.md

@@ -0,0 +1,52 @@
+---
+description: ✨✨✨
+---
+
+# Hot-Code Reloading
+
+Hot-code reloading is one of the more enjoyable features of using Stealth to create your bots. As you make changes to your bot, your source code is automatically loaded into memory without having to stop and start your bot!
+
+There is nothing you need to turn on to start using this feature. As long as you are in the `development` [environment](../basics.md#environments). You may however wish to customize which files are watched for changes as you add your own custom directories, service objects, etc.
+
+## Customizing Hot-Reload Paths
+
+By default, these are paths and files that Stealth will watch for changes:
+
+```
+bot/controllers/conerns/*.*
+bot/controllers/*.*
+bot/models/concerns/*.*
+bot/models/*.*
+bot/helpers/*.*
+config/*.*
+```
+
+In addition to your Ruby code in these directories, all reply files are automatically included since Stealth reads their contents for each message.
+
+### Adding a File or Path to Watch
+
+As you add your own directories to your bot, you'll want to add them to your `autoload_path` so that they can be hot-reloaded while in `development`. 
+
+{% hint style="info" %}
+In `production`Stealth will pre-load all files in the `autoload_paths` array to improve performance.
+{% endhint %}
+
+#### Adding a Single File
+
+To add the file `lib/some_file.rb` to the `autoload_path`, add this line to `config/autoload.rb`:
+
+```ruby
+Stealth.config.autoload_paths << File.join(Stealth.root, 'lib', 'some_file')
+```
+
+{% hint style="warning" %}
+Don't include the `.rb` extension to the filename.
+{% endhint %}
+
+#### Adding a Directory
+
+To add the entire `lib` directory to the `autoload_path`, add this line to `config/autoload.rb`:
+
+```ruby
+Stealth.config.autoload_paths << File.join(Stealth.root, 'lib')
+```

data/docs/dev-environment/logs.md

@@ -0,0 +1,74 @@
+# Logs
+
+Logs are the primary visibility mechanism into your bot. Stealth logs are designed to help you debug during development and also in production.
+
+Stealth logs all events to `stdout` instead of a log file. This avoids having to routinely clean your log files and also mimics typical production deployments.
+
+### Interpreting Logs
+
+Here are some sample log entries from the [Facebook Messenger](../platforms/facebook-messenger.md) platform:
+
+```
+Dec 28 18:31:33 sidekiq.1 info  pid=4 tid=590 class=Stealth::Services::HandleMessageJob jid=b08b6721a327c72aa5baa09f INFO: start
+Dec 28 18:31:33 sidekiq.1 info  TID-58w [user] User 3772279279459415 -> Received Message: What is Stealth?
+Dec 28 18:31:33 sidekiq.1 info  TID-58w [facebook] Requested user profile for 3772279279459415. Response: 200: {"id":"3772279279459415","name":"Leroy Jenkins","first_name":"Leroy","last_name":"Jenkins","profile_pic":"https:\/\/picsum.photos\/400"}
+Dec 28 18:31:33 sidekiq.1 info  TID-58w [primary_session] User 3772279279459415: setting session to hellos->say_hello
+Dec 28 18:31:33 sidekiq.1 info  TID-58w [previous_session] User 3772279279459415: setting to 
+Dec 28 18:31:33 web.1     info  TID-5hs [facebook] Received webhook.
+Dec 28 18:31:34 sidekiq.1 info  TID-58w [facebook] Transmitted. Response: 200: {"recipient_id":"3772279279459415"}
+Dec 28 18:31:34 sidekiq.1 info  TID-58w [facebook] User 3772279279459415 -> Sending: <typing indicator>
+Dec 28 18:31:37 sidekiq.1 info  TID-58w [facebook] Transmitted. Response: 200: {"recipient_id":"3772279279459415","message_id":"m_aukUQrqKbnxqm9FT6nBdZuuz3dIn4BVeTi4JX4XD8lJ2fSuuNXpN7SZkouaoC7SRrdrSDsqF--2Gi0KFZHkFNg"}
+Dec 28 18:31:37 sidekiq.1 info  TID-58w [facebook] User 3772279279459415 -> Sending: Hey Leroy, 👋 welcome to Stealth!
+Dec 28 18:31:37 sidekiq.1 info  TID-58w [facebook] Transmitted. Response: 200: {"recipient_id":"3772279279459415"}
+Dec 28 18:31:37 sidekiq.1 info  TID-58w [facebook] User 3772279279459415 -> Sending: <typing indicator>
+Dec 28 18:31:42 sidekiq.1 info  TID-58w [facebook] Transmitted. Response: 200: {"recipient_id":"3772279279459415","message_id":"m_5Dm01zkLp0Fj44QhvWYpq-uz3dIn4BVeTi4JX4XD8lLRkdqJ3g0yw0RA30Cpb06rkJPfDNGYs6BCV769e-nb7Q"}
+Dec 28 18:31:42 sidekiq.1 info  TID-58w [facebook] User 3772279279459415 -> Sending: Stealth is one of the fastest ways to create a bot.
+Dec 28 18:31:42 sidekiq.1 info  TID-58w [facebook] Transmitted. Response: 200: {"recipient_id":"3772279279459415"}
+Dec 28 18:31:42 sidekiq.1 info  TID-58w [facebook] User 3772279279459415 -> Sending: <typing indicator>
+Dec 28 18:31:49 sidekiq.1 info  TID-58w [facebook] Transmitted. Response: 200: {"recipient_id":"3772279279459415","message_id":"m_s9FICmzHaIi2hEVm2NDDvOuz3dIn4BVeTi4JX4XD8lJlfF98sBAAIos0GgjxrV4tNvIxq9_MW9qqPTO45e6gIA"}
+Dec 28 18:31:49 sidekiq.1 info  TID-58w [facebook] User 3772279279459415 -> Sending: Ready to get started?
+Dec 28 18:31:49 sidekiq.1 info  TID-58w [primary_session] User 3772279279459415: setting session to hellos->get_hello_response
+Dec 28 18:31:49 sidekiq.1 info  TID-58w [previous_session] User 3772279279459415: setting to hellos->say_hello
+```
+
+{% hint style="info" %}
+Transcript logging is enabled for the sample entries above.
+{% endhint %}
+
+#### Session Updates
+
+Each time Stealth changes the session for a user, the `previous_session` is stored as well. On Line 5 above, you can see the user does not have a previous session (`nil`) and so on Line 4 they are being sent to `hellos->say_hello`.
+
+After the replies are sent, you can see the session is updated again on Line 19 to `hellos->get_hello_response`. This time on Line 20 you can see there is a previous session to set and so we do.
+
+For more info about sessions and why Stealth stores the previous session, check out the [Session docs](../controllers/sessions/intro.md).
+
+#### Thread IDs
+
+Often times in production, you'll see a lot of entries all interlaced together depending on your bot's load. In the example above, there isn't a lot going on, but nonetheless you can see a couple different threads logging their events.
+
+Thread IDs begin with the prefix `TID-` followed by an alphanumeric string. Threads that have the same ID are the same thread. So in the example above, `TID-58w` are all the same background job started on Line 2. Following this thread ID will allow us to follow all the steps taken by this background job without getting confused by unrelated events.
+
+#### Event Topics
+
+After the thread ID, you can see the event topic wrapped in brackets (`[facebook]`). These will be color coded in your console. Session change events, component events, user events, etc are all labeled accordingly.
+
+#### Finding Events For a User
+
+Each Stealth component is designed to output the user's `session_id` where applicable. In the example above, you can see each Facebook entry is prefixed with `User 3772279279459415`.&#x20;
+
+In production this would allow you to search for the user's ID (`3772279279459415`) and you would be able to see all events for the user. This is really helpful for debugging.
+
+### Transcript Logging
+
+In order to see what your users type, in addition to what your bot sends out, you'll need to enable the transcript logging config setting. Check out the [docs for config settings](../config/settings.md).
+
+### Logging Custom Events
+
+If you want to add your own custom events to the log stream, you can use the Stealth`::Logger` class to log those events. This ensures your events will appear formatted like the stock Stealth events. The API for event logging is:
+
+```ruby
+Stealth::Logger.l(topic: 'your_topic', message: 'Your message.')
+```
+
+The `topic` can be any topic of your choosing and `message` is the string you want to log. If available, you'll want to include the user's `session_id` in the `message`. This will help you tail your logs for events related to particular user.

data/docs/dev-environment/procfile.md

@@ -0,0 +1,22 @@
+---
+description: Examining the contents of the Procfile
+---
+
+# Procfile
+
+If you used the generator to instantiate your bot, you'll find a `Procfile.dev` in the root directory of your bot. Here are the contents:
+
+```
+web: bundle exec puma -C config/puma.rb
+sidekiq: bundle exec sidekiq -C config/sidekiq.yml -q stealth_webhooks -q stealth_replies -r ./config/boot.rb
+```
+
+If you're not familiar with Procfiles, each line specifies a process name and command for the process. So in this default Procfile, we've specified 2 processes, `web` and `sidekiq`.
+
+### Sidekiq
+
+Currently, Stealth uses Sidekiq for processing background jobs. It is configured to monitor 2 queues by default: `stealth_webhooks` and `stealth_replies`. You can specify additional queues as needed by your bot by adding `-q <queue_name>` to the `sidekiq` Procfile entry.
+
+{% hint style="success" %}
+You can even use Sidekiq Pro and Sidekiq Enterprise if you have a license
+{% endhint %}