diff --git a/docs-internal/github-guide.md b/docs-internal/github-guide.md
new file mode 100644
index 00000000..60e356ca
--- /dev/null
+++ b/docs-internal/github-guide.md
@@ -0,0 +1,235 @@
+# GitHub guide for contributors
+
+## An introduction to Git and GitHub
+
+Git is a system that enables thousands of people to work together on projects without central coordination.
+
+Because of how useful this is, Git has a whole ecosystem built around it. You can think of Git as a tree trunk, and the services built around it as branches. One of these services is **GitHub**.
+
+GitHub is a site optimized for hosting and sharing Git repositories (repositories are just a fancy name for projects). And while you don't strictly need GitHub to use Git, you'll find that it makes your life considerably easier.
+
+At Aragon we choose to put a copy of our Git repository on GitHub for three reasons:
+
+1. It's a full backup of our code (including the full history of changes).
+
+1. It has an excellent User Interface that makes future collaboration easy.
+
+1. It offers convenient ways to browse and search through our codebase.
+
+## Editing a document on GitHub
+
+Now that you have a high-level overview of both Git and GitHub, we're ready to cover how to edit a document.
+
+If you don't have a GitHub account already, the first thing you should do is [sign up for one](https://github.com/join). Follow the instructions to create your account. It shouldn't take more than a couple of minutes.
+
+The next step is to open the [Getting Started page](https://hack.aragon.org/docs/getting-started) of the hack Aragon docs.
+
+You should find that there is a light blue **EDIT** button in the top-right corner the page. This button is available on every page of the Aragon docs.
+
+
+
+Click on it. You'll be taken to a GitHub copy of the page.
+
+
+
+You should see a small pencil icon on the right. When you hover over it, it will turn blue, and you'll see a small tooltip appear above it with the words:
+
+> Edit the file in your fork of this project
+
+
+
+[A fork](https://help.github.com/en/articles/fork-a-repo) is just GitHub's term for a copy of a project. In other words, clicking on the pencil icon tells GitHub to:
+
+1. Create a copy (fork) of the project under your account.
+
+1. Open up your copy of the Getting Started page for editing
+
+Why do we need to fork? Why not just make changes directly in the original project?
+
+Forking a project allows us to freely experiment with changes without affecting the original project. Put another way, a fork allows us to test out changes without messing up the work done in the original.
+
+Later on, when we're happy with our changes, we can use our fork to propose changes to the original project.
+
+Click on the pencil icon. You should be directed to a page with a built-in document editor.
+
+
+
+At the top you should see a message highlighted in a blue box. Don't worry about understanding what it means at this stage.
+
+Right below this blue box you should see a line that reads:
+
+> hack / docs / getting-started.md
+
+
+
+This line gives us the location as well as the name of the document we are currently editing. In this case **getting-started.md** is the name of the document, and it's located in the **hack/docs** folder of our GitHub repository.
+
+The **.md** file extension stands for **Markdown**. In GitHub's words:
+
+> Markdown is a lightweight and easy-to-use syntax for styling all forms of writing on the GitHub platform.
+
+If you're new to it, we recommend reading through this quick [Markdown guide](https://guides.github.com/features/mastering-markdown/) before moving on.
+
+Really, it'll take you 3 minutes, and will give you a much better understanding of the structure of the document we are about to edit.
+
+## Your first edit
+
+Suppose you've read the [Getting Started page](https://hack.aragon.org/docs/getting-started) and you have an idea for how to explain things more clearly.
+
+In particular, you want to add a paragraph to the _What is Aragon and what does it do_ section. Something along the lines of:
+
+> If you're new to this ecosystem, don't worry if some (or all) of that sounded a little abstract to you. You can think of Aragon as providing the lego pieces to allow people (like you) to build the next generation of human organizations. Organizations that can be spun up instantly, that can't be shut down by governments, that are resistant to internet censorship, and that allow small groups of people to collaborate effectively.
+
+The process couldn't be simpler. Just start writing directly in the document editor provided!
+
+
+
+When you're happy with the changes you've made, click on the **Preview changes** button at the top of the document editor.
+
+
+
+If you're happy with how your change looks, you're ready to officially propose the file change.
+
+Note that if you're unhappy with the result, you can click on the **Edit file** button to continue making changes.
+
+## Proposing the file change
+
+Scroll down to the bottom of the page You should see a box with the heading **Propose file change**.
+
+
+
+This is where the description of your proposed file change goes- known in Git as a **commit message**.
+
+ou can think of a commit message as a short email explaining your proposal: the first text box is the subject line, and the second is the text body.
+
+The [convention](https://github.blog/2011-09-06-shiny-new-commit-styles/) is to write your commit message in the present tense. For example, if you fixed a bug, you would write _Fix bug_ and not _Fixed bug_.
+
+In the first box we'll write:
+
+> Update getting-started.md
+
+And in the second we'll write a brief description:
+
+> Add paragraph to 'What is Aragon and what does it do' subsection.
+
+
+
+When you're ready, click on the green **Propose file change** button.
+
+## Comparing changes
+
+If you've followed the above steps correctly, you should be looking a page that looks like this.
+
+
+
+Under the header, you should see a line that says:
+
+> Choose two **branches** to see what's changed or to start a new **pull request**. If you need to, you can also compare across **forks**.
+
+Before we move on, it's time to explain what these terms mean.
+
+We've already explained the term [fork](https://help.github.com/en/articles/fork-a-repo) : remember it's just GitHub's term for a copy of a project.
+
+We mentioned that when you click on the pencil icon to edit the document, GitHub creates a complete copy (fork) of the project under your account (we need a copy because we don't have the permissions required to directly edit the original project).
+
+What we didn't cover is that clicking on this icon also creates what Git calls a new branch.
+
+The ability to create branches is one of the most powerful features of Git: Branches are essentially self-contained copies of the project code.
+
+A GitHub project always starts with one branch (the master branch). However, the usual Git workflow is to create a new branch every time you begin working on a new feature or bug fix.
+
+Why is it good practice to create a new branch for every new feature? Why not just make changes directly to the master branch?
+
+The problems with making changes directly to the master branch is that there may be others working on implementing new features at the same time as you.
+
+If you're implementing your feature at the same time as someone else is implementing theirs, you might overwrite each others changes by mistake. This can get messy. So we try to avoid this.
+
+The idea is that once we've implemented our changes in our branch, we can request to **merge** our branch into the original branch: which is basically a request to update the original branch with our changes. This is usually done using a **pull request**.
+
+## Your first pull request
+
+
+
+[Pull requests](https://help.github.com/en/articles/about-pull-requests) let you tell others about changes you've pushed to a branch in a repository. Once a pull request is created, you can discuss and review the potential changes with collaborators (in this case the Aragon One team) before your changes are merged into the original (base) branch.
+
+By now you should understand the gist of this page. So let's go ahead and click on **Create pull request**.
+
+
+
+You should see both a subject and a body field. In our case they have been automatically filled with our previous commit message.
+
+At this stage you should add any issues you think exist with the pull request to the body, as well as any questions you may have for the Aragon team.
+
+If you haven't already, this is a good time to familiarize yourself with Aragon's [contribution guidelines](https://github.com/aragon/hack/blob/master/CONTRIBUTING.md).
+
+Once you're confident you've satisfied the contribution guidelines, click on **Create pull request** again.
+
+
+
+Congratulations! 🎉 You've just opened your first pull request.
+
+Now you just need to wait for the pull request to be reviewed by a maintainer.
+
+Don't worry if it isn't perfect (no pull request is). Your reviewer will help you improve it and fix any problems!
+
+## Adjusting your pull request
+
+After making a pull request, you may want to make an adjustment or an addition.
+
+Making an adjustment is as simple as editing the relevant file(s) in your branch and committing the change.
+
+GitHub ensures your pull request automatically tracks the changes in your branch and updates accordingly.
+
+Let's go through an example.
+
+Under the _Update getting-started.md_ header you should see a line that reads:
+
+> _username_ wants to merge 1 commit into aragon:master from _username:branchname_
+
+Note that, in the text above, _username_ and _branchname_ are just placeholders for your user and branch names.
+
+In my case, my username is _sysl91_ and the name of the branch I'm working in is _patch-1_, so I would click on _sysl91:patch-1_.
+
+To access your branch, click on your _username:branchname_ (it should be highlighted in blue).
+
+
+
+This will open up the branch you've created in your fork of the **hack** project.
+
+
+
+Click on the **docs** folder (remember, the getting-started.md page is located in the docs folder).
+
+
+
+Now click on **getting-started.md**.
+
+You should find yourself back at the GitHub copy of the Getting Started page.
+
+
+
+
+
+From here on in the workflow is pretty much the same as before.
+
+Click on the pencil icon to start editing.
+
+
+
+Say we want to make a grammatical change to the paragraph we added. Specifically, we want to separate the two clauses below with a colon instead of a full stop.
+
+> You can think of Aragon as providing the lego pieces to allow people (like you) to build the next generation of human **organizations: Organizations** that can be spun up instantly, that can't be shut down by governments, that are resistant to internet censorship, and that allow small groups of people to collaborate effectively.
+
+As before, we can make this change directly in the editor.
+
+
+
+We can then preview it.
+
+
+
+And if we're happy with the result, commit it.
+
+
+
+And voila! That's all there is to it 😊. The changes you just committed will automatically be reflected in your pull request.
diff --git a/docs/assets/centralized-vs-decentralized-stack-2.png b/docs/assets/centralized-vs-decentralized-stack-2.png
new file mode 100644
index 00000000..81c290b7
Binary files /dev/null and b/docs/assets/centralized-vs-decentralized-stack-2.png differ
diff --git a/docs/assets/centralized-vs-decentralized-stack.png b/docs/assets/centralized-vs-decentralized-stack.png
new file mode 100644
index 00000000..e24608a7
Binary files /dev/null and b/docs/assets/centralized-vs-decentralized-stack.png differ
diff --git a/docs/assets/getting-started-dao-0.png b/docs/assets/getting-started-dao-0.png
new file mode 100644
index 00000000..44a3f88b
Binary files /dev/null and b/docs/assets/getting-started-dao-0.png differ
diff --git a/docs/assets/getting-started-dao-1.png b/docs/assets/getting-started-dao-1.png
new file mode 100644
index 00000000..e71bd19b
Binary files /dev/null and b/docs/assets/getting-started-dao-1.png differ
diff --git a/docs/assets/getting-started-dao-2.png b/docs/assets/getting-started-dao-2.png
new file mode 100644
index 00000000..a9b09c33
Binary files /dev/null and b/docs/assets/getting-started-dao-2.png differ
diff --git a/docs/assets/github-guide/gh-0.png b/docs/assets/github-guide/gh-0.png
new file mode 100644
index 00000000..d619b9e7
Binary files /dev/null and b/docs/assets/github-guide/gh-0.png differ
diff --git a/docs/assets/github-guide/gh-1.png b/docs/assets/github-guide/gh-1.png
new file mode 100644
index 00000000..732ba441
Binary files /dev/null and b/docs/assets/github-guide/gh-1.png differ
diff --git a/docs/assets/github-guide/gh-10.png b/docs/assets/github-guide/gh-10.png
new file mode 100644
index 00000000..a2e48651
Binary files /dev/null and b/docs/assets/github-guide/gh-10.png differ
diff --git a/docs/assets/github-guide/gh-11.png b/docs/assets/github-guide/gh-11.png
new file mode 100644
index 00000000..d268ede4
Binary files /dev/null and b/docs/assets/github-guide/gh-11.png differ
diff --git a/docs/assets/github-guide/gh-12.png b/docs/assets/github-guide/gh-12.png
new file mode 100644
index 00000000..cf61e3ff
Binary files /dev/null and b/docs/assets/github-guide/gh-12.png differ
diff --git a/docs/assets/github-guide/gh-13.png b/docs/assets/github-guide/gh-13.png
new file mode 100644
index 00000000..ef038ee2
Binary files /dev/null and b/docs/assets/github-guide/gh-13.png differ
diff --git a/docs/assets/github-guide/gh-14.png b/docs/assets/github-guide/gh-14.png
new file mode 100644
index 00000000..91f65114
Binary files /dev/null and b/docs/assets/github-guide/gh-14.png differ
diff --git a/docs/assets/github-guide/gh-15.png b/docs/assets/github-guide/gh-15.png
new file mode 100644
index 00000000..51a2d4e7
Binary files /dev/null and b/docs/assets/github-guide/gh-15.png differ
diff --git a/docs/assets/github-guide/gh-16.png b/docs/assets/github-guide/gh-16.png
new file mode 100644
index 00000000..43110482
Binary files /dev/null and b/docs/assets/github-guide/gh-16.png differ
diff --git a/docs/assets/github-guide/gh-17.png b/docs/assets/github-guide/gh-17.png
new file mode 100644
index 00000000..ef801afd
Binary files /dev/null and b/docs/assets/github-guide/gh-17.png differ
diff --git a/docs/assets/github-guide/gh-18.png b/docs/assets/github-guide/gh-18.png
new file mode 100644
index 00000000..6df135a6
Binary files /dev/null and b/docs/assets/github-guide/gh-18.png differ
diff --git a/docs/assets/github-guide/gh-19.png b/docs/assets/github-guide/gh-19.png
new file mode 100644
index 00000000..58ac881d
Binary files /dev/null and b/docs/assets/github-guide/gh-19.png differ
diff --git a/docs/assets/github-guide/gh-2.png b/docs/assets/github-guide/gh-2.png
new file mode 100644
index 00000000..d54fe8b8
Binary files /dev/null and b/docs/assets/github-guide/gh-2.png differ
diff --git a/docs/assets/github-guide/gh-20.png b/docs/assets/github-guide/gh-20.png
new file mode 100644
index 00000000..fa49523b
Binary files /dev/null and b/docs/assets/github-guide/gh-20.png differ
diff --git a/docs/assets/github-guide/gh-3.png b/docs/assets/github-guide/gh-3.png
new file mode 100644
index 00000000..72c9d9f7
Binary files /dev/null and b/docs/assets/github-guide/gh-3.png differ
diff --git a/docs/assets/github-guide/gh-4.png b/docs/assets/github-guide/gh-4.png
new file mode 100644
index 00000000..1c2eb426
Binary files /dev/null and b/docs/assets/github-guide/gh-4.png differ
diff --git a/docs/assets/github-guide/gh-5.png b/docs/assets/github-guide/gh-5.png
new file mode 100644
index 00000000..17689ec9
Binary files /dev/null and b/docs/assets/github-guide/gh-5.png differ
diff --git a/docs/assets/github-guide/gh-6.png b/docs/assets/github-guide/gh-6.png
new file mode 100644
index 00000000..6e84d46c
Binary files /dev/null and b/docs/assets/github-guide/gh-6.png differ
diff --git a/docs/assets/github-guide/gh-7.png b/docs/assets/github-guide/gh-7.png
new file mode 100644
index 00000000..9013a954
Binary files /dev/null and b/docs/assets/github-guide/gh-7.png differ
diff --git a/docs/assets/github-guide/gh-8.png b/docs/assets/github-guide/gh-8.png
new file mode 100644
index 00000000..a2d12509
Binary files /dev/null and b/docs/assets/github-guide/gh-8.png differ
diff --git a/docs/assets/github-guide/gh-9.png b/docs/assets/github-guide/gh-9.png
new file mode 100644
index 00000000..ea0a8f1b
Binary files /dev/null and b/docs/assets/github-guide/gh-9.png differ
diff --git a/docs/assets/metamask-1.png b/docs/assets/metamask-1.png
new file mode 100644
index 00000000..c343dd8e
Binary files /dev/null and b/docs/assets/metamask-1.png differ
diff --git a/docs/assets/metamask-4.png b/docs/assets/metamask-4.png
new file mode 100644
index 00000000..85744153
Binary files /dev/null and b/docs/assets/metamask-4.png differ
diff --git a/docs/assets/metamask-5.png b/docs/assets/metamask-5.png
new file mode 100644
index 00000000..73a2f25e
Binary files /dev/null and b/docs/assets/metamask-5.png differ
diff --git a/docs/assets/metamask-6.png b/docs/assets/metamask-6.png
new file mode 100644
index 00000000..51c66fbd
Binary files /dev/null and b/docs/assets/metamask-6.png differ
diff --git a/docs/assets/metamask-7.png b/docs/assets/metamask-7.png
new file mode 100644
index 00000000..4d883033
Binary files /dev/null and b/docs/assets/metamask-7.png differ
diff --git a/docs/assets/metamask-guide/m-0.png b/docs/assets/metamask-guide/m-0.png
new file mode 100644
index 00000000..4299b30e
Binary files /dev/null and b/docs/assets/metamask-guide/m-0.png differ
diff --git a/docs/assets/metamask-guide/m-1.png b/docs/assets/metamask-guide/m-1.png
new file mode 100644
index 00000000..818eda9a
Binary files /dev/null and b/docs/assets/metamask-guide/m-1.png differ
diff --git a/docs/assets/metamask-guide/m-10.png b/docs/assets/metamask-guide/m-10.png
new file mode 100644
index 00000000..185d54af
Binary files /dev/null and b/docs/assets/metamask-guide/m-10.png differ
diff --git a/docs/assets/metamask-guide/m-11.png b/docs/assets/metamask-guide/m-11.png
new file mode 100644
index 00000000..3be77d03
Binary files /dev/null and b/docs/assets/metamask-guide/m-11.png differ
diff --git a/docs/assets/metamask-guide/m-12.png b/docs/assets/metamask-guide/m-12.png
new file mode 100644
index 00000000..1e475c04
Binary files /dev/null and b/docs/assets/metamask-guide/m-12.png differ
diff --git a/docs/assets/metamask-guide/m-13.png b/docs/assets/metamask-guide/m-13.png
new file mode 100644
index 00000000..48468051
Binary files /dev/null and b/docs/assets/metamask-guide/m-13.png differ
diff --git a/docs/assets/metamask-guide/m-14.png b/docs/assets/metamask-guide/m-14.png
new file mode 100644
index 00000000..4b01d49f
Binary files /dev/null and b/docs/assets/metamask-guide/m-14.png differ
diff --git a/docs/assets/metamask-guide/m-15.png b/docs/assets/metamask-guide/m-15.png
new file mode 100644
index 00000000..1ce99922
Binary files /dev/null and b/docs/assets/metamask-guide/m-15.png differ
diff --git a/docs/assets/metamask-guide/m-2.png b/docs/assets/metamask-guide/m-2.png
new file mode 100644
index 00000000..06adab87
Binary files /dev/null and b/docs/assets/metamask-guide/m-2.png differ
diff --git a/docs/assets/metamask-guide/m-3.png b/docs/assets/metamask-guide/m-3.png
new file mode 100644
index 00000000..94e46130
Binary files /dev/null and b/docs/assets/metamask-guide/m-3.png differ
diff --git a/docs/assets/metamask-guide/m-4.png b/docs/assets/metamask-guide/m-4.png
new file mode 100644
index 00000000..b303c843
Binary files /dev/null and b/docs/assets/metamask-guide/m-4.png differ
diff --git a/docs/assets/metamask-guide/m-5.png b/docs/assets/metamask-guide/m-5.png
new file mode 100644
index 00000000..bc59ae21
Binary files /dev/null and b/docs/assets/metamask-guide/m-5.png differ
diff --git a/docs/assets/metamask-guide/m-6.png b/docs/assets/metamask-guide/m-6.png
new file mode 100644
index 00000000..174727bd
Binary files /dev/null and b/docs/assets/metamask-guide/m-6.png differ
diff --git a/docs/assets/metamask-guide/m-7.png b/docs/assets/metamask-guide/m-7.png
new file mode 100644
index 00000000..45de06d7
Binary files /dev/null and b/docs/assets/metamask-guide/m-7.png differ
diff --git a/docs/assets/metamask-guide/m-8.png b/docs/assets/metamask-guide/m-8.png
new file mode 100644
index 00000000..49e184cb
Binary files /dev/null and b/docs/assets/metamask-guide/m-8.png differ
diff --git a/docs/assets/metamask-guide/m-9.png b/docs/assets/metamask-guide/m-9.png
new file mode 100644
index 00000000..2f3da585
Binary files /dev/null and b/docs/assets/metamask-guide/m-9.png differ
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 9d03a0c9..84ff03f0 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -6,68 +6,236 @@ sidebar_label: Getting started
##### What is Aragon and what does it do
-
Aragon is a project to **empower freedom** by creating tools for **decentralized governance**.
-These tools help people freely organize **without borders or intermediaries**. Instead of bureaucracy, subjectivity, and trust, smart contracts have opened the door to **experiment with governance at the speed of software**.
+These tools help people freely organize **across borders** and **without intermediaries**. Instead of bureaucracy, subjectivity, and trust, smart contracts have opened the door to **experiment with governance at the speed of software**.
The Aragon stack helps you develop software for **human organization**. From the smart contracts to the user interface, Aragon takes care of the most important pieces of infrastructure to deliver censorship-resistant, decentralized and upgradeable apps.
+If you're new to this ecosystem, don't worry if some (or all) of that sounded a little abstract. You can think of Aragon as providing the lego pieces to allow people (like you) to build the next generation of human organizations.
+
+Organizations that can be spun up instantly, that can't be shut down by governments, that are resistant to internet censorship, and that allow small groups of people to collaborate effectively.
+
> Example of a decentralized, censorship-resistant, good-looking voting app on Aragon
+# Introduction
+
+Many of us have gone through the pain of setting up a corporate entity. Or felt like we've lacked the tools to collaborate with people all around the globe when we're building stuff we want to see in the world.
+
+Right now, the current system simply doesn't work. If you want to set up an organisation you have to go to lawyers, pay thousands of dollars, and all you get in return is a set of unintelligible pieces of paper that cost you more than months of development.
+
+On top of this, these pieces of paper don't enforce anything by themselves: they're more like an idea, or a concept.
+
+If you try to explain this to a kid, you quickly realise how mad the current system seems to them. When you think about it, it's really impressive that the world functions the way it does with this sort of legacy framework and operating system underneath.
+
+At Aragon, we believe that decentralized autonomous organizations (DAOs) are the solution to this problem.
+
+What exactly is a DAO? There are many ways to describe a DAO, and knowledgable people may disagree on the precise definition. For our purposes, you can think of DAOs as flexible, global, and uncensorable online organizations.
+
+How does Aragon fit in? Aragon provides you with tools (apps) that make it easy for you to create DAOs -- you can think of Aragon apps as lego bricks that can be flexibly combined to make DAOs (the final lego structures).
+
+Another way to think of Aragon is as a new operating system (OS) for setting up organizations. One that is far more efficient than the existing OS (lawyers, administrative headaches, etc) we are used to dealing with.
+
+### More on DAOs
+
+For those of you who are new to DAOs, in this section we'll briefly cover the sorts of things DAOs can enable, when you might want to use a DAO, as well as the trends around the world accelerating their adoption.
+
+#### DAOs can enable:
+
+- Shared bank accounts with custom rules and permissions
+- Payroll that automatically runs by itself
+- Built-in voting on important topics
+
+#### DAO use cases:
+
+- Part-time projects with friends or strangers
+- Future of work: people working part time on multiple things for short periods of time
+- Temporary pop-up companies
+- Companies in authoritarian jurisdictions
+- Global, distributed teams
+
+#### Trends around the world accelerating DAO adoption:
+
+- The rise of populist authoritarians
+- The future of work (remote and distributed)
+- The growing de-platforming problem
+- The rise of decentralized finance
+- The [increasing](https://medium.com/complex-systems-channel/teams-a-manifesto-7490eab144fa) [complexity](https://necsi.edu/complexity-rising-from-human-beings-to-human-civilization-a-complexity-profile) of human civilization
+
+### Web3
-What you need to get started building with Aragon:
+Unless you've been living under a rock for the last few years, you've probably come across the term web3 😋. But what does it mean exactly? And why do we care about it in the context of Aragon?
-- [Environment setup](#environment-setup)
-- [Quick start](#quick-start)
-- [Next steps](#next-steps)
+Web3 is the vision of a fully decentralized web. One of the craziest things to wrap your head around is that in web3, apps don't need a central server to fetch data from!
+How is this possible? In a nutshell, thanks to something called peer-to-peer data architectures. The key point is that in a P2P architecture, instead of requesting data from a central server, you request it from multiple computers (peers) around you.
+
+While this is nothing new in itself -- P2P architectures have existed since the 1990’s (where they rose to fame with file sharing programs like BitTorrent and Napster) -- what's new is the addition of cryptography and economic incentives to these architectures.
+
+The fusion of these seemingly disparate disciplines was the big innovation behind Bitcoin, and has since led to the emergence of a new field of research devoted to their intersection (what we now call cryptoeconomics).
+
+While we won't get into the details here,the key takeaway is that cryptoeconomics is the big unlock that has allowed us to start moving from centralized data structures (web2) to more decentralized or fully distributed data architectures (web3).
+
+
+
+> Note that there’s a spectrum from fully centralized (left) to fully decentralized (right).
+
+And while blockchains -- like Bitcoin and Ethereum -- are key to this web3 vision, it's important to note that there are other essential parts of the web3 stack that are not covered by them.
+
+For example, since blockchains are relatively expensive to store data on, it turns out that they don't make great file systems. That's why there's also a need for decentralized file systems like the [InterPlanetary File System](https://ipfs.io/) (which Aragon also makes use of).
+
+### Further resources
+
+- [DAOs and the Web3 vision](https://www.youtube.com/watch?v=YG3a5ihbkAQ)
+- [The Aragon Manifesto](https://blog.aragon.org/the-aragon-manifesto-4a21212eac03/)
+- [The Aragon Whitepaper](https://github.com/aragon/whitepaper)
+- [Aragon Black: #1 White paper & Manifesto](https://blog.aragon.black/white-paper-manifesto/)
+- [Can Aragon make decentralized autonomous governance work](https://breakermag.com/can-aragon-make-decentralized-autonomous-governance-work/)
+- [Why The Internet Needs IPFS Before It’s Too Late](https://techcrunch.com/2015/10/04/why-the-internet-needs-ipfs-before-its-too-late/)
+- [A hands-on introduction to IPFS](https://medium.com/coinmonks/a-hands-on-introduction-to-ipfs-ee65b594937)
+- [Blockchain infrastructure landscape: a first principles framing](https://medium.com/@trentmc0/blockchain-infrastructure-landscape-a-first-principles-framing-92cc5549bafe)
+- [The case for decentralization](https://a16zcrypto.com/2019/04/why-work-in-crypto-startup-grind-2019/)
+- [What comes after open source?](https://a16zcrypto.com/2019/01/what-comes-after-open-source/)
+- [Fat protocols](http://www.usv.com/blog/fat-protocols)
+
+# Up and running
+
+Now that we've got you all excited, let's go through what you need to get started building with Aragon 😊
## Environment setup
-### Node version
+### Node.js
+
+First off, we need to be sure we have a recent version of Node.js installed, for compatibility across OS we recommend LTS (`v10.5.3`) version.
+
+To see which version of Node you have installed, from the command line run:
+
+```sh
+node -v
+```
+
+To download node, [follow this link](https://nodejs.org/en/download/).
+
+### Web3 provider
+
+Next, we'll need what we call a web3 provider to actually sign and send transactions to the Ethereum blockchain.
-Make sure you have at least Node.js `v8.0.0`.
+If you're new to the decentralized web you might be wondering why we have to use a separate provider to interact with the blockchain. Why don't decentralized apps (like Aragon's) just do it themselves?
-### Signing and web3 provider
+In short, while it's possible for dapps to interact directly with the blockchain, using a web3 provider allows users to interact with dapps without trusting every one of them with their private keys (the keys to theirs funds).
-We recommend using [Frame](https://frame.sh) to send transactions to the blockchain. Otherwise you can use [Metamask browser extension](https://metamask.io/).
+Without a web3 provider, users have to have total trust in every dapp they use. With a web3 provider, they just need to trust that provider.
-### Install the aragonCLI
+> In general, if you have a hardware wallet, we recommend you use [Frame](https://frame.sh) as your web3 provider -- we'll go over how to do this in the [tutorial](/docs/tutorial.html) that follows. To interact with the app in this section however, we'll be using [Metamask](https://metamask.io/).
-From the command line run:
+#### Metamask
+
+MetaMask is a browser plugin that allows users to make Ethereum transactions through regular websites. It does this by injecting a javascript library called web3.js into the namespace of each page your browser loads.
+
+web3.js is written by the Ethereum core team, and has functions that regular webpages can use to make read and write requests to the blockchain. Eventually we'll have browsers with this sort of functionality built-in. But for now we need plugins like Metamask to help us bridge the gap between web2 and web3.
+
+For instructions on how to use Metamask as your web3 provider, please follow our [Metamask guide](/docs/guides-use-metamask.html).
+
+### The aragonCLI
+
+The final missing piece is what's known as the aragonCLI (or Aragon Command Line Interface). This is what we'll use to create, interact with, and develop Aragon apps and DAOs -- remember an Aragon DAO is just a combination of Aragon Apps.
+
+To install aragonCLI from the command line run:
```sh
npm i -g @aragon/cli
```
-Once we have this package installed we can start building DAOs.
+Hopefully, it downloaded successfully. If that's the case, congrats! You're now officially ready to start building your first Aragon DAO!
-### Note on Git
+If you're having trouble with this step, you should take a look at the installing aragonCLI section of the [troubleshooting guide.](/docs/guides-faq#installing-aragonCLI) If that doesn't fix things, please don't hesitate to reach out to us at the [#dev-help channel on the Aragon Chat](https://aragon.chat/channel/dev-help).
-You might need to have [Git](https://git-scm.com) installed.
+## Quick start
-### Windows considerations
+In order to get up and running quickly, we’ll build our first DAO using some basic scaffolding. Just like real scaffolding in a construction site, when we talk about scaffolding in this context, we mean a simple prebuilt structure for your project, on top of which you can build the real one.
-You might need to run the shell with administrator rights when installing the aragonCLI, because our `go-ipfs` dependency will need to create a symlink to work correctly.
+To create your first (scaffolded) DAO, from the command line run:
-If you have problems during the instalation of aragonCLI or any other dependencies. You probably need to install [windows-build-tools](https://www.npmjs.com/package/windows-build-tools) or similar package.
+```sh
+npx create-aragon-app first-dao.aragonpm.eth
+```
+Don't worry about fully understanding this line right now. Really. We'll cover that in the [tutorial](/docs/tutorial.html) coming up. Right now, you just need to know that the scaffolding relies on some generated code, magically created by the `create-aragon-app` command.
-## Quick start
+If you look at your terminal, you should see a five step process:
-To create your first DAO run:
+
+ `Preparing initialization`
+
+ `Cloning app template`
+
+ `Preparing template`
+
+ `Installing package dependencies`
+
+ `Created new application first_dao.aragonpm.eth in first_dao.`
+
+
+
+Once all 5 have ticks next to them, you should run the following:
```sh
-npx create-aragon-app foo.aragonpm.eth
-cd foo
+cd first-dao
npx aragon run
```
-Congrats you have just created a DAO! It’s running on your local network and as soon as it's ready it will open in your browser at [localhost:3000](http://localhost:3000)!
+The first line, `cd first-dao`, just moves us into the directory where the scaffolded app was created.
+
+And the second, `npx aragon run`, sets up everything for us in the background so we can quickly live test our DAO.
+
+If you're unsure what the difference is between `npx` and `npm`, we recommend you read through this [medium post](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) and this [stackoverflow post.](https://stackoverflow.com/questions/50605219/difference-between-npx-and-npm)
+
+If you've made it this far congrats 🤗. You've just created your first DAO! It’s running on your local network and as soon as it's ready it will open in your browser at [localhost:3000](http://localhost:3000)!
+
+### Interacting with your first DAO
+
+If it's not already open, open your browser at the localhost address shown in your terminal. It should look something like this:
+
+```sh
+This is the configuration for your development deployment:
+ Ethereum Node: ws://localhost:8545
+ ENS registry: 0x5f6f7e8cc7346a11ca2def8f827b7a0b612c56a1
+ APM registry: aragonpm.eth
+ DAO address: 0xE56671CA800F4516B5B705c729BD3c6Aee4DDbEC
+
+Opening http://localhost:3000/#/0xE56671CA800F4516B5B705c729BD3c6Aee4DDbEC to view your DAO
+```
+
+Once your browser is open at the right address, you should see a screen that looks like the one below.
+
+
+
+As you can see on the left, this DAO is made up of two Aragon apps -- Home and Counter. Right now, we're in the Home app. This app just displays a welcome message with no possible user interactions.
+
+Click on Counter to open up the (slightly) more interesting Counter app.
+
+
+
+Right now the count is at 0. Let's increment it.
+
+Note that incrementing the counter triggers a blockchain transaction that saves the new value to the chain. But before the transaction can be sent, we need to sign it (to prove it was us that really sent it).
+
+#### Signing your first transaction with Metamask
+
+To sign your first transaction with Metamask, head to the **Signing your first transaction with Metamask** section of our [Metamask guide](/docszf/guides-use-metamask.html).
## Next steps
-Now that you’ve built a DAO let's take a look at the docs or you can jump into the [tutorial](/docs/tutorial.html).
+We hope you enjoyed that 😊! Please don't hesitate to leave us any [feedback](https://aragon.chat/channel/feedback).
+
+Now that you’ve built your first DAO, feel free to take a look at the docs. If you're interested in understanding things at a deeper level, we recommend you jump straight into our [awesome tutorial](/docs/tutorial.html).
+
+## Contributing
+
+You should find that there is a light blue EDIT button in the top-right corner the page. This button is available on every page of the Aragon docs. If you feel like you can improve our documentation in any way, please don't hesitate to click on it!
+
+If you don't have any programming experience or if this is your first time contributing to an open-source project, don't worry. We've created a [GitHub guide](https://github.com/aragon/hack/tree/master/docs-internal/github-guide.md) just for you 😊.
+
+P.S. Before you submit any changes, make sure to read our [contribution guidelines.](https://github.com/aragon/hack/blob/master/CONTRIBUTING.md)
diff --git a/docs/guides-faq.md b/docs/guides-faq.md
index a018c91f..4754d208 100644
--- a/docs/guides-faq.md
+++ b/docs/guides-faq.md
@@ -6,6 +6,45 @@ sidebar_label: Troubleshooting
#####
+## Installing aragonCLI
+
+### Linux considerations
+
+If you're seeing several errors (e.g. `node-gyp rebuild`) it's probably cause you need to run node long term support (LTS) version, currently `10.15.3`.
+
+### Mac considerations
+
+If you're seeing one or more errors that look like:
+
+```sh
+EACCES: permission denied
+```
+
+It's probably because you originally installed Node with root permissions [explain what this means] . Because of this, writing to your npm directory (```npm -i -g```) requires root permissions too.
+
+While it's not a good idea to have Node installed this way, one way to quickly give yourself root permissions is to run the slightly modified command: [maybe not a good idea to show this option]
+
+```sh
+sudo npm i -g --unsafe-perm @aragon/cli
+```
+
+An arguably better way to fix the problem is to follow the steps outlined in this [stackoverflow answer.](https://stackoverflow.com/a/24404451) [should make this more intuitive...]
+
+[i think this whole section needs to be exlained more simply...]
+
+### Windows considerations
+
+You might need to run the shell with administrator rights when installing the aragonCLI, because our `go-ipfs` dependency will need to create a symlink to work correctly. [this needs to be explained better]
+
+If you have problems during the instalation of aragonCLI or any other dependencies. You probably need to install [windows-build-tools](https://www.npmjs.com/package/windows-build-tools) or similar package.
+
+Again, if you're having trouble fixing things, please reach out to us at the [#dev-help channel on the Aragon Chat](https://aragon.chat/channel/dev-help)
+
+### Note on Git
+
+You might need to have [Git](https://git-scm.com) installed. If you're unsure what Git is, or whether you have it installed, we recommend you follow [this tutorial.](https://www.learnenough.com/git-tutorial/getting_started)
+*[a little startling for the reader... why might? i think we need to elaborate here...]*
+
## Resetting the devchain
After upgrading aragonCLI, or if unexpected errors are being experienced, [resetting the devchain](/docs/cli-main-commands.html#aragon-devchain) (by doing `aragon devchain --reset` or `aragon run --reset`) is sometimes useful as it will restart the chain from the snapshot.
diff --git a/docs/guides-use-metamask.md b/docs/guides-use-metamask.md
new file mode 100644
index 00000000..6cad3acb
--- /dev/null
+++ b/docs/guides-use-metamask.md
@@ -0,0 +1,204 @@
+---
+id: guides-use-metamask
+title: How to use Metamask
+sidebar_label: Metamask
+---
+
+# What is MetaMask?
+
+Metamask is a browser plugin that lets you make Ethereum transactions through regular websites.
+
+It does this by injecting a Javascript library called web3.js into the namespace of each page your browser loads.
+
+web3.js is written by the Ethereum core team, and has functions that regular webpages can use to make read and write requests to the blockchain.
+
+Eventually we'll have browsers with this sort of functionality built-in. But for now we need plugins like Metamask to help us bridge the gap between web2 and web3. We call these portals between web2 and web3, web3 providers.
+
+For more on why we need web3 providers like Metamask to interact with the blockchain see the **web3 provider** section of our [getting started page](/docs/getting-started.html#web3-provider).
+
+Finally, if you're new to web3 we recommend you read through the **web3** section of our [getting started page](/docs/getting-started.html#web3).
+
+# Getting started
+
+If this is your first time using Metamask, here's how to get started:
+
+Visit the [Metamask homepage](https://metamask.io/) and download the relevant browser extension (this guide will be based around the Chrome extension, but the process is similar for all browsers).
+
+Once it's downloaded, you should be automatically directed to a welcome page.
+
+
+ 
+
+
+Follow the instructions carefully. They should be pretty self-explanatory.
+
+Once your MetaMask setup is complete, you should be redirected to your newly created Ethereum wallet.
+
+
+ 
+
+
+If you've made it this far, congratulations 🎉.
+
+You now have all you need to sign transactions and interact directly with the Ethereum blockchain.
+
+# A couple of useful points
+
+While at this stage there's no need for you to understand everything about Metamask, here are a couple of useful points.
+
+### Selected networks
+
+In the top right you should see a dropdown menu with **Main Ethereum Network** selected.
+
+With this option selected, you're able to interact directly with the main Ethereum blockchain. If you click on it however, you should see that you have the ability to select other networks.
+
+
+ 
+
+
+Why would we need to select other networks? Simply put, before launching a project (or dapp) on the main Ethereum network, it's good practice to deploy a version to an Ethereum test network.
+
+The main reason is that Testnet ETH can be obtained without having to pay real money. This gives developers and the community a chance to iron out any problems before real money is involved.
+
+There are three testnets: **Ropsten**, **Kovan**, and **Rinkleby**.
+
+Don't worry about the precise differences between them at this stage. All you need to know is that they simulate Ethereum and can be used without having to pay real money.
+
+Finally, you can also interact with private Ethereum networks by selecting **Localhost 8545**. Private in this case doesn't mean more secure. It just means that the nodes are not connected to the main or test network nodes.
+
+Why would we want to use a private network? In short, using the mainnet or testnets requires you to download the past transaction history of the blockchain. This takes a considerable amount of time, and requires a lot of local disk space.
+
+A private network requires negligible local disk storage and can be operated without having to purchase ETH with real money. Perfect for rapid experimentation and testing.
+
+### Account address
+
+If you click on the **Details** button below your account name - in my case Account 1 - a popup will appear with your account address. It should look something like:
+
+ **0x931D387731bBbC988B312206c74F77D004D6B84b**
+
+This is your public address (or public key). You can share this with other people to receive ETH.
+
+# Signing your first transaction with MetaMask
+
+In this section we'll go through how to sign your first transaction using Metamask.
+
+From now on, I'll assume you've reached the **Interacting with your first DAO** section of our [getting started](https://hack.aragon.org/docs/getting-started.html) page. If you haven't, and you want to follow along, you should do this first.
+
+The first step is to open up the Metamask browser extension. If you're using Chrome you should be able to do this by clicking on the fox icon located to the right of your address bar. If you can't see it, [click here](https://chrome.google.com/webstore/search/metamask).
+
+This will open up an interface to your Ethereum wallet.
+
+
+ 
+
+
+Click on the circle in the top right. You should see a black drop down menu appear.
+
+
+ 
+
+
+Click on the **Log out** button in the top right of this menu. You'll be taken to a Welcome Back page.
+
+
+ 
+
+
+Now click on **Import using account seed phrase**. Metamask should now open up in a new tab, with the heading: **Restore your account with Seed Phrase**.
+
+Now, what you need to do is to look at the output of your terminal after you ran `npx aragon run`. You should see the following at the end:
+
+```
+ℹ The accounts were generated from the following mnemonic phrase:
+explain tackle mirror kit van hammer degree position ginger unfair soup bogus
+```
+
+These 12 words phrase will allow us to use MetaMask to access an account that has permission to update the Counter in our Counter app.
+
+> Note that your mnemonic phrase won't be the same as mine. So make sure you copy yours from your terminal, and not from this blog.
+
+Once you've copied it, paste it into the wallet seed text box, and create a new password.
+
+
+ 
+
+
+When you're done, click on the **Restore** button at the bottom of the page. Congratulations 🎉. You've now connected MetaMask to an Ethereum account that has permission to increment and decrement the Counter app in your first DAO.
+
+We're now finally ready to play with the Counter app 😊.
+
+Navigate back to your DAO and click on the **Increment** button in the Counter app.
+
+
+ 
+
+
+You should see a panel slide in from the right with an error message. The message (in a blue box) basically says you can't perform any actions unless you enable MetaMask.
+
+
+ 
+
+
+You should see that the final line inside the blue box reads: **Please unlock and enable Metamask**. Click on **enable** and open up MetaMask again.
+
+You should see a connection request from Aragon. Click on the **Connect** button to accept it.
+
+
+ 
+
+
+Now go back to the Counter app. Oh dear… we have another error message 😔. This time, the message says we need to connect MetaMask to the private network.
+
+
+ 
+
+
+Why are we getting this error?
+
+Remember, Metamask defaults to selecting the main Ethereum network when you make a transaction. But our DAO is actually running on a private local network, not the mainnet.
+
+Why are we using a private network?
+
+Remember that using the mainnet requires purchasing ETH with real money. And that using the mainnet or testnets requires us to download the entire past transaction history of the blockchain: this takes a considerable amount of time, and requires a lot of local disk space. In contrast, a private network requires almost no local disk space and can be operated without having to purchase ETH with real money. So it's perfect for rapid experimentation and testing.
+
+Remember, we can connect to a local (private) network by opening up Metamask and selecting **Localhost 8545**. So let's go ahead and do that.
+
+Close the panel and open MetaMask again. Now, click on the selected network - **Main Ethereum Network** - and select **Localhost 8545** from the dropdown menu that appears.
+
+
+ 
+
+
+You should now see that your account has some ETH. Quite a lot in fact. Unfortunately this is not real ETH, but it will allow you to perform transactions within your local private network (in other words, increment and decrement the counter).
+
+Now, go back to the **Counter app**, and click on the **Increment** button again.
+
+This time, instead of an error message, you should see an explanation of the action you are about to perform.
+
+
+ 
+
+
+Double check that the action that's about to be triggered is the one you wish to perform. Then click on **Create transaction**.
+
+The app will now signal to you that it's waiting for your signature.
+
+
+ 
+
+
+Open MetaMask again to sign your transaction. You'll be asked to confirm a transaction from Account 1 (your account) to the address of your newly created DAO. The total amount you're sending is about 0.001 ETH: basically just the **Gas fee**.
+
+
+ 
+
+
+In case you're unfamiliar with the concept of **Gas**, the **Gas fee** is what's used to incentivize miners to add your transaction to the blockchain. You can think of it as a small tip. Remember that this transaction is taking place on a local (private) network, so this isn't real money. If you're happy with the details of the transaction, click on **Confirm**.
+
+Now, if you go back to you're first DAO you should see that the counter has finally been incremented!
+
+
+ 
+
+
+If you've made it all the way here, well done! You've just signed your first blockchain transaction with Metamask. 🎉🎉😊
diff --git a/website/sidebars.json b/website/sidebars.json
index 654a7956..ee07780b 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -16,6 +16,11 @@
"tutorial",
"guides-publish",
"guides-custom-deploy",
+ {
+ "type": "subcategory",
+ "label": "Signers",
+ "ids": ["guides-use-frame", "guides-use-metamask"]
+ },
"guides-faq"
],
"aragonCLI": [