diff --git a/README.md b/README.md
index 3706438..17a85df 100644
--- a/README.md
+++ b/README.md
@@ -2,10 +2,480 @@
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![UPRJ_CI](https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg)](https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml) [![Caravel Build](https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg)](https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml)
 
-| :exclamation: Important Note            |
-|-----------------------------------------|
-
 ## Please fill in your project documentation in this README.md file 
 
 
 Refer to [README](docs/source/index.rst) for this sample project documentation. 
+
+
+.. raw:: html
+
+   <!---
+   # SPDX-FileCopyrightText: 2020 Efabless Corporation
+   #
+   # Licensed under the Apache License, Version 2.0 (the "License");
+   # you may not use this file except in compliance with the License.
+   # You may obtain a copy of the License at
+   #
+   #      http://www.apache.org/licenses/LICENSE-2.0
+   #
+   # Unless required by applicable law or agreed to in writing, software
+   # distributed under the License is distributed on an "AS IS" BASIS,
+   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   # See the License for the specific language governing permissions and
+   # limitations under the License.
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   -->
+
+Caravel User Project
+====================
+
+|License| |User CI| |Caravel Build|
+
+Table of contents
+=================
+
+-  `Overview <#overview>`__
+-  `Install Caravel <#install-caravel>`__
+-  `Caravel Integration <#caravel-integration>`__
+
+   -  `Repo Integration <#repo-integration>`__
+   -  `Verilog Integration <#verilog-integration>`__
+   -  `Layout Integration <#layout-integration>`__
+
+-  `Running Full Chip Simulation <#running-full-chip-simulation>`__
+-  `User Project Wrapper Requirements <#user-project-wrapper-requirements>`__
+-  `Hardening the User Project using
+   Openlane <#hardening-the-user-project-using-openlane>`__
+-  `Checklist for Open-MPW
+   Submission <#checklist-for-open-mpw-submission>`__
+
+Overview
+========
+
+This repo contains a sample user project that utilizes the
+`caravel <https://github.com/efabless/caravel.git>`__ chip user space.
+The user project is a simple counter that showcases how to make use of
+`caravel's <https://github.com/efabless/caravel.git>`__ user space
+utilities like IO pads, logic analyzer probes, and wishbone port. The
+repo also demonstrates the recommended structure for the open-mpw
+shuttle projects.
+
+Prerequisites
+=============
+
+- Docker
+
+Install Caravel
+===============
+
+To setup caravel, run the following:
+
+.. code:: bash
+
+    # If unset, CARAVEL_ROOT will be set to $(pwd)/caravel
+    # If you want to install caravel at a different location, run "export CARAVEL_ROOT=<caravel-path>"
+    export CARAVEL_ROOT=$(pwd)/caravel
+
+    # Disable submodule installation if needed by, run "export SUBMODULE=0"
+    
+    git clone https://github.com/efabless/caravel_user_project.git
+    cd caravel_user_project
+    make install
+
+To update the installed caravel to the latest, run:
+
+.. code:: bash
+
+     make update_caravel
+
+To remove caravel, run
+
+.. code:: bash
+
+    make uninstall
+
+By default
+`caravel-lite <https://github.com/efabless/caravel-lite.git>`__ is
+installed. To install the full version of caravel, run this prior to
+calling make install.
+
+.. code:: bash
+
+    export CARAVEL_LITE=0
+
+Caravel Integration
+===================
+
+Repo Integration
+----------------
+
+Caravel files are kept separate from the user project by having caravel
+as submodule. The submodule commit should point to the latest of
+caravel/caravel-lite master/main branch. The following files should have a symbolic
+link to `caravel's <https://github.com/efabless/caravel.git>`__
+corresponding files:
+
+-  `Openlane Makefile <../../openlane/Makefile>`__: This provides an easier
+   way for running openlane to harden your macros. Refer to `Hardening
+   the User Project Macro using
+   Openlane <#hardening-the-user-project-macro-using-openlane>`__. Also,
+   the makefile retains the openlane summary reports under the signoff
+   directory.
+
+-  `Pin order <../../openlane/user_project_wrapper/pin_order.cfg>`__ file for
+   the user wrapper: The hardened user project wrapper macro must have
+   the same pin order specified in caravel's repo. Failing to adhere to
+   the same order will fail the gds integration of the macro with
+   caravel's back-end.
+
+The symbolic links are automatically set when you run ``make install``.
+
+Verilog Integration
+-------------------
+
+You need to create a wrapper around your macro that adheres to the
+template at
+`user\_project\_wrapper <https://github.com/efabless/caravel/blob/master/verilog/rtl/__user_project_wrapper.v>`__.
+The wrapper top module must be named ``user_project_wrapper`` and must
+have the same input and output ports as the golden wrapper `template <https://github.com/efabless/caravel/blob/master/verilog/rtl/__user_project_wrapper.v>`__. The wrapper gives access to the
+user space utilities provided by caravel like IO ports, logic analyzer
+probes, and wishbone bus connection to the management SoC.
+
+For this sample project, the user macro makes use of:
+
+-  The IO ports for displaying the count register values on the IO pads.
+
+-  The LA probes for supplying an optional reset and clock signals and
+   for setting an initial value for the count register.
+
+-  The wishbone port for reading/writing the count value through the
+   management SoC.
+
+Refer to `user\_project\_wrapper <../../verilog/rtl/user_project_wrapper.v>`__
+for more information.
+
+.. raw:: html
+
+   <p align="center">
+   <img src="./_static/counter_32.png" width="50%" height="50%">
+   </p>
+
+.. raw:: html
+
+   </p>
+
+
+Layout Integration
+-------------------
+
+The caravel layout is pre-designed with an empty golden wrapper in the user space. You only need to provide us with a valid ``user_project_wrapper`` GDS file. And, as part of the tapeout process, your hardened ``user_project_wrapper`` will be inserted into a vanilla caravel layout to get the final layout shipped for fabrication. 
+
+.. raw:: html
+
+   <p align="center">
+   <img src="./_static/layout.png" width="80%" height="80%">
+   </p>
+   
+To make sure that this integration process goes smoothly without having any DRC or LVS issues, your hardened ``user_project_wrapper`` must adhere to a number of requirements listed at `User Project Wrapper Requirements <#user-project-wrapper-requirements>`__ .
+
+
+Building the PDK 
+================
+
+You have two options for building the pdk: 
+
+- Build the pdk natively. 
+
+Make sure you have `Magic VLSI Layout Tool <http://opencircuitdesign.com/magic/index.html>`__ installed on your machine before building the pdk. 
+The pdk build is tested with magic version ``8.3.209``. 
+
+.. code:: bash
+
+    # set PDK_ROOT to the path you wish to use for the pdk
+    export PDK_ROOT=<pdk-installation-path>
+
+    # you can optionally specify skywater-pdk and open-pdks commit used
+    # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
+    # if you do not set them, they default to the last verfied commits tested for this project
+
+    make pdk
+
+- Build the pdk using openlane's docker image which has magic installed. 
+
+.. code:: bash
+
+    # set PDK_ROOT to the path you wish to use for the pdk
+    export PDK_ROOT=<pdk-installation-path>
+
+    # you can optionally specify skywater-pdk and open-pdks commit used
+    # by setting and exporting SKYWATER_COMMIT and OPEN_PDKS_COMMIT
+    # if you do not set them, they default to the last verfied commits tested for this project
+
+    make pdk-nonnative
+
+Running Full Chip Simulation
+============================
+
+First, you will need to install the simulation environment, by
+
+.. code:: bash
+
+    make simenv
+
+This will pull a docker image with the needed tools installed.
+
+Then, run the RTL simulation by
+
+.. code:: bash
+
+    export PDK_ROOT=<pdk-installation-path>
+    export CARAVEL_ROOT=$(pwd)/caravel
+    # specify simulation mode: RTL/GL
+    export SIM=RTL
+    # Run RTL simulation on IO ports testbench, make verify-io_ports
+    make verify-<testbench-name>
+
+Once you have the physical implementation done and you have the gate-level netlists ready, it is crucial to run full gate-level simulations to make sure that your design works as intended after running the physical implementation. 
+
+Run the gate-level simulation by: 
+
+.. code:: bash
+
+    export PDK_ROOT=<pdk-installation-path>
+    export CARAVEL_ROOT=$(pwd)/caravel
+    # specify simulation mode: RTL/GL
+    export SIM=GL
+    # Run RTL simulation on IO ports testbench, make verify-io_ports
+    make verify-<testbench-name>
+
+
+This sample project comes with four example testbenches to test the IO port connection, wishbone interface, and logic analyzer. The test-benches are under the
+`verilog/dv <https://github.com/efabless/caravel_user_project/tree/main/verilog/dv>`__ directory. For more information on setting up the
+simulation environment and the available testbenches for this sample
+project, refer to `README <https://github.com/efabless/caravel_user_project/blob/main/verilog/dv/README.md>`__.
+
+
+User Project Wrapper Requirements
+=================================
+
+Your hardened ``user_project_wrapper`` must match the `golden user_project_wrapper <https://github.com/efabless/caravel/blob/master/gds/user_project_wrapper_empty.gds.gz>`__ in the following: 
+
+- Area ``(2.920um x 3.520um)``
+- Top module name ``"user_project_wrapper"``
+- Pin Placement
+- Pin Sizes 
+- Core Rings Width and Offset
+- PDN Vertical and Horizontal Straps Width 
+
+
+.. raw:: html
+
+   <p align="center">
+   <img src="./_static/empty.png" width="40%" height="40%">
+   </p>
+ 
+
+These fixed configurations are specified `here <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/fixed_wrapper_cfgs.tcl>`__ .
+
+However, you are allowed to change the following if you need to: 
+
+- PDN Vertical and Horizontal Pitch & Offset
+
+.. raw:: html
+
+   <p align="center">
+   <img src="./_static/pitch.png" width="30%" height="30%">
+   </p>
+ 
+To make sure that you adhere to these requirements, we run an exclusive-or (XOR) check between your hardened ``user_project_wrapper`` GDS and the golden wrapper GDS after processing both layouts to include only the boundary (pins and core rings). This check is done as part of the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ tool. 
+
+
+Hardening the User Project using OpenLane
+==========================================
+
+OpenLane Installation 
+---------------------
+
+You will need to install openlane by running the following
+
+.. code:: bash
+
+   export OPENLANE_ROOT=<openlane-installation-path>
+
+   # you can optionally specify the openlane tag to use
+   # by running: export OPENLANE_TAG=<openlane-tag>
+   # if you do not set the tag, it defaults to the last verfied tag tested for this project
+
+   make openlane
+
+For detailed instructions on the openlane and the pdk installation refer
+to
+`README <https://github.com/The-OpenROAD-Project/OpenLane#setting-up-openlane>`__.
+
+Hardening Options 
+-----------------
+
+There are three options for hardening the user project macro using
+openlane:
+
++--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
+|           Option 1                                           |            Option 2                        |           Option 3                         |
++--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
+| Hardening the user macro(s) first, then inserting it in the  |  Flattening the user macro(s) with the     | Placing multiple macros in the wrapper     |
+| user project wrapper with no standard cells on the top level |  user_project_wrapper                      | along with standard cells on the top level |
++==============================================================+============================================+============================================+
+| |pic1|                                                       | |pic2|                                     | |pic3|                                     |
+|                                                              |                                            |                                            |
++--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
+|           ex: |link1|                                        |                                            |           ex: |link2|                      |
++--------------------------------------------------------------+--------------------------------------------+--------------------------------------------+
+
+.. |link1| replace:: `caravel_user_project <https://github.com/efabless/caravel_user_project>`__
+
+.. |link2| replace:: `caravel_ibex <https://github.com/efabless/caravel_ibex>`__
+
+
+.. |pic1| image:: ./_static/option1.png
+   :width: 48%
+
+.. |pic2| image:: ./_static/option2.png
+   :width: 140%
+
+.. |pic3| image:: ./_static/option3.png
+   :width: 72%
+
+For more details on hardening macros using openlane, refer to `README <https://github.com/The-OpenROAD-Project/OpenLane/blob/master/docs/source/hardening_macros.md>`__.
+
+
+Running OpenLane 
+-----------------
+
+For this sample project, we went for the first option where the user
+macro is hardened first, then it is inserted in the user project
+wrapper without having any standard cells on the top level.
+
+.. raw:: html
+
+   <p align="center">
+   <img src="./_static/wrapper.png" width="30%" height="30%">
+   </p>
+
+.. raw:: html
+
+   </p>
+   
+To reproduce hardening this project, run the following:
+
+.. code:: bash
+
+   # Run openlane to harden user_proj_example
+   make user_proj_example
+   # Run openlane to harden user_project_wrapper
+   make user_project_wrapper
+
+
+For more information on the openlane flow, check `README <https://github.com/The-OpenROAD-Project/OpenLane#readme>`__.
+
+Running MPW Precheck Locally
+=================================
+
+You can install the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ by running 
+
+.. code:: bash
+
+   # By default, this install the precheck in your home directory
+   # To change the installtion path, run "export PRECHECK_ROOT=<precheck installation path>" 
+   make precheck
+
+This will clone the precheck repo and pull the latest precheck docker image. 
+
+
+Then, you can run the precheck by running
+Specify CARAVEL_ROOT before running any of the following, 
+
+.. code:: bash
+
+   # export CARAVEL_ROOT=$(pwd)/caravel 
+   export CARAVEL_ROOT=<path-to-caravel>
+   make run-precheck
+
+This will run all the precheck checks on your project and will produce the logs under the ``checks`` directory.
+
+
+Other Miscellaneous Targets
+============================
+
+The makefile provides a number of useful that targets that can run LVS, DRC, and XOR checks on your hardened design outside of openlane's flow. 
+
+Run ``make help`` to display available targets. 
+
+Specify CARAVEL_ROOT before running any of the following, 
+
+.. code:: bash
+
+   # export CARAVEL_ROOT=$(pwd)/caravel 
+   export CARAVEL_ROOT=<path-to-caravel>
+
+Run lvs on the mag view, 
+
+.. code:: bash
+
+   make lvs-<macro_name>
+
+Run lvs on the gds, 
+
+.. code:: bash
+
+   make lvs-gds-<macro_name>
+
+Run lvs on the maglef, 
+
+.. code:: bash
+
+   make lvs-maglef-<macro_name>
+
+Run drc using magic,
+
+.. code:: bash
+
+   make drc-<macro_name>
+
+Run antenna check using magic, 
+
+.. code:: bash
+
+   make antenna-<macro_name>
+
+Run XOR check, 
+
+.. code:: bash
+
+   make xor-wrapper
+
+
+Checklist for Open-MPW Submission
+=================================
+
+-  ✔️ The project repo adheres to the same directory structure in this
+   repo.
+-  ✔️ The project repo contain info.yaml at the project root.
+-  ✔️ Top level macro is named ``user_project_wrapper``.
+-  ✔️ Full Chip Simulation passes for RTL and GL (gate-level)
+-  ✔️ The hardened Macros are LVS and DRC clean
+-  ✔️ The project contains a gate-level netlist for ``user_project_wrapper`` at verilog/gl/user_project_wrapper.v
+-  ✔️ The hardened ``user_project_wrapper`` adheres to the same pin
+   order specified at
+   `pin\_order <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/pin_order.cfg>`__
+-  ✔️ The hardened ``user_project_wrapper`` adheres to the fixed wrapper configuration specified at `fixed_wrapper_cfgs <https://github.com/efabless/caravel/blob/master/openlane/user_project_wrapper_empty/fixed_wrapper_cfgs.tcl>`__
+-  ✔️ XOR check passes with zero total difference.
+-  ✔️ Openlane summary reports are retained under ./signoff/
+-  ✔️ The design passes the `mpw-precheck <https://github.com/efabless/mpw_precheck>`__ 
+
+.. |License| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
+   :target: https://opensource.org/licenses/Apache-2.0
+.. |User CI| image:: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml/badge.svg
+   :target: https://github.com/efabless/caravel_project_example/actions/workflows/user_project_ci.yml
+.. |Caravel Build| image:: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml/badge.svg
+   :target: https://github.com/efabless/caravel_project_example/actions/workflows/caravel_build.yml