diff --git a/_data/navigation.yml b/_data/navigation.yml
index 19dd34c9..a2906bf6 100644
--- a/_data/navigation.yml
+++ b/_data/navigation.yml
@@ -1,9 +1,6 @@
-- title: Tutorials
- docs:
- - browser/todo-list
-
- title: Authentication
docs:
+ - browser/todo-list
- develop/connect/overview
- develop/connect/get-started
- develop/profiles
diff --git a/browser/todo-list.md b/browser/todo-list.md
index d5529144..1db8106b 100644
--- a/browser/todo-list.md
+++ b/browser/todo-list.md
@@ -3,7 +3,7 @@
description: Single-page application with Blockstack
---
-# Todos app
+# Tutorial for App Integration
{:.no_toc}
In this tutorial, you will learn about Blockstack authentication and storage by installing, running and reviewing the code for a "Todos" web app built with Blockstack and [React](https://reactjs.org/).
diff --git a/develop/connect/overview.md b/develop/connect/overview.md
index cbb30dc9..cc3a5648 100644
--- a/develop/connect/overview.md
+++ b/develop/connect/overview.md
@@ -18,7 +18,84 @@ The library empowers you to:
## See it in action
-Here's what it looks like to register new users into an app with Blockstack Connect:
+## How does this compare to `blockstack.js`?
+
+Although [`blockstack.js`](https://github.com/blockstack/blockstack.js) can also be used to authenticate users, it implements the deprecated [Blockstack Browser](https://browser.blockstack.org/) and lacks any pre-built onboarding UI that educates users as to how your app is more secure for having implemented Blockstack. As such, we advise that you use `blockstack.js` for all other functionality apart from authentication, such as saving and retrieving user data with Gaia.
+
+## Start building with Blockstack Connect
+
+Head over to the [Tutorial for App Integration](/browser/todo-list.html) to learn how to build apps with Blockstack Connect.
+
+## Installation
+
+With yarn:
+
+```bash
+yarn add @blockstack/connect
+```
+
+With npm:
+
+```bash
+npm install --save @blockstack/connect
+```
+
+## Usage
+
+### AuthOptions
+
+Every major method you'll use with `connect` requires you to pass some options, like the name and icon of your app, and what to do when authentication is finished. In practice, this means you need to define these options, and pass them to the various API methods.
+
+The exact interface you'll use [is defined as](https://github.com/blockstack/connect/blob/master/src/auth.ts#L12:L24):
+
+```typescript
+export interface AuthOptions {
+ redirectTo: string;
+ finished: (payload: FinishedData) => void;
+ sendToSignIn?: boolean;
+ userSession?: UserSession;
+ appDetails: {
+ name: string;
+ icon: string;
+ };
+}
+```
+
+parameter | type | default | optional | description
+---|---|---|---|---
+redirectTo | string | | false | The path in your app where users go after sign in.
+appDetails | object | | false | an object which includes `appName: string` and `appIcon: string`. This will speed up the process of loading your app's information during onboarding.
+finished | function | | false | A callback that can be invoked after authentication. This prevents having to do a whole page refresh in a new tab. One argument is passed to this callback, which is an object with `userSession` included. If included, then the `redirectTo` path is ignored, and the user will be logged in automatically.
+sendToSignIn | boolean | false | true | Whether the user should go straight to the 'sign in' flow (false) or be presented with the 'sign up' flow (true) instead.
+userSession | UserSession | | false | pass a `UserSession` instance to use for authentication. If it's not passed, `@blockstack/connect` will create one for you.
+
+
+### In React Apps
+
+If you're using `connect` in a React app, then the best option is to include `connect`'s React Provider and hooks in your React app.
+
+First, setup the `Connect` provider at the "top-level" of your app - probably next to wherever you would put a Redux provider, for example.
+
+```javascript
+import { Connect } from '@blockstack/connect';
+
+const authOptions = {
+ redirectTo: '/',
+ finished: ({ userSession }) => {
+ console.log(userSession.loadUserData());
+ },
+ appDetails: {
+ name: 'My Cool App',
+ icon: 'https://example.com/icon.png',
+ },
+};
+
+const App = () => (
+
+ // the rest of your app's components
+
+)
+```
**insert video**
diff --git a/storage/hub-choice.md b/storage/hub-choice.md
deleted file mode 100644
index f24c301e..00000000
--- a/storage/hub-choice.md
+++ /dev/null
@@ -1,112 +0,0 @@
----
-description: "Storing user data with Blockstack"
----
-# Hubs and user choice
-
-{% include note.html content="The functionality described in this tutorial has been deprecated with the Blockstack Browser. It will continue working only for apps that have not yet upgraded to Blockstack Connect." %}
-
-Blockstack operates a default Gaia storage hub at `https://hub.blockstack.org`.
-Individuals or organizations may also run their own hubs, either as a for-profit
-service or for other reasons.
-
-## Background
-
-Each user with an identity in the Blockstack Network has a Gaia hub
-configured on their profile. New users that create identities with the
-Blockstack Browser automatically are given storage on this default hub. For a
-user to have a storage hub other than this default, the user must create an
-identity through an application that enables storage hub selection.
-
-{% include note.html content="Users with existing identities cannot yet migrate
-their data from one hub to another." %}
-
-## Enable the Gaia hub URL option for new users
-
-A major principle of Blockstack applications is that DApps do not store or
-replicated user data. Through the Gaia feature, Blockstack seeks to empower
-users to choose where to store their data and how they manage it.
-
-As a step towards fulfilling this principle, DApp developers can configure their
-application to prompt new users to provide a Gaia hub URL. An application with
-this feature enabled presents users creating an identity for the first time
-with this prompt:
-
-
-
-Users can choose to **Use Blockstack's official provider** or **Use a different provider**. Choosing the non-default option prompts the user with the following:
-
-
-
-Users can enter the HTTPS address of a hub hosted by an entity other than
-Blockstack. Once the user submits the above form, they continue through the
-standard identity creation. As they use DApps on the Blockstack Network, all
-their data is stored in this storage hub and not the default Blockstack hub.
-
-## Enabling hub selection in your DApp
-
-To enable this feature, you must ensure your DApp is using the latest version of the blockstack.js library. Instead of the default flow `redirectToSignIn()` method, you must use the `makeAuthRequest()` method. This method takes the following parameters:
-
-
- -
-
transitPrivateKey(String = generateAndStoreTransitKey())
-
- - A HEX encoded transit private key.
- -
-
redirectURI(String = `${window.location.origin}/`)
-
- - Location to redirect the user to after sign in approval.
- -
-
manifestURI(String = `${window.location.origin}/manifest.json`)
-
- -
- Location of this app's manifest file.
-
- -
-
scopes (Array = DEFAULT_SCOPE)
-
- - The permissions this app is requesting.
- -
-
appDomain(String = window.location.origin)
-
- - The origin of this app.
- -
-
expiresAt(Number = nextHour().getTime())
-
- - The time at which this request is no longer valid.
- -
-
extraParams(Object = {})
-
- - Any extra parameters to pass to the authenticator. Use this to pass options that aren't part of the Blockstack authentication specification, but might be supported by special authenticators.
-
-
-To ensure your DApps identity creation flow includes the Gaia URL, modify the `makeAuthRequest()` method to apply the `solicitGaiaHubUrl` parameter with value `true` when executing the method:
-
-```javascript
-import {
- makeAuthRequest,
- redirectToSignInWithAuthRequest
-} from 'blockstack';
-
-const authRequest = makeAuthRequest(
- generateAndStoreTransitKey(),
- 'http://localhost:8080/',
- 'http://localhost:8080/manifest.json',
- ['store_write', 'publish_data'],
- 'http://localhost:8080/',
- nextHour().getTime(), {
- solicitGaiaHubUrl: true
- } // new options param
-);
-redirectToSignInWithAuthRequest(authRequest);
-```
-
-You can also pass a suggested Gaia storage hub URL also. For example, you might
-do this if you have a corporate client whose employees would all like to use
-your application with a company-run Gaia hub. To do this, you provide an
-additional `recommendedGaiaHubUrl` value alongside the `solicitGaiaHubUrl`
-
-
-## Related information
-{:.no_toc}
-
-[Hello, Hub Choice Tutorial](hello-hub-choice.html) for a tutorial on using the [`makeAuthRequest()`](https://blockstack.github.io/blockstack.js/#makeauthrequest) method.
diff --git a/storage/hub-operation.md b/storage/hub-operation.md
index fd45760d..e3912bd6 100644
--- a/storage/hub-operation.md
+++ b/storage/hub-operation.md
@@ -2,6 +2,9 @@
description: "Storing user data with Blockstack"
+redirect_from:
+- /storage/hello-hub-choice.html
+
---
# Understand hub operation
{:.no_toc}