ipfs · johnnymatthews · Jan 7, 2021 · Jan 5, 2021 · Jan 5, 2021 · Jan 6, 2021
diff --git a/docs/how-to/companion-node-types.md b/docs/how-to/companion-node-types.md
@@ -5,77 +5,94 @@ description: Learn about the available node types in IPFS Companion.
 
 # Understand node types in IPFS Companion
 
-There are four available node types in IPFS Companion:
+IPFS Companion's preferences screen allows you to choose from several different node types. The available types you'll see in your Companion preferences depends on the browser you're using (i.e. Firefox, Chrome, Brave), but the full list is as follows:
 
-1. External
-2. Embedded
-3. Embedded + `chrome.sockets`
-4. Public
+[[toc]]
 
-![Screenshot of node type switch](./images/node-type-switch.png)
+![Screenshot of node type selector in Companion preferences](./images/node-type-switch.png)
 
-When in doubt, use the _External_ node type running on your localhost. Some options for doing so:
+**If you're already running a local IPFS node, choose _External_.** If not, do one of the following:
 
-- Use the [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) GUI app (for Windows/Linux/Mac), which installs and manages a local IPFS node for you
-- If you prefer a more hands-on approach:
-  - Install IPFS by following the [command line quick-start guide](command-line-quick-start.md)
-  - Or run it in [Docker](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker)
-- If you are using [Brave](https://brave.com/), feel you may want to experiment with _embedded + `chrome.sockets`_ (see below); you can always switch back to _External_ with local IPFS Desktop
+- [Install](/install) and run IPFS as an [external node](#external) (recommended).
+- Use a [native node](#native) built into your browser (Brave v1.19 or later only) or the [embedded node](#embedded) built into Companion.
 
 ## External
 
-An _external_ node can be any instance of an IPFS daemon that runs outside of a web browser process and exposes _Gateway_ and writable _API_ over HTTP at TCP ports.
+An _external_ node can be any instance of an IPFS daemon that:
 
-At this time, the [go-ipfs](https://github.com/ipfs/go-ipfs) daemon is the preferred implementation. It is easier on CPU, and provides `dhtclient` mode, which
-decreases ambient bandwidth use and smaller battery drain (key characteristics of something that is expected to run in the background all the time).
+- Runs outside of your web browser.
+- Exposes a _gateway_ and writeable _API_ over HTTP at TCP ports.
 
-A good practice is to run it on localhost (`127.0.0.1`), as it provides:
+The [go-ipfs](https://github.com/ipfs/go-ipfs) implementation of IPFS is the recommended choice for running an external IPFS node. It's less power-hungry than other implementations and uses the `dhtclient` mode to decrease ambient bandwidth use and reduce battery drain.
 
-- Increased security (native IPFS used as end-to-end transport)
-- Better UX in the browser (no mixed-content warnings)
-- Improved performance (local loopback is used, no network overhead)
+A good practice is to run your go-ipfs daemon on localhost (`127.0.0.1`), as it provides:
 
-Don't know where to start? See the [command line quick-start guide](command-line-quick-start.md).
+- Increased security: native IPFS used as end-to-end transport.
+- Better UX in the browser: no mixed-content warnings.
+- Improved performance: local loopback is used, so no network overhead.
 
-## Embedded
+You can get started with running a go-ipfs node on your local machine in several ways:
 
-An _embedded_ node is a js-ipfs instance running in the browser (in-memory), without the need for any external software. It is a work in progress, but can be used for development and experimentation (e.g. for testing a dApp that uses `window.ipfs` without having to install and start up your own IPFS daemon).
+- [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop) installs and manages a local node for you, as well as offering an easy, convenient user interface for managing files and peers.
+- If you're comfortable with the command line and don't need the convenience of the IPFS Desktop UI, follow the directions in the [command line quick-start guide](/how-to/command-line-quick-start/).
+- Docker fans can run and use go-ipfs from [inside a Docker container](https://github.com/ipfs/go-ipfs#running-ipfs-inside-docker).
 
-Power users can provide [custom config](https://github.com/ipfs/js-ipfs#faq) (e.g. to enable experimental pubsub) via the IPFS Companion [Preferences](https://user-images.githubusercontent.com/157609/38084660-0b97c0cc-334e-11e8-9368-823345ced67f.png)
+## Native
 
-**Note:** At present, embedded js-ipfs running within webextension (browser context) comes with some limitations:
+### Provided by Brave
 
-- Can't act as an HTTP gateway (extension uses public one as a fallback)
-- Known to be CPU-hungry
-  ([#450](https://github.com/ipfs-shipyard/ipfs-companion/issues/450), [ipfs/js-ipfs#1190](https://github.com/ipfs/js-ipfs/issues/1190)) over time, which may drain your battery
-- Missing DHT ([js-ipfs/#856](https://github.com/ipfs/js-ipfs/pull/856))
-- Default transports limited to websockets ([js-ipfs/#1088](https://github.com/ipfs/js-ipfs/issues/1088))
-  - Lack of connection closing ([ipfs/js-ipfs#962](https://github.com/ipfs/js-ipfs/issues/962))
-  - Missing relay discovery ([js-ipfs/v0.29.x/examples/circuit-relaying](https://github.com/ipfs/js-ipfs/tree/v0.29.3/examples/circuit-relaying))
-- An embedded node _does not run_ when external node is selected.; every time you switch back to the embedded node, a new instance is created on-demand, and it can take a few seconds for a brand new node to find peers
+Users of the [Brave](https://brave.com/) browser (v1.19 or later) can enable native support for IPFS using a go-ipfs node built directly into the browser itself. This is a great way to experiment with IPFS without having to install or run IPFS Desktop or the command-line daemon.
 
-**When in doubt, run go-ipfs as an external node instead.**
+This node type offers the same benefits as an [external](#external) node, with additional features provided within Brave itself:
 
-## Embedded + `chrome.sockets`
+- Native support for `ipfs://` and `ipns://` URIs:
+  - Built-in fallback to a public gateway.
+  - Ability to change your preferred public gateway from Brave's settings page.
+  - Options for default resolution of IPFS resources: through a public gateway, through a local node, or asking each time.
+- The IPFS node is managed by Brave itself:
+  - Automatic go-ipfs updates and migrations.
+  - Your node is only running when Brave is open.
+  - You can start/stop your Brave-based node by clicking the power button icon in IPFS Companion's main menu.
 
-This node type replaces the regular _embedded_ type if the browser vendor grants us access to `chrome.sockets` APIs. These powerful APIs enable embedded js-ipfs to provide a true p2p experience without the need for an external daemon:
+::: tip TOOLS FOR BRAVE USERS
 
-### HTTP gateway
+- `ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi`
+  Popular URI for triggering and testing native IPFS support
+- `brave://settings/extensions`
+  One-click Companion install and URI resolution settings
+- `brave://ipfs`
+  Status page for Brave's built-in go-ipfs node
+
+:::
+
+## Embedded
 
-- Access IPFS resources over HTTP without relying on a public gateway
-- Automatically pick a free localhost port
+An _embedded_ node is a js-ipfs instance running in the browser in-memory, without the need for any external software.
 
-### TCP transport
+::: warning
 
-- Embedded js-ipfs is able to connect to go-ipfs
-- go-ipfs is able to connect to embedded js-ipfs
+This node type is only for development and experimentation. Most users should use [external](#external) or [native](#native) node types instead.
 
-### Local discovery (mDNS/DNS-SD)
+:::
+
+Power users can provide [custom config](https://github.com/ipfs/js-ipfs#faq) (e.g. to enable experimental pubsub) via the IPFS Companion [Preferences](https://user-images.githubusercontent.com/157609/38084660-0b97c0cc-334e-11e8-9368-823345ced67f.png)
+
+Please note that there are some limitations when running an embedded js-ipfs instance in the browser context using Companion:
+
+- Embedded js-ipfs cannot act as an HTTP gateway; the extension uses a public one as a fallback.
+- Running an embedded js-ipfs instance is known to be CPU-hungry over time, which may drain your battery. See GitHub issues ([#450](https://github.com/ipfs-shipyard/ipfs-companion/issues/450) and [ipfs/js-ipfs#1190](https://github.com/ipfs/js-ipfs/issues/1190)) for further details
+- Missing DHT (see [js-ipfs/#856](https://github.com/ipfs/js-ipfs/pull/856)).
+- Default transports limited to websockets ([js-ipfs/#1088](https://github.com/ipfs/js-ipfs/issues/1088)):
+  - Lack of connection closing ([ipfs/js-ipfs#962](https://github.com/ipfs/js-ipfs/issues/962))
+  - Missing relay discovery ([js-ipfs/v0.29.x/examples/circuit-relaying](https://github.com/ipfs/js-ipfs/tree/v0.29.3/examples/circuit-relaying))
+- An embedded node _does not run_ when an external node is selected; every time you switch back to the embedded node, a new instance is created on demand, and it can take a few seconds for a newly running node to find peers.
 
-- Embedded node discovers go-ipfs in the LAN and automatically connects to it
+### Embedded + `chrome.sockets` (deprecated)
 
-**Note:** This is still a work in progress. see [Embedded JS-IPFS in Brave](https://github.com/ipfs-shipyard/ipfs-companion/issues/716) for the current status.
+::: warning
+This node type has been deprecated and is no longer supported by Chromium browsers. While this option still appears in IPFS Companion preferences, users of this node type are strongly urged to migrate to a different node type.
+:::
 
 ## Public
 
-A _public_ node is not a part of the toggle UI. It is used as an implicit fallback for its gateway functionality when an external node is offline or an embedded node is used. It does not expose the API port.
+A _public_ node is used as a fallback for gateway functionality when an external node is offline or an embedded node is used. It does not expose the API port. This type of node is not included as an option in Companion's preferences.