Adds notes to center user's learnings on each page + provide a succinct

summary

docs/concepts/actions.rst

@@ -4,6 +4,12 @@ Actions
 
 .. _actions:
 
+.. note::
+
+    Actions are the core building block of Burr. They read from state and write to state.
+    They can be synchronous and asynchonous, and have both a ``sync`` and ``async`` API.
+    There are both function and class-based APIs.
+
 
 Actions do the heavy-lifting in a workflow. They should contain all complex compute. You can define actions
 either through a class-based or function-based API. If actions implement ``async def run`` then will be run in an

docs/concepts/additional-visibility.rst

@@ -2,9 +2,10 @@
 Additional Visibility
 =====================
 
-Burr comes with the ability to see inside your actions. This is a very pluggable framework
-that comes with the default tracking client.
+.. note::
 
+    Burr comes with the ability to see inside your actions. This is a very pluggable framework
+    that comes with the default tracking client, but can also be hooked up to tools such as `OpenTelemetry <https://opentelemetry.io/>`_
 
 -------
 Tracing

docs/concepts/hooks.rst

@@ -3,6 +3,10 @@ Hooks
 =====
 
 .. _hooks:
+.. note::
+
+    Hooks allow you to customize every aspect of Burr's execution, plugging in whatever tooling,
+    observability framework, or debugging tool you need.
 
 Burr has a system of lifecycle adapters (adapted from the similar `Hamilton <https://github.com/dagworks-inc/hamilton>`_ concept), which allow you to run tooling before and after
 various places in a node's execution. For instance, you could:

docs/concepts/index.rst

@@ -9,13 +9,13 @@ Overview of the concepts -- read these to get a mental model for how Burr works.
 .. toctree::
     :maxdepth: 2
 
-    state-machine
-    state
     actions
+    state
+    state-machine
     transitions
-    hooks
     tracking
     state-persistence
     streaming-actions
+    hooks
     additional-visibility
     planned-capabilities

docs/concepts/state-machine.rst

@@ -4,6 +4,11 @@ Applications
 
 .. _applications:
 
+.. note::
+
+    Applications tie everything in Burr together. They specify which actions should be included,
+    how they connect (including conditional edges), and how to run.
+
 Applications form the core representation of the state machine. You build them with the ``ApplicationBuilder``.
 Here is the minimum that is required:
 
@@ -18,18 +23,15 @@ This is shown in the example from :ref:`getting started <simpleexample>`
     from burr.core import ApplicationBuilder, default, expr
     app = (
         ApplicationBuilder()
-        .with_state(counter=0) # initialize the count to zero
-        .with_actions(
-            count=count, # add the counter action with the name "counter"
-            done=done # add the printer action with the name "printer"
-        ).with_transitions(
-            ("count", "count", expr("counter < 10")), # Keep counting if the counter is less than 10
-            ("count", "done", default) # Otherwise, we're done
-        ).with_entrypoint("counter") # we have to start somewhere
+        .with_actions(human_input, ai_response)
+        .with_transitions(
+            ("human_input", "ai_response"),
+            ("ai_response", "human_input")
+        ).with_state(chat_history=[])
+        .with_entrypoint("human_input")
         .build()
     )
 
-
 -------
 Running
 -------

docs/concepts/state-persistence.rst

@@ -4,6 +4,13 @@ State Persistence
 
 .. _state-persistence:
 
+.. note::
+
+    Burr comes with a core set of APIs that enable state `persistence` -- the ability
+    to save and load state automatically from a database. This enables you to launch an application,
+    pause it, and restart where you left off. The API is customizable, and works with any database you want.
+
+
 The key to writing a real life ``burr`` application is state persistence. For example, say you're building a chat bot and you
 want to store the conversation history and then reload it when you restart. Or, you have a long running process/series of agents,
 and you want to store the state of the process after each action, and then reload it if it fails, etc....

docs/concepts/state.rst

@@ -4,6 +4,11 @@ State
 
 .. _state:
 
+.. note::
+
+    Burr's ``State`` API enables actions to talk to each other, and enables you to persist data.
+    Burr has a ``State`` API that allows you to manipulate state in a functional way.
+
 The ``State`` class provides the ability to manipulate state for a given action. It is entirely immutable,
 meaning that you can only create new states from old ones, not modify them in place.
 

docs/concepts/streaming-actions.rst

@@ -4,6 +4,11 @@ Streaming Actions
 
 .. _streaming_actions:
 
+.. note::
+
+    Burr actions can stream results! This enables you to display results to the user as
+    tokens are streamed in.
+
 Actions can be implemented as streaming results. This enables a lower time-to-first-token and a more interactive
 interface in the case of AI applications or streaming in of metrics in a model-training application. Broadly,
 this is a tool to enable quicker user interaction in longer running actions that require user focus.

docs/concepts/tracking.rst

@@ -4,6 +4,12 @@
 Tracking Burr
 =============
 
+.. note::
+
+    Burr's telemetry system is built in and easy to integrate. It allows you to understand
+    the flow of your application, and watch it make decisions in real time. You can run it
+    with sample projects by running ``burr`` in the terminal after ``pip install "burr[start]"``.
+
 Burr comes with a telemetry system that allows tracking a variety of information for debugging,
 both in development and production.
 

docs/concepts/transitions.rst

@@ -4,6 +4,12 @@ Transitions
 
 .. _transitions:
 
+.. note::
+
+    While actions form the steps taken in an `application`, transitions decide which one to do next.
+    They make decisions based on state. You can use them to specify which model to call, whether a conversation is
+    over, or any other decision that needs to be made based on the current state.
+
 Transitions define explicitly how actions are connected and which action is available next for any given state.
 You can think of them as edges in a graph.