diff --git a/README.md b/README.md
index 20ef395..408f743 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,19 @@
 # surplus
 
-Plus Code to iOS-Shortcuts-like shareable text
+surplus is a Python script to convert
+[Google Map Plus Codes](https://maps.google.com/pluscodes/)
+to iOS Shortcuts-like human text.
 
-- [Installing](#installing)
-- [Usage](#usage)
-  - [Command-line Interface](#command-line-interface)
-  - [API Reference](#api-reference)
-    - [surplus.surplus()](#surplussurplus)
-    - [surplus.parse_query()](#surplusparse_query)
-    - [surplus.handle_query()](#surplushandle_query)
-    - [surplus.Localcode](#surpluslocalcode)
-    - [surplus.Latlong](#surpluslatlong)
-- [Developing](#developing)
-- [The format is wrong/different!](#the-format-is-wrongdifferent)
-- [Licence](#licence)
+- [installation](#installation)
+- [command-line usage](#command-line-usaage)
+- [developer's guide](#developers-guide)
+  - [api reference](#api-reference)
+- [contributor's guide](#contributors-guide)
+  - [reporting incorrect output](#reporting-incorrect-output)
+    - [the reporting process](#the-reporting-process)
+    - [what counts as "incorrect"](#what-counts-as-incorrect)
+- [output technical details](#the-technical-details-of-surpluss-output)
+- [licence](#licence)
 
 ```text
 $ surplus 9R3J+R9 Singapore
@@ -33,17 +33,15 @@ Central, Singapore
 (True, 'Caldecott Stn Exit 4\nToa Payoh Link\n298106\nCentral, Singapore')
 ```
 
-## Installing
+## installation
 
-Install surplus directly from GitHub using pip:
+install surplus directly from the repository using pip:
 
 ```text
 pip install git+https://github.com/markjoshwel/surplus
 ```
 
-## Usage
-
-### Command-line Interface
+## command-line usage
 
 ```text
 usage: surplus [-h] [-d] [-v] [query ...]
@@ -63,9 +61,370 @@ options:
                  and exits
 ```
 
-### API Reference
+## developer's guide
 
-#### `surplus.surplus()`
+prerequisites:
+
+- [Python >=3.10](https://www.python.org/)
+- [Poetry](https://python-poetry.org/)
+
+alternatively, use [devbox](https://get.jetpack.io/devbox) for a hermetic development environment powered by [Nix](https://nixos.org/).
+
+```text
+devbox shell    # skip this if you aren't using devbox
+poetry install
+poetry shell
+```
+
+## contributor's guide
+
+1. fork the repository and branch off from the `future` branch
+2. make and commit your changes!
+3. pull in any changes from `future`, and resolve any conflicts, if any
+4. **commit your copyright waiver** (_see below_)
+5. submit a pull request (_or mail in a diff_)
+
+when contributing your first changes, please include an empty commit for a copyright
+waiver using the following message (replace 'Your Name' with your name or nickname):
+
+```
+Your Name Copyright Waiver
+
+I dedicate any and all copyright interest in this software to the
+public domain.  I make this dedication for the benefit of the public at
+large and to the detriment of my heirs and successors.  I intend this
+dedication to be an overt act of relinquishment in perpetuity of all
+present and future rights to this software under copyright law.
+```
+
+the command to create an empty commit is `git commit --allow-empty`
+
+### reporting incorrect output
+
+> **Note**  
+> this section is independent from the rest of the contributing section.
+
+different output from the iOS Shortcuts app is expected, however incorrect output is not.
+
+#### the reporting process
+
+open an issue in the
+[repositories issue tracker](https://github.com/markjoshwel/surplus/issues/new),
+and include the following:
+
+1. ensure that your issue is not an error of incorrect data returned by your reverser 
+   function, which by default is OpenStreetMap Nominatim.  
+   (_don't know what the above means? then using the default reverser._)
+
+   also look at "[what counts as 'incorrect'](#what-counts-as-incorrect)" before
+   moving on.
+
+2. include the erroneous Plus Code, local code, latitude and longitude coordinate, or 
+   query string.
+
+3. include output from the teminal with the
+   [`--debug` flag](#command-line-usage) passed to the surplus CLI or with 
+   `debug=True` set in function calls.
+
+   > **Note**  
+   > if you are using custom stdout and stderr parameters and redirecting output,
+   > include that instead.
+
+4. how it should look like instead, with reasoning if the error not obvious. (e.g., missing details)
+
+   for reference, see how the following issues were written:
+
+   - [issue #4: "Incorrect format: repeated lines"](https://github.com/markjoshwel/surplus/issues/4)
+   - [issue #6: "Incorrect format: missing details"](https://github.com/markjoshwel/surplus/issues/6)
+   - [issue #12: "Incorrect format: State before county"](https://github.com/markjoshwel/surplus/issues/12)
+
+#### what counts as "incorrect"
+
+- **example 1**
+
+  - iOS Shortcuts Output
+
+    ```
+    Plaza Singapura
+    68 Orchard Rd
+    238839
+    Singapore
+    ```
+
+  - surplus Output
+
+    ```
+    Plaza Singapura
+    68 Orchard Road
+    Museum
+    238839
+    Central, Singapore
+    ```
+
+  this _should not_ be reported as incorrect, as the only difference between the two is
+  that surplus displays more information.
+
+  note: for singaporean readers, "Musuem" here is correct as it refers to the
+  [Museum planning area](https://en.wikipedia.org/wiki/Museum_Planning_Area),
+  in which Plaza Singapura is located in.
+
+other examples that _should not_ be reported are:
+
+- name of place is incorrect/different
+
+  this may be due to incorrect data from the geolocator function, which is OpenStreetMap Nominatim by default.
+  in the case of Nominatim, it means that there the data on OpenStreetMap is incorrect.
+
+  (_if so, then consider updating OpenStreetMap to help not just you, but other surplus
+  and OpenStreetMap users!_)
+
+you should report when the output does not make logical sense, or something similar 
+wherein the output of surplus is illogical to read or is not correct in the traditional
+sense of a correct address.
+
+see the linked issues in [the reporting process](#the-reporting-process) for examples 
+of incorrect outputs.
+
+## the technical details of surplus's output
+
+```
+$ s+ 8QJF+RP --debug
+surplus version 1.1.3, debug mode
+debug: args.query='8QJF+RP Singapore'
+debug: squery=['8QJF+RP', 'Singapore']
+debug: pcode='8QJF+RP', locality='Singapore'
+debug: lat=1.3320625, lon=103.7743125
+debug: location={...}
+debug: seen_names=['Ngee Ann Polytechnic', '', '', '']
+debug: d=''     _dvtm4=[False, False, False, False]     _dvcm4=[False, False, False, False]
+debug: d='Bukit Timah'  _dvtm4=[True, True, True, True] _dvcm4=[True, True, True, True]
+debug: d='Singapore'    _dvtm4=[True, True, False, True]        _dvcm4=[True, True, True, True]
+0       Ngee Ann Polytechnic
+1
+2
+3       535 Clementi Road
+4       Bukit Timah
+5       599489
+6       Northwest, Singapore
+Ngee Ann Polytechnic
+535 Clementi Road
+Bukit Timah
+599489
+Northwest, Singapore
+```
+
+variables
+
+- **variable `args.query`**
+
+  space-combined query given by user, comes from
+  [`argparse.ArgumentParser.parse_args`](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args)
+
+- **variable `squery`**
+
+  query split by comma
+
+  ```text
+  $ s+ 77Q4+7X Austin, Texas, USA
+       --------------------------
+       query
+
+  squery -> ['77Q4+7X', 'Austin', 'Texas', 'USA']
+  ```
+
+- **variables `pcode` and `locality`**
+
+  (_only shown if the query is a local code, not shown on full-length plus codes, 
+  latlong coordinates or string queries_)
+
+  represents the plus code and locality portions of a
+  [shortened plus code](https://en.wikipedia.org/wiki/Open_Location_Code#Common_usage_and_shortening)
+  (_referred to as a "short/local code" in the codebase_) respectively.
+
+- **variables `lat` and `lon`**
+
+  (_only shown if the query is a plus code_)
+
+  the latitude longitude coordinates derived from the plus code.
+
+- **variable `location`**
+
+  the response dictionary from the reverser passed to
+  [`surplus.surplus()`](#surplussurplus)
+
+- **variable `seen_names`**
+
+  a list of unique names/elements found in certain nominatim keys used in final output
+  lines 0-3.
+
+- **variables for seen name checks**
+
+  the variables come from a check to reduce repeated elements found in `seen_names`.
+
+  - **variable `d`**
+
+    current element in the iteration of the final output line 4 (general regional 
+    location) nominatim keys
+
+  - **variable `_dvmt4`**
+
+    list used in an `all()` check to see if the current nominatim key (variable `d`) can
+    be wholly found in any of the seen names, in the general regional location, or in 
+    the road name.
+
+    reasoning is, if the previous lines wholly state the general regional location of the
+    query, there is no need to restate it.
+
+    ```
+    # psuedocode
+    _dvtm4 = [
+        d != "",
+        d not in road,
+        d not in [output line 4 (general regional location) nominatim keys],
+        any(_dvcm4),
+    ]
+    ```
+
+  - **variable `_dvcm4`**
+
+    list used in an `any()` check to see if the current nominatim key (variable `d`) can
+    be wholly found in any of the seen names.
+
+    ```python
+    _dvcm4 = [True if (d not in sn) else False for sn in seen_names]
+    ```
+
+breakdown of each output line, accompanied by their nominatim key:
+
+```
+0       name of a place
+1       building name
+2       highway name
+3       block/house/building number, house name, road
+4       general regional location
+5       postal code
+6       general global information
+```
+
+0. **name of a place**
+
+   (_usually important places or landmarks_)
+
+   - examples
+
+     ```
+     The University of Queensland
+     Ngee Ann Polytechnic
+     Botanic Gardens
+     ```
+
+   - nominatim keys
+
+     ```
+     emergency, historic, military, natural, landuse, place, railway, man_made, 
+     aerialway, boundary, amenity, aeroway, club, craft, leisure, office, mountain_pass, 
+     shop, tourism, bridge, tunnel, waterway
+     ```
+
+1. **building name**
+
+   - examples
+
+     ```
+     Novena Square Office Tower A
+     Visitor Centre
+     ```
+
+   - nominatim keys
+
+     ```
+     building
+     ```
+
+2. **highway name**
+
+   - examples
+
+     ```
+     Marina Coastal Expressway
+     Lornie Highway
+     ```
+
+   - nominatim keys
+
+     ```
+     highway
+     ```
+
+3. **block/house/building number, house name, road**
+
+   - examples
+
+     ```
+     131 Toa Payoh Rise
+     535 Clementi Road
+     Macquarie Street
+     Braddell Road
+     ```
+
+   - nominatim keys
+
+     ```
+     house_number, house_name, road
+     ```
+
+4. **general regional location**
+
+   - examples
+
+     ```
+     St Lucia, Greater Brisbane
+     The Drag, Austin
+     Toa Payoh Crest
+     ```
+
+   - nominatim keys
+
+     ```
+     residential, neighbourhood, allotments, quarter, city_district, district, borough, 
+     suburb, subdivision, municipality, city, town, village
+     ```
+
+5. **postal code**
+
+   - examples
+
+     ```
+     310131
+     78705
+     4066
+     ```
+
+   - nominatim key
+
+     ```
+     postcode
+     ```
+
+6. **general global information**
+
+   - examples
+
+     ```
+     Travis County, Texas, United States
+     Southeast, Singapore
+     Queensland, Australia
+     ```
+
+   - nominatim keys
+
+     ```
+     region, county, state, state_district, country, continent
+     ```
+
+## api reference
+
+### `surplus.surplus()`
 
 pluscode to shareable text conversion function
 
@@ -113,7 +472,7 @@ pluscode to shareable text conversion function
 
 ---
 
-#### `surplus.parse_query()`
+### `surplus.parse_query()`
 
 function that parses a string Plus Code, local code or latlong into a str, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong) respectively
 
@@ -122,7 +481,7 @@ function that parses a string Plus Code, local code or latlong into a str, [`sur
     ```python
     def parse_query(
       query: str, debug: bool = False
-    ) -> tuple[Literal[True], str | Localcode | Latlong] | tuple[Literal[False], str]:
+    ) -> tuple[typing.Literal[True], str | Localcode | Latlong] | tuple[typing.Literal[False], str]:
     ```
 
 - arguments:
@@ -130,16 +489,14 @@ function that parses a string Plus Code, local code or latlong into a str, [`sur
   - `query: str`  
     string Plus Code, local code or latlong
 
-- returns `tuple[Literal[True], str | Localcode | Latlong] | tuple[Literal[False], str]`
+- returns `tuple[typing.Literal[True], str | Localcode | Latlong] | tuple[typing.Literal[False], str]`
 
   - `(True, <str | surplus.Localcode | surplus.Latlong>)`  
       conversion succeeded, second element is resultant Plus code string, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong)
   - `(False, <str>)`  
       conversion failed, second element is an error message string
 
----
-
-#### `surplus.handle_query()`
+### `surplus.handle_query()`
 
 function that gets returns a [surplus.Latlong](#surpluslatlong) from a Plus Code string, [`surplus.Localcode`](#surpluslocalcode) or [`surplus.Latlong`](#surpluslatlong) object.  
 used after [`surplus.parse_query()`](#surplusparse_query).
@@ -149,7 +506,7 @@ used after [`surplus.parse_query()`](#surplusparse_query).
     ```python
     def handle_query(
         query: str | Localcode | Latlong, debug: bool = False
-    ) -> tuple[Literal[True], Latlong] | tuple[Literal[False], str]:
+    ) -> tuple[typing.Literal[True], Latlong] | tuple[typing.Literal[False], str]:
     ```
 
 - arguments:
@@ -162,15 +519,13 @@ used after [`surplus.parse_query()`](#surplusparse_query).
     - [`surplus.Latlong`](#surpluslatlong)  
         latlong
 
-- returns `tuple[Literal[True], Latlong] | tuple[Literal[False], str]`  
+- returns `tuple[typing.Literal[True], Latlong] | tuple[typing.Literal[False], str]`  
   - `(True, <surplus.Latlong>)`  
     conversion succeeded, second element is a [`surplus.Latlong`](#surpluslatlong)
   - `(False, <str>)` 
     conversion failed, second element is an error message string
 
----
-
-#### `surplus.Localcode`
+### `surplus.Localcode`
 
 `typing.NamedTuple` representing short Plus Code with locality
 
@@ -181,9 +536,7 @@ used after [`surplus.parse_query()`](#surplusparse_query).
   - `locality: str`
       e.g.: `"Singapore"`
 
----
-
-##### `surplus.Localcode.full_length()`
+#### `surplus.Localcode.full_length()`
 
 method that calculates full-length Plus Code using locality
 
@@ -207,8 +560,6 @@ method that calculates full-length Plus Code using locality
   - `(False, <str>)`  
       conversion failed, second element is an error message string
 
----
-
 #### `surplus.Latlong`
 
 `typing.NamedTuple` representing a pair of latitude and longitude coordinates
@@ -220,35 +571,8 @@ method that calculates full-length Plus Code using locality
   - `long: float`  
       longitudinal coordinate
 
-## Developing
+## licence
 
-Prerequisites:
-
-- [Python >=3.10](https://www.python.org/)
-- [Poetry](https://python-poetry.org/)
-
-Alternatively, use [devbox](https://get.jetpack.io/devbox) for a hermetic development environment powered by [Nix](https://nixos.org/).
-
-```text
-devbox shell    # skip this if you aren't using devbox
-poetry install
-poetry shell
-```
-
-## The format is wrong/different!
-
-If surplus generates wrong text for a particular Plus Code,
-[submit an issue](https://github.com/markjoshwel/surplus/issues/new). 
-
-Ensure you detail the following:
-
-1. The erroneous Plus Code, local code or latlong, or a similar coordinate that reproduces the same error
-
-2. Output from the terminal, with `--debug` enabled or `debug=True`
-
-3. How it should look like instead
-
-## Licence
-
-surplus is free and unencumbered software released into the public domain.
-For more information, please refer to the [UNLICENCE](UNLICENCE), <http://unlicense.org/> or the Python module docstring.
+surplus is free and unencumbered software released into the public domain. for more
+information, please refer to the [UNLICENCE](/UNLICENCE), <https://unlicense.org>, or the
+python module docstring.