diff --git a/doc/decent/about-noms.md b/doc/decent/about-noms.md
deleted file mode 100644
index f1b97fa529..0000000000
--- a/doc/decent/about-noms.md
+++ /dev/null
@@ -1,48 +0,0 @@
-[About Noms](about-noms.md) | [How to Use Noms](how-to-use-noms.md) | [Demo App](demo-app.md) | [Vision](vision.md) | [What's Next](whats-next.md)
-
-[](http://jenkins3.noms.io/job/NomsMasterBuilder/)
-[](https://codecov.io/gh/attic-labs/noms)
-[](https://godoc.org/github.com/attic-labs/noms)
-[](http://slack.noms.io)
-
-# About Noms
-
-[Noms](http://noms.io) is a database for decentralized
-applications. It stores structured data (ints, strings, blobs, maps,
-lists, structs, etc) and like most databases it features atomic
-transactions, efficient searches, scans, reads, and updates.
-
-Unlike any other database, Noms is built for the decentralized
-web. Any number of dapp peers can concurrently modify their own copies
-of the same Noms database and continuously sync their changes with
-each other. In this sense noms works like git: changes are bundled as
-commits which reference previous states of the database. Apps pull
-changes from peers and merge them using a principled set of APIs and
-strategies. Except that rather than users manually pulling and
-merging, applications typically do this continuously, automatically
-converging to a shared state.
-
-Noms stores data in the blockstore of your choice. For example you
-could back Noms with a decentralized blockstore like IPFS. In this
-configuration, read and write load is spread throughout the
-network. If for some reason you wanted to sync to a centralized
-service you could do that to (for example, S3).
-
-Your application uses a [Go client library](https://github.com/attic-labs/noms/blob/master/doc/go-tour.md) to interact with Noms
-data. There is also a command-line interface for working with data and
-initial support for a GraphQL-based query language.
-
-Some additional features include:
-* **Versioning**: noms is git-like, so it’s easy to use, compare, or revert to older database versions
-* **Efficient diffs**: diffing even huge datasets is efficient due to
- noms’ use of a novel BTree-like data structure called a [Prolly
- Tree](../intro.md#prolly-trees-probabilistic-b-trees)
-* **Efficient storage**: data are chunked and content-addressable, so
- there is exactly one copy of each chunk in the database, shared by
- other data that reference it. Small changes to massive data
- structures always result in small operations.
-* **Verifiable**: The entire database rolls up to a single 20-byte hash
- that uniquely represents the database at that moment - anyone can
- verify that a particular database hashes to the same value
-
-Read the [Noms design overview](../intro.md).
diff --git a/doc/decent/about.md b/doc/decent/about.md
new file mode 100644
index 0000000000..10b756312f
--- /dev/null
+++ b/doc/decent/about.md
@@ -0,0 +1,64 @@
+[About Noms](about-noms.md) | [How to Use Noms](how-to-use-noms.md) | [Demo App](demo-app.md) | [Vision](vision.md) | [What's Next](whats-next.md)
+
+[](http://jenkins3.noms.io/job/NomsMasterBuilder/)
+[](https://codecov.io/gh/attic-labs/noms)
+[](https://godoc.org/github.com/attic-labs/noms)
+[](http://slack.noms.io)
+
+# Noms -- The Decentralized Database
+
+[Noms](http://noms.io) makes it ~~easy~~ tractable to create rich,
+multiuser, collaborative, fully-decentralized applications.
+
+Like most databases, Noms features a rich data model, atomic
+transactions, support for large-scale data, and efficient searches,
+scans, reads, and updates.
+
+Unlike any other database, Noms has built-in multiparty sync and
+conflict resolution. Any number of dapp peers in a P2P network can
+concurrently modify the same logical Noms database, and continuously
+and efficiently sync their changes with each other. All peers will
+converge to the same state.
+
+For many applications, peers can store an entire local copy of the
+data they are interested in. For larger applications, it should be
+possible to back Noms by a decentralized blockstore like IPFS, Swarm,
+or Sia (or in the future, Filecoin), and store large-scale data in a
+completely decentralized way, without replicating it on every
+node. Noms also has a blockstore for S3, which is ideal for
+applications that have some centralized components.
+
+## How it Works
+
+Think of Noms like a programmable Git: changes are bundled as commits
+which reference previous states of the database. Apps pull changes
+from peers and merge them using a principled set of APIs and
+strategies. Except that rather than users manually pulling and
+merging, applications typically do this continuously, automatically
+converging to a shared state.
+
+Your application uses a [Go client
+library](https://github.com/attic-labs/noms/blob/master/doc/go-tour.md)
+to interact with Noms data. There is also a [command-line
+interface](https://github.com/attic-labs/noms/blob/master/doc/cli-tour.md)
+for working with data and initial support for a [GraphQL-based query
+language](https://github.com/attic-labs/noms/blob/master/go/ngql/README.md).
+
+Some additional features include:
+* **Versioning**: It’s easy to use, compare, or revert to older database versions
+* **Efficient diffs**: diffing even huge datasets is efficient due to
+ noms’ use of a novel BTree-like data structure called a [Prolly
+ Tree](../intro.md#prolly-trees-probabilistic-b-trees)
+* **Efficient storage**: data are chunked and content-addressable, so
+ there is exactly one copy of each chunk in the database, shared by
+ other data that reference it. Small changes to massive data
+ structures always result in small operations.
+* **Verifiable**: The entire database rolls up to a single 20-byte hash
+ that uniquely represents the database at that moment - anyone can
+ verify that a particular database hashes to the same value
+
+Read the [Noms design overview](../intro.md).
+
+*If you’d like to use noms in your project we’d love to hear from you*:
+drop us an email ([noms@attic.io](mailto:noms@attic.io)) or send us a
+message in slack ([slack.noms.io](http://slack.noms.io)).
diff --git a/doc/decent/architectures.md b/doc/decent/architectures.md
new file mode 100644
index 0000000000..8b13789179
--- /dev/null
+++ b/doc/decent/architectures.md
@@ -0,0 +1 @@
+
diff --git a/doc/decent/demo-app.md b/doc/decent/demo-ipfs-chat.md
similarity index 75%
rename from doc/decent/demo-app.md
rename to doc/decent/demo-ipfs-chat.md
index cdd4dd3151..9474c7fc09 100644
--- a/doc/decent/demo-app.md
+++ b/doc/decent/demo-ipfs-chat.md
@@ -5,11 +5,11 @@
[](https://godoc.org/github.com/attic-labs/noms)
[](http://slack.noms.io)
+# Demo App: IPFS-based Decentralized Chat
-
-# Sample App: IPFS-based Decentralized Chat
-
-Demo app code is in the [ipfs-chat](https://github.com/attic-labs/noms/tree/master/samples/go/ipfs-chat/) directory. To get it up and running take the following steps:
+Demo app code is in the
+[ipfs-chat](https://github.com/attic-labs/noms/tree/master/samples/go/ipfs-chat/)
+directory. To get it up and running take the following steps:
* Use git to clone the noms repository onto your computer:
```
git clone git@github.com:attic-labs/noms.git or git clone https://github.com/attic-labs/noms.git
@@ -27,9 +27,14 @@ go build
./ipfs-chat client --username --node-idx=2 ipfs:/tmp/ifps2::chat
```
-If desired, ipfs-chat can be run as a daemon which will replicate all chat content in a local store which will enable clients to go offline without causing data to become unavailable to other clients:
+If desired, ipfs-chat can be run as a daemon which will replicate all
+chat content in a local store which will enable clients to go offline
+without causing data to become unavailable to other clients:
+
```
./ipfs-chat daemon --node-idx=3 ipfs:/tmp/ifps3::chat
```
-Note: the 'node-idx' argument ensures that each IPFS-based program uses a distinct set of ports. This is useful when running multiple IPFS-based programs on the same machine.
+Note: the 'node-idx' argument ensures that each IPFS-based program
+uses a distinct set of ports. This is useful when running multiple
+IPFS-based programs on the same machine.
diff --git a/doc/decent/demo-p2p-chat.md b/doc/decent/demo-p2p-chat.md
new file mode 100644
index 0000000000..8b13789179
--- /dev/null
+++ b/doc/decent/demo-p2p-chat.md
@@ -0,0 +1 @@
+
diff --git a/doc/decent/how-to-use-noms.md b/doc/decent/quickstart.md
similarity index 99%
rename from doc/decent/how-to-use-noms.md
rename to doc/decent/quickstart.md
index 0f280ba6ad..43210c81c7 100644
--- a/doc/decent/how-to-use-noms.md
+++ b/doc/decent/quickstart.md
@@ -5,7 +5,6 @@
[](https://godoc.org/github.com/attic-labs/noms)
[](http://slack.noms.io)
-
# How to Use Noms in a Decentralized App
If you’d like to use noms in your project we’d love to hear from you:
diff --git a/doc/decent/whats-next.md b/doc/decent/status.md
similarity index 99%
rename from doc/decent/whats-next.md
rename to doc/decent/status.md
index d6853a2c6e..00cf641639 100644
--- a/doc/decent/whats-next.md
+++ b/doc/decent/status.md
@@ -5,7 +5,6 @@
[](https://godoc.org/github.com/attic-labs/noms)
[](http://slack.noms.io)
-
# What's next for Noms?
Our primary goal (as of 9/2017) is to **find users to drive the future
diff --git a/doc/decent/vision.md b/doc/decent/vision.md
deleted file mode 100644
index e39a769091..0000000000
--- a/doc/decent/vision.md
+++ /dev/null
@@ -1,28 +0,0 @@
-[About Noms](about-noms.md) | [How to Use Noms](how-to-use-noms.md) | [Demo App](demo-app.md) | [Vision](vision.md) | [What's Next](whats-next.md)
-
-[](http://jenkins3.noms.io/job/NomsMasterBuilder/)
-[](https://codecov.io/gh/attic-labs/noms)
-[](https://godoc.org/github.com/attic-labs/noms)
-[](http://slack.noms.io)
-
-
-# Vision
-
-*Noms enables developers to build rich decentralized applications.*
-
-Decentralization promises to be the next great evolution of the Web. But developers today struggle to create even simple decentralized applications because there are no databases that work well in a decentralized environment.
-
-Our vision is to provide a database native to the decentralized web that includes:
-
-1. Efficient and correct multiparty sync and conflict resolution
-1. Search across the entire network, including data that isn’t local
-1. Paging of data from the network “lazily” as needed
-1. Enforcement of business logic
-1. Load-spreading to minimize hotspots
-1. Data persistence: data should not lost when a node disconnects or goes away
-
-This vision is achievable. Today Noms can do (1), (2), and (3). We
-have ideas for how to solve (4). Bittorrent and IPFS are existence
-proofs for (5). We do not yet have a solution for (6), though there
-are several promising efforts underway that may in the future provide
-some of the tools we need (e.g., Filecoin).
diff --git a/doc/olap/about.md b/doc/olap/about.md
new file mode 100644
index 0000000000..44626f650e
--- /dev/null
+++ b/doc/olap/about.md
@@ -0,0 +1,4 @@
+# Noms -- the OLAP database-in-a-bucket
+
+[Noms](http://noms.io) ... {description of OLAP use case,
+similar to what we have for [the decentralized use case](/docs/decent/about.md)}