diff --git a/README.md b/README.md
index 4fb1eb60895..f0855ee6989 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,31 @@
-# AZTEC 3 Monorepo
+# Aztec 3 Monorepo
 
-All the packages that make up Aztec 3. Typescript projects exist in yarn-project.
+All the packages that make up [Aztec 3](https://docs.aztec.network/aztec3/overview).
 
-Package development:
+- [**`circuits`**](/circuits): C++ code for circuits and cryptographic functions
+- [**`l1-contracts`**](/l1-contracts): Solidity code for the Ethereum contracts that process rollups
+- [**`yarn-project`**](/yarn-project): Typescript code for client and backend
 
-- Run `yarn build:dev` in the root to interactively build the package.
-- Run `yarn prepare` in the root to update tsconfig.json and build_manifest.json files based on package.json contents.
-  Note this only analyzes package.json imports to @aztec/\* packages.
+## Issues Board
 
-Repo architecture:
+All issues being worked on are tracked on the [A3 Github Project](https://github.com/orgs/AztecProtocol/projects/22). For a higher-level roadmap, check the [milestones overview](https://docs.aztec.network/aztec3/milestones) section of our docs.
 
-- yarn-project/tsconfig.json: Base tsconfig file, extended by all packages. Used directly by vscode and eslint, where it functions to include the whole project without listing project references.
-- yarn-project/tsconfig.json: Used by `yarn build:dev` in root.
-- package/tsconfig.json: Each package has its own file that specifies its project reference dependencies. This allows them to be built independently.
+## Development Setup
+
+Run `bootstrap.sh` in the project root to set up your environment. This will update git submodules, download ignition transcripts, build all C++ circuits code, install Foundry, compile Solidity contracts, install the current node version via nvm, and build all typescript packages.
+
+To build C++ code, make sure to fullfil the [requirements from barretenberg](https://github.com/AztecProtocol/barretenberg/#dependencies), the underlying cryptographic library we maintain. To build Typescript code, make sure to have [`nvm`](https://github.com/nvm-sh/nvm) (node version manager) installed.
+
+## Continuous Integration
+
+This repository uses CircleCI for continuous integration. Build steps are managed using [`build-system`](https://github.com/AztecProtocol/build-system). Small packages are built and tested as part of a docker build operation, while larger ones and end-to-end tests spin up a large AWS spot instance. Each successful build step creates a new docker image that gets tagged with the package name and commit.
+
+All packages need to be included in the [build manifest](`build_manifest.json`), which declares what paths belong to each package, as well as dependencies between packages. When the CI runs, if none of the rebuild patterns or dependencies were changed, then the build step is skipped and the last successful image is re-tagged with the current commit. Read more on the [`build-system`](https://github.com/AztecProtocol/build-system) repository README.
+
+## Debugging
+
+Logging goes through the [`info` and `debug`](circuits/cpp/barretenberg/cpp/src/barretenberg/common/log.hpp) functions in C++, and through the [DebugLogger](yarn-project/foundation/src/log/debug.ts) module in Typescript. To see the log output, set a `DEBUG` environment variable to the name of the module you want to debug, to `aztec:*`, or to `*` to see all logs.
+
+## Contributing
+
+To contribute, make sure to pick an existing issue and assign yourself to it, or notify that you'll be working on it. If you're new to the repository, look for those tagged as [`good-first-issue`](https://github.com/AztecProtocol/aztec3-packages/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). Then send a pull request with your contribution, linking back to the issue it fixes.
diff --git a/bootstrap.sh b/bootstrap.sh
index ba245880ae9..0946e34c92b 100755
--- a/bootstrap.sh
+++ b/bootstrap.sh
@@ -36,6 +36,10 @@ cd circuits/cpp
 ./bootstrap.sh
 cd ../..
 
+cd l1-contracts
+./bootstrap.sh
+cd ..
+
 if [ "$(uname)" = "Darwin" ]; then
   # works around https://github.com/AztecProtocol/aztec3-packages/issues/158
   echo "Note: not sourcing nvm on Mac, see github #158"
diff --git a/yarn-project/README.md b/yarn-project/README.md
new file mode 100644
index 00000000000..0b56a1fb72e
--- /dev/null
+++ b/yarn-project/README.md
@@ -0,0 +1,40 @@
+# Aztec 3 Typescript Packages
+
+All the Typescript packages that make up [Aztec 3](https://docs.aztec.network/aztec3/overview).
+
+## Development
+
+All scripts are run in the `yarn-project` workspace root:
+
+- Run `yarn` to install dependencies
+- Run `yarn build:dev` to compile all packages on file changes
+- Run `yarn prepare` to update `tsconfig.json` and `build_manifest.json` references
+- Run `yarn format` to prettify all files
+- Run `yarn formatting` to check prettier and eslint rules on each package (slow)
+
+## Tests
+
+To run tests for a specific package, just run `yarn test` in its folder. Note that `end-to-end` tests require `anvil` to be running, which is installed as part of the Foundry toolchain.
+
+## Useful extensions
+
+Consider installing the Prettier and ESLint extensions if using VSCode. Configure Prettier to format the code on save, and ensure that ESLint errors are shown in your IDE.
+
+## Typescript config
+
+- `yarn-project/tsconfig.json`: Base tsconfig file, extended by all packages. Used directly by vscode and eslint, where it functions to include the whole project without listing project references.
+- `yarn-project/[package]/tsconfig.json`: Each package has its own file that specifies its project reference dependencies. This allows them to be built independently.
+
+## Package.json inheritance
+
+To simplify the management of all package.json files, we have a custom script that injects the contents of `package.common.json` into all packages that reference it via the `inherits` custom field. To run the script, just run `yarn prepare`. To override any of the fields from `package.common.json`, declare a `package.local.json` local to the package and add it to the `inherits` field.
+
+## Adding a new package
+
+To add a new package, make sure to add it to the `build_manifest.json`, to the `workspaces` entry in the root `package.json`, and to the `.circleci/config`. Then, copy the structure from another existing package, including:
+
+- `.eslintrc.cjs`
+- `Dockerfile`
+- `package.json`
+- `README.md`
+- `tsconfig.json`