incorporate docs feedback

docs/docs/about_aztec/overview.mdx

@@ -52,7 +52,7 @@ Contributors to Aztec uphold many of the values of the Ethereum community -- bui
 
 Noir is a domain specific programming language for writing zero knowledge circuits. On Aztec a smart contract is a collection of circuits that developers write using Noir.
 
-You can find more information and resources for learning about Noir smart contracts on [this page](../dev_docs/getting_started/noir_contracts.md).
+You can find more information and resources for learning about Noir smart contracts on [this page](../dev_docs/contracts/main.md).
 
 ## Cryptography
 

docs/docs/concepts/advanced/contract_creation.md

@@ -327,4 +327,4 @@ Adds initial public state variables to the public data tree.
 
 ## Further reading
 
-To see how to deploy a contract in practice, check out the [dapp development tutorial](../../dev_docs/dapps/tutorials/main.md).
+To see how to deploy a contract in practice, check out the [dapp development tutorial](../../dev_docs/tutorials/writing_dapp/main.md).

docs/docs/dev_docs/cli/main.md

@@ -2,22 +2,147 @@
 title: Aztec CLI
 ---
 
-## What is the Aztec CLI?
+## Introduction
 
 The Aztec CLI is a command-line tool allowing the user to interact directly with the Aztec Network.
 
 It aims to provide all of the functionality required to deploy and invoke contracts and query system state such as contract data, transactions and emitted logs.
 
 ## Requirements
 
