diff --git a/README.md b/README.md
index fc16a50f1d3c17c05c75a06bdfed68244e210a72..fa5ae5b398a022f426cac06cbd78fb7f7ded13fc 100644
--- a/README.md
+++ b/README.md
@@ -1,87 +1,108 @@
 # Free Cities - pregmod
 
-## Common problems
-
- *  How do I start the game?
-    - Run the compile file, go to folder "bin", click the "FC_Pregmod" and play. (Recommendation: Drag it into incognito mode)
-
- *  I get an error on gamestart reading "Apologies! A fatal error has occurred. Aborting. Error: Unexpected token @ in JSON at position 0. Stack Trace: SyntaxError: Unexpected token @ in JSON at position 0 at JSON.parse (<anonymous>) at JSON.value" or some variant
-    - clear cookies
-
- *  Everything is broken!
-    - Do not copy over your existing download as it may leave old files behind, replace it entirely
+Pregmod is a modification of the original [Free Cities](https://freecitiesblog.blogspot.com/) created by FCdev.
 
- *  I can't save more than once or twice.
-    - Known issue caused by sugarcube level changes. Save to file doesn't have this problem and will likely avoid the first problem as well.
-    - It is possible to increase the memory utilized by your browser to delay this
+## Play the game
 
- *  I wish to report a sanityCheck issue.
-    - Great, however a large majority of the results are false positives coming from those specific sections being split over several lines in the name of readability and git grep's intentionally (http://git.661346.n2.nabble.com/bug-git-grep-P-and-multiline-mode-td7613900.html ) lacking support for multiline. An Attempt to add -Pzl (https://gitgud.io/pregmodfan/fc-pregmod/merge_requests/2108 ) created a sub condition black hole. What follows are examples of common false positives that can safely be ignored:
-```
-	[MissingClosingAngleBracket]src/art/vector/Generate_Stylesheet.tw:11:<<print "<style>."+_art_display_class+" {
-		<<print "<style>."+_art_display_class+" {
-	position: absolute;
-	height: 100%;
-	margin-left: auto;
-	margin-right: auto;
-	left: 0;
-	right: 0;
-	}
-```
+To play the game you have to download the sources first. You can either download an archive of the current state or, if
+you plan to keep up to date with current progress, clone the repository.
 
-## How to mod (basic doc):
+Clone the repo:
 
-1. All sources now in the src subdir, in separate files. 1 passage = 1 file.
+1. [Install Git for terminal](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) or a Git GUI of your choice.
+2. Clone the repo
+    * Via terminal: `git clone --single-branch https://gitgud.io/pregmodfan/fc-pregmod.git`
+3. Get updates
+    * Via terminal: `git pull`
 
-2. Special files and dir's:
-	- src/config		- configuration of the story is here.
-	- src/config/start.tw	- contains list of .tw passage files, regenerated automatic, by building scripts. Do not change by hands. (original passage Start from pregmod renamed and moved to src/events/intro/introSummary.tw)
-	- src/js/storyJS.tw		- special passage with [script] tag - contain all native JavaScript from pregmod.
-	- devTools/tweeGo/targets/sugarcube-2/userlib.js - on original FC JS moved here (I deleted it after moving JS to storyJS.tw). Compare to storyJS.tw but do not copy file here. May conflict with src/js/storyJS.tw if copied.
-	- src/pregmod		- I put all pregmod-only passages here.
-	- .gitignore		- special file for git - to ignore some files. For example - compilation results.
+Compile the game:
 
-3. Compilation:
+* Windows
+    * Run compile.bat
+    * Second run of compile.bat will overwrite without prompt
 
-	Windows:
-	Run compile.bat - result will be file bin/FC_pregmod.html
-	Second run of compile.but will overwrite bin/FC_pregmod.html without prompt.
+* Linux/Mac
+    1. Ensure executable permission on file `devTools/tweeGo/tweego` (not tweego.exe!)
+    2. Ensure executable permission on file `compile.sh`
+    3. In the root dir of sources (where you see src, devTools, bin...) run command `./compile.sh` from console. 
+        Alternatively, if you have make installed, run `make all` in the root directory.
 
-	Linux:
-	Ensure executable permission on file "devTools/tweeGo/tweego" (not tweego.exe!)
-	Ensure executable permission on file "compile.sh"
-	In the root dir of sources (where you see src, devTools, bin...) run command "./compile.sh" from console
-	Alternatively, if you have make installed, run "make all" in the root directory
+To play open FCpregmod.html in bin/ (Recommendation: Drag it into incognito mode)
 
-	Mac:
-	Not supported directly (I don't have access to Mac for testing).
-	But you can use linux compilation script if you download tweego for mac from here: https://bitbucket.org/tmedwards/tweego/downloads/ and replace linux executable with mac executable in ./devTools/tweeGo/ folder. This is not tested though, so be warned.
-
-4. Simple comparing and merging with original FC:
+## Common problems
 
-	Use meld tool. Place folder FreeCities (original FC sources tree) near FreeCitiesPregmod (this sources tree) and use command:
-	meld FreeCities FreeCitiesPregmod
-	or just select these folders in meld's GUI.
+* I get an error on gamestart reading `Apologies! A fatal error has occurred. Aborting. Error: Unexpected token @ in 
+    JSON at position 0. Stack Trace: SyntaxError: Unexpected token @ in JSON at position 0 at JSON.parse (<anonymous>)
+    at JSON.value` or some variant
+    - clear cookies
 
-5. All modders will be very grateful if anyone who makes some changes to game with .html file also post their resulting src folder tree.
+* Everything is broken!
+    - Do not copy over your existing download as it may leave old files behind, replace it entirely
 
-6. For contributors to pregmod: if you don't use git, then you need to post your version of src folder tree, not just produced FC_pregmod.html file!!! This html file can't be reverted to proper sources, and useless as contribution!
+* I can't save more than once or twice.
+    - Known issue caused by sugarcube level changes. Save to file doesn't have this problem and will likely avoid the first problem as well.
+    - It is possible to increase the memory utilized by your browser to delay this
 
-7. Git workflow:
-	- Master branch is pregmod-master. Only Pregmodder can add something to it directly. Always contain his last public changes.
-	- pregmod-dev - branch with experimental code mainly by pregmodfan.
-	- Any contributions will be placed in separate branches like pregmod-mod-<something> (if it's ready to merge with master complete feature/mod) or pregmod-contrib-<something> if it's partial work until contributions is reviewed.
+* I wish to report a sanityCheck issue.
+    - Great, however a large majority of the results are false positives coming from those specific sections being split
+      over several lines in the name of readability and git grep's 
+      [intentionally](http://git.661346.n2.nabble.com/bug-git-grep-P-and-multiline-mode-td7613900.html ) lacking support
+       for multiline. An Attempt to add -Pzl (https://gitgud.io/pregmodfan/fc-pregmod/merge_requests/2108 ) created a 
+       sub condition black hole. What follows are examples of common false positives that can safely be ignored:
+```
+[MissingClosingAngleBracket]src/art/vector/Generate_Stylesheet.tw:11:<<print "<style>."+_art_display_class+" {
+	<<print "<style>."+_art_display_class+" {
+position: absolute;
+height: 100%;
+margin-left: auto;
+margin-right: auto;
+left: 0;
+right: 0;
+}
+```
 
-	Typical cycle with git:
-	1. Make account on gitgud if you don't have usable one.
-	2. Fork main repository through gitgud interface. (Or pull changes from main repo if you already have fork.)
-	3. Clone your fork to local machine with git client (Or pull changes if already cloned.)
-	4. Make you changes as you like, commit, and push result into your forked repository (with git client).
-	5. (optional, but recommended) Run sanityCheck before final push to catch any errors you missed. (You can ignore errors unrelated to files you changed.)
-	6. Make merge request through gitgud interface.
+## Contribute
+
+First time setup:
+
+0. Follow the steps to clone the main repository if you haven't already.
+1. Create an account on gitgud if you don't have a usable one.
+    * (optional) Add an SSH key to your account for easier pushing. This allows you to connect to gitgud through SHH, 
+    which doesn't require your credentials every time.
+2. Fork the main repository through gitgud interface.
+    * (optional) Delete all branches other than pregmod-master, so you don't get them locally when fetching.
+3. Setup your fork as a remote
+    * (optional) Rename the main repository to upstream
+        * Via terminal: `git remote rename origin upstream`
+    * Add your repo as remote
+        * Via terminal: `git remote add origin <url-to-your-fork>`
+        * The big clone button in the gitgud interface on your fork gives you the relevant URLs.
+4. Checkout `pregmod-master`
+    * Via terminal: `git checkout pregmod-master`
+5. Make sure `fc-pregmod` tracks `upstream/master`
+    * Via terminal: `git branch -u upstream/pregmod-master`
+
+Typical cycle with Git:
+
+1. Get changes from upstream
+    * Via terminal: `git pull`
+    * If you don't get new commits from `upstream` repeat steps 4&5 of the setup.
+2. Checkout a new branch for your work
+    * Via terminal: `git checkout -b <branch-name>`
+3. Make your changes as you like
+4. Commit your changes
+    * Via terminal: `git commit <files>`
+    * Make the commit message useful (`Fix X`, `Add Y`, etc.)
+5. (optional, but recommended) Run sanityCheck before final push to catch any errors you missed. (You can ignore errors unrelated to files you changed.)
+6. Push result into your forked repository 
+    * Via terminal:
+        * Initially `git push -u origin <branch-name>`
+        * Afterwards `git push` will suffice.
+7. Create merge request through gitgud interface.
+8. Checkout `pregmod-master` in preparation of next change.
+9. Once the merge request was accepted, delete your local branch.
+    * Via terminal: `git branch -d <branch-name>`
 
 ## Submodules
 
-FC uses a modified version of SugarCube 2. It is integrated as a git submodule. If you are interested in modding SC2 this is a [good starting point](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for using submodules. Instructions to build SC2 can be found [here](devNotes/sugarcube stuff/building SugarCube.md). 
-
-When modifying SC2 make sure to open an MR here and at the [SC2 repo](https://gitgud.io/Arkerthan/sugarcube-2), so they stay in sync. 
+FC uses a modified version of SugarCube 2. More information can be found [here](devNotes/sugarcube stuff/building SugarCube.md).
diff --git a/devNotes/sugarcube stuff/building SugarCube.md b/devNotes/sugarcube stuff/building SugarCube.md
index 7fa138513bfa27c93b06882170ccf731557bb0e4..965fbc9c7627eeeedb14e90e2c085f8f8b8429d2 100644
--- a/devNotes/sugarcube stuff/building SugarCube.md	
+++ b/devNotes/sugarcube stuff/building SugarCube.md	
@@ -17,6 +17,58 @@ the PATH environment variable.
 
 ## Retrieving SugarCube sources and preparing build environment for it
 
+The SC2 sources are a git submodule.
+ 
+1. Get the sources: `git submodule update`
+
+2. Download required JavaScript libraries that are used during the build.
+    Run the node package manager (npm) in the repository: `npm install` or `npm update`.
+    * You need to navigate into `submodules/sugarcube-2` first.
+
+## Building 
+
+Run the build.js script. If you use Git bash, you can run the `build.js` file directly, otherwise run
+it as `node build.js`. See `build.js -h` for options, but reasonable sets are the following.
+
+* for release version: `node build.js -6 -b 2`
+* for debug version: `node build.js -6 -b 2 -u -d`
+
+Find result files in the `build` directory. After each build you have to copy `build/twine2/sugarcube-2/format.js` over
+to this directory and name it accordantly. The last step is to copy the release `format.js` to 
+`devTools/tweeGo/storyFormats/sugarcube-2`. Do not forget to `git add` all three files.
+
+Linux: If you have make installed, `make sugarcube` automatically builds and copies `format.js` to 
+`devTools/tweeGo/storyFormats/sugarcube-2` for easy testing.
+
+## Contributing
+
+1. Fork the [SC2 repo](https://gitgud.io/Arkerthan/sugarcube-2)
+2. Navigate into submodules/sugarcube-2
+    * Tip: Use two terminals, one in the main repo and one in the submodule.
+    * You are now in the root of the submodule. Git works here (almost) the same as in the root of a standalone repo.
+3. Add your fork as remote
+4. `git submodule update` leaves you in a detached head state, so checkout fc and pull recent changes
+5. Branch, modify, commit, push as usual.
+6. Build and replace the three relevant format.js (`devTools/...` and the two most recent in `devNotes/...`)
+7. Create a new patch `git diff master <your branch> > sugarcube-fc-changes.patch` and move it to `devNotes/sugarcube stuff/`.
+8. Commit and push in the main repo.
+9. Open an MR in the SC2 repo **AND** in the main repo. Mark the MR in the main repo as **WIP**.
+10. Once the MR in the SC2 repo is accepted do:
+    *  In the submodule 
+    1. `git checkout fc`
+    2. `git pull`
+    *  In the main repo
+    1. `git add submodules/sugarcube-2`
+    2. `git commit --amend --no-edit`
+    3. `git push -f`
+11. Remove WIP flag from main repo.
+
+Repeat steps 4 - 11.
+
+## (OLD) Retrieving SugarCube sources and preparing build environment for it
+
+Note: This is **NOT** recommended. Everything below is for documentation purposes only.
+
 1. Open a terminal window where you want to clone the repository, and run the following command: `git clone https://github.com/tmedwards/sugarcube-2.git`. Change working directory into the cloned repository.
 
 2. The last step we need is downloading required JavaScript libraries that are used during the build.
@@ -56,17 +108,6 @@ If the rebasing resulted in a conflict, you have to resolve it first. Issue `git
 
 Now you need to update the patch files in the FC repo. First, rename the old patch file: `git mv sugarcube-fc-changes.patch sugarcube-fc-changes-<the last version it applies to>.patch`. Now create an new patch and add it to the repository: `git diff master fc > sugarcube-fc-changes.patch`, copy it to this dir and `git add sugarcube-fc-changes.patch`.
 
-## Building
-
-Run the build.js script. If you use Git bash, you can run the `build.js` file directly, otherwise run
-it as `node build.js`. See `build.js -h` for options, but reasonable sets are the following.
-
-* for release version: `node build.js -6 -b 2`
-* for debug version: `node build.js -6 -b 2 -u -d`
-
-Find result files in the `build` directory. After each build you have to copy `build/twine2/sugarcube-2/format.js` over to this repo and name it accordantly. The last step is to copy the release `format.js` to `devTools/tweeGo/storyFormats/sugarcube-2`. Do not forget to `git add` all three files.
-
-
 ## APPENDIX Lists required steps very briefly
 
 1. Clone SugarCube repo: `git clone https://github.com/tmedwards/sugarcube-2.git`
diff --git a/submodules/sugarcube-2 b/submodules/sugarcube-2
index 813625f280aecab97e00eee3eb76acfbc2e15e5c..d6a74e05d5a2367355f52eddd2840d4e11510668 160000
--- a/submodules/sugarcube-2
+++ b/submodules/sugarcube-2
@@ -1 +1 @@
-Subproject commit 813625f280aecab97e00eee3eb76acfbc2e15e5c
+Subproject commit d6a74e05d5a2367355f52eddd2840d4e11510668