input-output-hk · joseph-fajen · Nov 17, 2023 · Nov 20, 2023 · Nov 20, 2023 · Nov 21, 2023
diff --git a/docs/developer-tools/payouts-dapp-prototype.md b/docs/developer-tools/payouts-dapp-prototype.md
@@ -0,0 +1,40 @@
+---
+title: Payouts DApp prototype
+sidebar_position: 3
+---
+
+## Discover, track, and withdraw role tokens
+
+The **[payouts DApp prototype](https://github.com/input-output-hk/marlowe-payouts)** is an example of a decentralized application designed to help users discover, track, and withdraw tokens from Marlowe smart contracts that use role tokens. It enables holders of role tokens in Marlowe smart contracts to withdraw the received funds, simplifying the process of tracking and withdrawing their payouts. 
+
+Since role tokens can be [**ada handles**](https://handle.tools/), [**ada domains**](https://www.adadomains.io/), or custom tokens, users have a lot of flexibility with how to use the payouts DApp component. 
+
+## Built with the Marlowe TS-SDK
+
+Marlowe developers built the payouts DApp prototype using the [**Marlowe TS-SDK**](https://github.com/input-output-hk/marlowe-ts-sdk), which provides a powerful way of writing web applications. The TS-SDK is a collection of JavaScript and TypeScript libraries that helps DApp developers interact with the Marlowe ecosystem. 
+
+## Intended use
+
+The payouts DApp prototype illustrates functionality that is available through the Marlowe TS-SDK. 
+
+DApp developers can think about the payout DApp from multiple points of view: 
+
+* as an example of a standalone application
+* as functionality that they could incorporate into a DApp 
+* as a component that they could integrate into a wallet. 
+
+For example, it is possible to integrate the payouts DApp into a wallet so that when you go to the wallet, you see all the available role tokens you can withdraw from Marlowe contracts without using a separate application. 
+
+## Use alongside Marlowe Runner
+
+Using the payouts DApp functionality alongside **[Runner](../getting-started/runner)**, you can connect a wallet authorized to receive funds to the payouts DApp when advancing a contract through Runner. Once the wallet is connected, Runner will display a list of contracts you are part of. 
+
+The payouts DApp lists available role tokens that an authorized role can withdraw for that wallet. The recipient clicks the ‘Withdraw’ button and sees a prompt to sign the transaction. After the recipient signs the transaction, the transaction is confirmed. The recipient can then see the funds in their wallet. 
+
+## Role tokens
+
+At a high level, role tokens are a unique feature of Marlowe smart contracts that provide additional security and flexibility. They are used to authorize transactions, and any participant in a contract can hold them. 
+
+Each participant in a Marlowe contract has a role, and each role has its own role token. Participants hold role tokens in their wallets and use them to authorize transactions. Participants who want to make a transaction include their role token as input. The token doesn’t stay with the script or go anywhere else; it simply passes through the script and returns to the participant, allowing them to authorize another transaction.
+
+Role tokens can be transferred between wallets, which means a participant can give their role to someone else. This feature introduces flexibility and security beyond the use of private keys alone.
diff --git a/docs/developer-tools/ts-sdk-intro.md b/docs/developer-tools/ts-sdk-intro.md
@@ -11,14 +11,15 @@ The **[Marlowe TypeScript SDK (TS-SDK)](https://github.com/input-output-hk/marlo
 1. **Smart contract toolkit**: Craft, deploy, and manage Marlowe smart contracts on the Cardano blockchain with the tools and libraries in the TS-SDK.
 2. **Integration with Marlowe Playground**: The TS-SDK works well with the Marlowe Playground, an online interface dedicated to designing, simulating, and scrutinizing Marlowe contracts.
 3. **Wallet connectivity**: With built-in modules, the TS-SDK promotes smooth interactions with various wallet extensions. This ensures easy access to wallet data and the efficient integration of Marlowe contracts with a variety of wallet interfaces.
-4. **Proof-of-concept (PoC) templates**: Embark on your DApp journey using the TS-SDK's distilled example templates. These PoC templates serve as launching pads for your customized applications.
+4. **Prototype DApp examples**: Embark on your DApp journey using the TS-SDK's distilled prototype examples. These prototypes serve as launching pads for your customized applications.
 
 ## Getting started
 To use the capabilities of the Marlowe TS-SDK, you will need to have a URL to a running instance of the Marlowe Runtime and a compatible wallet extension installed in your browser. Please refer to the **[Marlowe starter kit](https://github.com/input-output-hk/marlowe-starter-kit)** for guidance about accessing a running instance of the Runtime. 
 
-## PoC templates
+## Prototype examples
 
-- **[Marlowe payouts DApp](https://github.com/input-output-hk/marlowe-payouts)**: Engineered with the Marlowe TS-SDK, this DApp offers a streamlined approach to discerning and extracting payouts from Marlowe contracts on the Cardano blockchain. With a commitment to user experience, it ensures intuitive interactions and unhindered connectivity to the Cardano network.
+- **[Runner DApp prototype](../getting-started/runner)**: Developed in PureScript, Runner is a simple DApp you can use to deploy and progress your contract on Cardano easily from the browser, whether you are deploying to the preview, pre-production or mainnet network. 
+- **[Payouts DApp prototype](payouts-dapp-prototype.md)**: Engineered with the Marlowe TS-SDK, this DApp offers a streamlined approach to discerning and extracting payouts from Marlowe contracts on the Cardano blockchain. With a commitment to user experience, it ensures intuitive interactions and unhindered connectivity to the Cardano network.
 - **[Vesting prototype repo](https://github.com/input-output-hk/marlowe-vesting)**: Manages the phased allocation of shares over a designated time frame. Users can easily retrieve shares upon vesting. Tailored for projects that require the following sorts of capabilities: 
   - Tokenomics orchestration
   - Timed fund safeguards

diff --git a/docs/getting-started/runner.md b/docs/getting-started/runner.md
@@ -3,16 +3,29 @@ title: Runner
 sidebar_position: 6
 ---
 
-Runner is a DApp that is designed to deploy your contract to the blockchain, whether you are deploying to the preview, pre-production or mainnet network. 
+## A developer tool and a DApp for running contracts on the blockchain
 
-Once you have finished creating, simulating and testing your Marlowe smart contract, such as by using Marlowe Playground, you can then deploy your smart contract to Runner by using one of these methods: 
+Runner is a user-friendly developer tool and a simple DApp you can use to deploy and execute your contract on Cardano right from the browser, whether you are deploying to the preview, pre-production or mainnet network. 
 
-1. Send your contract to Runner by selecting the 'Send to Runner' button in Playground, or 
-2. Download your contract as a JSON file, then upload it to Runner. 
+Runner makes contract deployment simple for both DApp builders and traditional developers, enabling the execution of contracts created in Playground without requiring any backend orchestration or programming knowledge. 
 
-## Runner's ease of use
+## Customizable DApp template
 
-Using Runner is quite simple and intuitive. It requires no knowledge of command-line tools. You will only need to specify the network you want to work with, connect a wallet that is on the same network, and have your password details available so that you can sign transactions with your wallet. You will also need to have any required tokens or funds available in your wallet. 
+Furthermore, Marlowe Runner is an [**open-source developer application**](https://github.com/input-output-hk/marlowe-runner), making it easy for you to replicate it to create a customized end-user interface. So, not only does it serve as a tool for running contracts on the blockchain, but also as a customizable DApp template that you can use to create your own custom DApp for your precise use case.
+
+## Simple to use
+
+Using Runner requires no knowledge of command-line tools, so it is quite simple and intuitive to use. You will only need to specify the network you want to work with, connect a wallet that is on the same network, and have your password details available so that you can sign transactions with your wallet. You will also need to have any required tokens or funds available in your wallet. 
+
+### Deploying your contract
+
+Once you have finished creating, simulating and testing your Marlowe smart contract in the Playground, you can deploy your smart contract to Runner by using one of these methods: 
+
+1. From the Playground, select 'Send to Simulator,' then 'Export to Marlowe Runner.'
+2. Alternatively, download your contract from the Playground as a JSON file, then upload it to Runner. 
+
+> * [**Access Runner on the preview network**](https://preview.runner.marlowe.iohk.io/)
+> * [**Access Runner on the pre-production network**](https://preprod.runner.marlowe.iohk.io/)
 
 ## Technical details