-The Aztec CLI is provided as an npm package containing an installed binary. It can be installed by using:
+You should have [node.js](https://nodejs.org/en/download) installed with version >= 18.
 
-`yarn global add @aztec/cli`
+To install the Aztec CLI run:
+
+```bash
+npm install -g @aztec/cli
+```
+
+Or if you use yarn:
+
+```bash
+yarn global add @aztec/cli
+```
+
+Then verify that it is installed with:
+
+```bash
+aztec-cli -h
+```
 
 Once installed it is invoked via:
 
 `aztec-cli [options] [command]`
 
-## Getting Started
+## I have the Sandbox running, now what?
+
+Lets first establish that we are able to communicate with the Sandbox. Most commands will require the url to the Sandbox, which defaults in the CLI to `http://localhost:8080`. You can override this as an option with each command or by setting `AZTEC_RPC_HOST` environment variable.
+
+To test communication with the Sandbox, let's run the command:
+
+#include_code block-number yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+You should see the current block number (1) printed to the screen!
+
+## Contracts
+
+We have shipped a number of example contracts in the `@aztec/noir-contracts` npm package. This is included with the cli by default so you are able to use these contracts to test with. To get a list of the names of the contracts run:
+
+#include_code example-contracts yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+You can see all of our example contracts in the monorepo [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/src/contracts).
+
+In the following sections there will be commands that require contracts as options. You can either specify the full directory path to the contract abi, or you can use the name of one of these examples as the option value. This will become clearer later on.
+
+## Creating Accounts
+
+The first thing we want to do is create a couple of accounts. We will use the `create-account` command which will generate a new private key for us, register the account on the sandbox, and deploy a simple account contract which [uses a single key for privacy and authentication](../../concepts/foundation/accounts/keys.md):
+
+#include_code create-account yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+Once the account is set up, the CLI returns the resulting address, its privacy key, and partial address. You can read more about these [here](../../concepts/foundation/accounts/keys.md#addresses-partial-addresses-and-public-keys).
+
+Save the Address and Private key as environment variables. We will be using them later.
+
+```bash
+export ADDRESS=<Address printed when you run the command>
+export PRIVATE_KEY=<Private key printed when you run the command>
+```
+
+Alternatively, we can also manually generate a private key and use it for creating the account, either via a `-k` option or by setting the `PRIVATE_KEY` environment variable.
+
+#include_code create-account-from-private-key yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+For all commands that require a user's private key, the CLI will look for the `PRIVATE_KEY` environment variable in absence of an optional argument.
+
+Let's double check that the accounts have been registered with the sandbox using the `get-accounts` command:
+
+#include_code get-accounts yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+You will see a that a number of accounts exist that we did not create. The Sandbox initialises itself with 3 default accounts. Save one of the printed accounts (not the one that you generated above) in an environment variable. We will use it later.
+
+```bash
+export ADDRESS2=<Account address printed by the above command>
+```
+
+## Deploying a Token Contract
+
+We will now deploy the private token contract using the `deploy` command, minting 1000000 initial tokens to address `0x175310d40cd3412477db1c2a2188efd586b63d6830115fbb46c592a6303dbf6c`. Make sure to replace this address with one of the two you created earlier.
+
+#include_code deploy yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+Save the contract address as an environment variable. We will use it later.
+
+```bash
+export CONTRACT_ADDRESS=<Your new contract address>
+```
+
+:::info
+If you use a different address in the constructor above, you will get an error when running the deployment. This is because you need to register an account in the sandbox before it can receive private notes. When you create a new account, it gets automatically registered. Alternatively, you can register an account you do not own along with its public key using the `register-recipient` command.
+:::
+
+This command takes 1 mandatory positional argument which is the path to the contract ABI file in a JSON format (e.g. `contracts/target/PrivateToken.json`).
+Alternatively you can pass the name of an example contract as exported by `@aztec/noir-contracts` (run `aztec-cli example-contracts` to see the full list of contracts available).
+
+The command takes a few optional arguments while the most important one is:
+
+- `--args` - Arguments to the constructor of the contract. In this case we have minted 1000000 initial tokens to the aztec address 0x20d3321707d53cebb168568e25c5c62a853ae1f0766d965e00d6f6c4eb05d599.
+
+The CLI tells us that the contract was successfully deployed. We can use the `check-deploy` command to verify that a contract has been successfully deployed to that address:
+
+#include_code check-deploy yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+## Calling a View Method
+
+When we deployed the token contract, an initial supply of tokens was minted to the address provided in the constructor. We can now query the `getBalance()` method on the contract to retrieve the balance of that address. Make sure to replace the `contract-address` with the deployment address you got from the previous command, and the `args` with the account you used in the constructor.
+
+#include_code call yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+The `call` command calls a read-only method on a contract, one that will not generate a transaction to be sent to the network. The arguments here are:
+
+- `--args` - The address for which we want to retrieve the balance.
+- `--contract-abi` - The abi of the contract we are calling.
+- `--contract-address` - The address of the deployed contract
+
+As you can see from the result, this address has a balance of 1000000, as expected. When using the Sandbox, you are able to query the balance of any account that has been created in the system, even the accounts created by default. You may wonder why this is, as you haven't provided the private keys for these accounts. The Sandbox contains a component known as the AztecRPCServer. When an account is created, this component stores the provided encryption private key and is able to read the account's private state meaning that the Sandbox can report the balance of any of it's accounts. More information about the account model can be found [here](../../concepts/foundation/accounts/main.md).
+
+## Sending a Transaction
+
+We can now send a transaction to the network. We will transfer funds from the owner of the initial minted tokens to our other account. For this we will use the `send` command, which expects as arguments the quantity of tokens to be transferred, the sender's address, and the recipient's address. Make sure to replace all addresses in this command with the ones for your run.
+
+#include_code send yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+We called the `transfer` function of the contract and provided these arguments:
+
+- `--args` - The list of arguments to the function call.
+- `--contract-abi` - The abi of the contract to call.
+- `--contract-address` - The deployed address of the contract to call.
+- `--private-key` - The private key of the sender
+
+The command output tells us the details of the transaction such as its hash and status. We can use this hash to query the receipt of the transaction at a later time:
+
+#include_code get-tx-receipt yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+Let's now call `getBalance()` on each of our accounts and we should see updated values:
 
-To get up and running with the Aztec CLI head over to the [getting start page](./cli.md).
+#include_code calls yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash

docs/docs/dev_docs/contracts/compiling.md

@@ -145,7 +145,7 @@ The compiler exposes the following functions:
 
 ## Next steps
 
-Once you have compiled your contracts, you can use the generated artifacts via the `Contract` class in the `aztec.js` package to deploy and interact with them, or rely on the type-safe typescript classes directly. Alternatively, use the CLI [to deploy](../../dev_docs/cli/cli.md#deploying-a-token-contract) and [interact](../../dev_docs/cli/cli.md#sending-a-transaction) with them.
+Once you have compiled your contracts, you can use the generated artifacts via the `Contract` class in the `aztec.js` package to deploy and interact with them, or rely on the type-safe typescript classes directly. Alternatively, use the CLI [to deploy](../../dev_docs/cli/main.md#deploying-a-token-contract) and [interact](../../dev_docs/cli/main.md#sending-a-transaction) with them.
 
 import Disclaimer from "../../misc/common/\_disclaimer.mdx";
 <Disclaimer/>

docs/docs/dev_docs/contracts/deploying.md

@@ -4,8 +4,8 @@ Once you have [compiled](./compiling.md) your contracts you can proceed to deplo
 
 ## Prerequisites
 - aztec-cli installed (go to [CLI main section](../cli/main.md) for installation instructions)
-- contract artifacts ready (go to [Compiling contracts section](../contracts/compiling.md) for instructions on how to compile contracts)
-- aztec-sandbox running (go to [Sandbox section](../sandbox/main.md) for instructions on how to install and run the sandbox)
+- contract artifacts ready (go to [Compiling contracts section](./compiling.md) for instructions on how to compile contracts)
+- aztec-sandbox running (go to [Sandbox section](../getting_started/sandbox.md) for instructions on how to install and run the sandbox)
 
 ## Deploy
 

docs/docs/dev_docs/contracts/layout.md

@@ -35,4 +35,4 @@ Here's a common layout for a basic Aztec.nr Contract project:
 ```
 
 - See the vanilla Noir docs for [more info on packages](https://noir-lang.org/modules_packages_crates/crates_and_packages).
-- You can review the structure of a complete contract in the token contract tutorial [here](../getting_started/token_contract_tutorial.md).
+- You can review the structure of a complete contract in the token contract tutorial [here](../tutorials/writing_token_contract.md).