diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 818e22a39f18150cc4139d56b2b0916207cb88da..246f6c086946f3b3d1fdd312663a1c3ec859a0da 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,7 +3,7 @@
Contributions are welcome from the community. Questions can be asked on the
[issues page][1]. Before creating a new issue, please take a moment to search
and make sure a similar issue does not already exist. If one does exist, you
-can comment (most simply even with just a `:+1:`) to show your support for that
+can comment (most simply even with just a :+1:) to show your support for that
issue.
If you have direct contributions you would like considered for incorporation
diff --git a/README.md b/README.md
index deae174278884041dc3a8f35983b3647532a5415..a72387778e86ec66bf7fa62c1ca6140ebcfad7aa 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,24 @@
# NSHM: Hawaiʻi
National Seismic Hazard Model (NSHM) for the state of Hawaiʻi. This model is intended for use with
-U.S. Geological Survey (USGS) hazard software [*nshmp-haz-v2*][1].
+U.S. Geological Survey (USGS) hazard software [*nshmp-haz*][1].
-For details on the format of this model, see the
-[*nshmp-haz-v2* user guide and implementation reference][2].
+For details on the format of this model, see the *nshmp-haz*
+[user guide and implementation reference][2].
For prior models, see the [U.S. Seismic Hazard Maps – Hawaii][3] data release.
## Model Notes
-All NSHM Hawaii sources are assigned to the top-level `volcanic` tectonic setting. NSHM Hawaii source ID numbers are in the range 5000-5999 (see [nshm-fault-sections Numbering][4]).
-
-### Source and region IDs
-
-Folder | Source Name | ID
--------------- |-------- |:--:
-decollement-sources/south-flank | South Flank (merged) | 5011
-decollement-sources/south-flank | South Flank (extended) | 5012
-decollement-sources/west-flank | West Flank (Hualalai) | 5005
-decollement-sources/west-flank | West Flank (Kona) | 5006
-decollement-sources/west-flank | West Flank (merged) | 5007
-decollement-sources/west-flank | West Flank (extended) | 5008
-grid-sources/non-summit | Non-Summit - Deep/Shallow | 5101
-grid-sources/summit | Summit - Deep/Shallow | 5100
-zone-sources/caldera | Caldera Collapse | 5050
+All NSHM Hawaii sources are assigned to the top-level `volcanic` tectonic setting.
## References
-Petersen, M.D, Shumway, A.M., Powers, P.M., Moschetti, M.P., Llenos, A.L., Michael, A.J., Mueller, C.S., Frankel, A.D., Rezaeian, S., Rukstales, K.S., McNamara. D.E., Okubo, P.G., Zeng, Y., Jaiswal, K.S.,, Ahdi, S.K., Altekruse, J.M., and Shiro, B.R., 2021, 2021 U.S. National Seismic Hazard Model for the State of Hawaii, Earthquake Spectra, in press.
+Petersen, M.D, Shumway, A.M., Powers, P.M., Moschetti, M.P., Llenos, A.L., Michael, A.J., Mueller,
+C.S., Frankel, A.D., Rezaeian, S., Rukstales, K.S., McNamara. D.E., Okubo, P.G., Zeng, Y., Jaiswal,
+K.S., Ahdi, S.K., Altekruse, J.M., and Shiro, B.R., 2021, 2021 U.S. National Seismic Hazard Model
+for the State of Hawaii, _Earthquake Spectra_, in press.
[1]: https://code.usgs.gov/ghsc/nshmp/nshmp-haz
-[2]: https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/-/tree/master/docs
+[2]: https://code.usgs.gov/ghsc/nshmp/nshmp-haz/-/tree/main/docs
[3]: https://www.usgs.gov/natural-hazards/earthquake-hazards/science/us-seismic-hazard-maps-hawaii?qt-science_center_objects=0#qt-science_center_objects
-[4]: https://code.usgs.gov/ghsc/nshmp/nshm-fault-sections/-/blob/master/docs/Contents.md
diff --git a/volcanic/decollement-sources/README.md b/volcanic/decollement-sources/README.md
index df0374710e46ae7232b18d90d6d47d9d504beb3d..9d352c61106a563db468c929701e10007bdac7c1 100644
--- a/volcanic/decollement-sources/README.md
+++ b/volcanic/decollement-sources/README.md
@@ -2,15 +2,36 @@
## South Flank
-The detachement sources on the south flank of the Island of Hawai‘i are a logic tree of two alternative models:
+The detachement sources on the south flank of the Island of Hawai‘i are a logic tree of two
+alternative models:
-1. A `merged` branch that envelopes the HÄ«lea, Kaoiki, and KÄ«lauea detachements of Klein et al. (2001).
-2. An `extended` branch that extends the merged model northward to the limit of recent geodetic strain accumulation, seismicity, and faulting.
+1. A `merged` branch that envelopes the HÄ«lea, Kaoiki, and KÄ«lauea detachements of Klein et
+ al. (2001).
+2. An `extended` branch that extends the merged model northward to the limit of recent geodetic
+ strain accumulation, seismicity, and faulting.
## West Flank
-The detachement sources on the west flank of the Island of Hawai‘i are a logic tree of three alternative models:
+The detachement sources on the west flank of the Island of Hawai‘i are a logic tree of three
+alternative models:
-1. A `segemented` branch that maintains the original Kona and HualÄlai detachments of Klein et al. (2001).
+1. A `segemented` branch that maintains the original Kona and HualÄlai detachments of Klein et
+ al. (2001).
2. A `merged` branch that combined the two Klein et al. (2001) detachments.
-3. An `extended` branch that extends the merged model southward to be contiguous with detachment sources on the south flank of the island.
+3. An `extended` branch that extends the merged model southward to be contiguous with detachment
+ sources on the south flank of the island.
+
+## Source names and IDs
+
+NSHM Hawaii source ID numbers are in the range 5000-5999 (see [nshm-fault-sections Numbering][1]).
+
+Folder | Source Name | ID
+-------------- |-------- |:--:
+decollement-sources/south-flank | South Flank (merged) | 5011
+decollement-sources/south-flank | South Flank (extended) | 5012
+decollement-sources/west-flank | West Flank (Hualalai) | 5005
+decollement-sources/west-flank | West Flank (Kona) | 5006
+decollement-sources/west-flank | West Flank (merged) | 5007
+decollement-sources/west-flank | West Flank (extended) | 5008
+
+[1]: https://code.usgs.gov/ghsc/nshmp/nshm-fault-sections/-/blob/master/docs/Contents.md
diff --git a/volcanic/grid-sources/README.md b/volcanic/grid-sources/README.md
index 6e7066f2a5117edd8abce212f83b80bd3682abc9..c0d194eb739b3187e28f556a2182c1f0f8860d23 100644
--- a/volcanic/grid-sources/README.md
+++ b/volcanic/grid-sources/README.md
@@ -1,14 +1,26 @@
# Gridded Seismicity sources
-Gridded (and smoothed) seismicity sources are modeled as uniformely distributed rupture sets (0.02° spacing) at two discrete depths (10 km and 40 km) with a unique logic tree of GMMs for each. Consistent with spatially varying properties of the earthquake catalog considered, source regions are further subdivided on the basis of observed rate differences between the 'summit' region on the Island of Hawaiʻi and everywhere else. Shallow sources outside the summit region are further subdivided into north and south regions.
+Gridded (or smoothed) seismicity sources are modeled as uniformely distributed rupture sets
+(0.02° spacing) at two discrete depths (10 km and 40 km) with a unique logic tree of GMMs for
+each. Consistent with spatially varying properties of the earthquake catalog considered, source
+regions are further subdivided on the basis of observed rate differences between the 'summit'
+region on the Island of Hawaiʻi and everywhere else. Shallow sources outside the summit region
+are further subdivided into north and south regions.
-All sub-catalogs were declusterd using nearest-neighbor (`nn`) and Reasenberg (1985; `r85`) algorithms prior to smoothing earthquake rates using a single, adaptive kernel approach.
+All sub-catalogs were declusterd using nearest-neighbor (`nn`) and Reasenberg (1985; `r85`)
+algorithms prior to smoothing earthquake rates using a single, adaptive kernel approach.
## Gridded rates
-Rates of M = 5.0 earthquakes, `n(m=5)`, given in Table 1 of Petersen et al. (2014) are the Gutenberg-Richter rate of magnitude 5.0 earthquakes derived from the total gridded a-value multiplied by a scale factor for the catalog time period and declustering method. These `n(m=5)` rates are converted to a-values (rate of earthquakes of magnitude 0.0) using \=10^{a-bm}) for use in grid-source `rate-tree.json` files. Spatial PDFs were created by normalizing the 1960-2019 catalog a-grid file.
+Rates of M = 0.0 earthquakes, `n(M=0)`, given in Table 1 of Petersen et al. (2014) are the
+incremental Gutenberg-Richter a-value in
+\=10^{a-bm}). They are
+derived from the total gridded a-value of a rupture set multiplied by a scale factor
+for the catalog time period and declustering method; see grid-source `rate-tree.json`
+files. Individual point source rates are the product of the total rate and the corresponding
+spatial PDF value. Spatial PDFs were created by normalizing the 1960-2019 catalog a-grid file.
-## Grid source rupture set names and IDs
+## Source names and IDs
Region | Depth | PDF¹ | ID
-----------|-----------------|------|:--:
@@ -23,4 +35,5 @@ non-summit | shallow (north) | r85 | 5123
non-summit | shallow (south) | nn | 5124
non-summit | shallow (south) | r85 | 5125
---
-¹ Refers to the declustering model ID for the corresponding gridded seismicity spatial probability density function (PDF)
+¹ Refers to the declustering model ID for the corresponding gridded seismicity spatial probability
+ density function (PDF)
diff --git a/volcanic/zone-sources/README.md b/volcanic/zone-sources/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..8f7ca0ca94f19416887e080b1b8041e25dfe6dce
--- /dev/null
+++ b/volcanic/zone-sources/README.md
@@ -0,0 +1,7 @@
+# KÄ«lauea Caldera Collapse Source Zone
+
+Collapse events are modeled as shallow (1 km) point sources spaced at 0.02°. They occupy a
+region roughly coincident with the caldera bounds where all of the M≥5 collapse events in the
+catalog considered for the model occurred.
+
+**Source ID:** 5050
diff --git a/volcanic/zone-sources/caldera/README.md b/volcanic/zone-sources/caldera/README.md
deleted file mode 100644
index 0a7e6109e902d363138ccd3a8eb341c3f34b8f90..0000000000000000000000000000000000000000
--- a/volcanic/zone-sources/caldera/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# KÄ«lauea Caldera Collapse Source Zone
-
-Collapse events are modeled as shallow (1 km) point sources spaced at 0.02°. They occupy a region roughly coincident with the caldera bounds where all of the M≥5 collapse events in the catalog considered for the model occurred.