diff --git a/.github/workflows/code-coverage-deploy.yml b/.github/workflows/code-coverage-deploy.yml
index d70aacf8ff..3a0712bb9b 100644
--- a/.github/workflows/code-coverage-deploy.yml
+++ b/.github/workflows/code-coverage-deploy.yml
@@ -118,9 +118,9 @@ jobs:
 
       - name: "Generate indexes"
         run: |
-          ./etc/ci/genindex.py pages/coverage/${{ steps.sha.outputs.result }}
-          ./etc/ci/genindex.py pages/coverage/main
-          ./etc/ci/genindex.py pages/coverage/
+          ./tools/ci/genindex.py pages/coverage/${{ steps.sha.outputs.result }}
+          ./tools/ci/genindex.py pages/coverage/main
+          ./tools/ci/genindex.py pages/coverage/
 
       - uses: JamesIves/github-pages-deploy-action@v4
         with:
diff --git a/.github/workflows/code-coverage.yml b/.github/workflows/code-coverage.yml
index b1ad8ff3e1..49f259d3b2 100644
--- a/.github/workflows/code-coverage.yml
+++ b/.github/workflows/code-coverage.yml
@@ -63,7 +63,7 @@ jobs:
       - name: Generate coverage reports
         working-directory: .
         run: |
-          ./etc/scripts/gen_coverage_all.sh
+          ./tools/gen_coverage_all.sh
           
       - name: Move all html to correct folders for deployment
         run: |
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 1bd4324977..80b3e7625c 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -49,7 +49,7 @@ jobs:
       - name: Generate documentation
         working-directory: .
         run: |
-          ./etc/scripts/gen_docs.sh
+          ./tools/gen_docs.sh
           
       - name: Move all html to correct folders for deployment
         run: |
diff --git a/.gitmodules b/.gitmodules
index a4d5857e52..f1230f2f98 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,4 +1,4 @@
-[submodule "minion-bindings/vendor"]
+[submodule "solvers/minion/vendor"]
 	path = solvers/minion/vendor
 	url = https://github.com/minion/minion
   ignore = dirty
diff --git a/readme.md b/readme.md
index 61f6d944f6..85c8c4b2eb 100644
--- a/readme.md
+++ b/readme.md
@@ -1 +1,20 @@
-Stay tuned!
+# Conjure-Oxide
+
+This repository contains the in progress Conjure Oxide constraints modelling
+tool, and it's dependencies. 
+
+This repository hosts the following projects:
+
+* [Conjure Oxide](https://github.com/conjure-cp/conjure-oxide/tree/main/conjure_oxide)
+* [`minion_rs` - Rust bindings to Minion](https://github.com/conjure-cp/conjure-oxide/tree/main/solvers/minion)
+* [`chuffed_rs` - Rust bindings to Chuffed](https://github.com/conjure-cp/conjure-oxide/tree/main/solvers/chuffed)
+
+This project is being produced by staff and students of University of St
+Andrews, and is licenced under the [MPL 2.0](./LICENCE).
+
+## Contributing
+
+See the [Contributors Guide](https://github.com/conjure-cp/conjure-oxide/wiki/Contributing).
+
+<!-- vim: cc=80
+-->
diff --git a/solvers/chuffed/build.rs b/solvers/chuffed/build.rs
index a20e120d83..d0006c0a6e 100644
--- a/solvers/chuffed/build.rs
+++ b/solvers/chuffed/build.rs
@@ -8,15 +8,20 @@ use std::path::PathBuf;
 use std::process::Command;
 
 fn main() {
-    println!("cargo:rustc-rerun-if-changed=vendor");
+    let out_dir = env::var("OUT_DIR").unwrap();
+
+    println!("cargo:rerun-if-changed=vendor");
+    println!("cargo:rerun-if-changed=wrapper.h");
+    println!("cargo:rerun-if-changed=wrapper.cpp");
+
     println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo:rerun-if-changed=build.sh");
+
+    println!("cargo:rustc-link-search=all={}/", out_dir);
+    println!("cargo:rustc-link-search=all={}/build", out_dir);
 
-    // must be ./ to be recognised as relative path
-    // from project root
-    println!("cargo:rustc-link-search=all=./solvers/chuffed/vendor/build/");
     println!("cargo:rustc-link-lib=static=chuffed");
     println!("cargo:rustc-link-lib=static=chuffed_fzn");
-    println!("cargo:rustc-link-search=all=./solvers/chuffed/");
     println!("cargo:rustc-link-lib=static=wrapper");
 
     // also need to (dynamically) link to c++ stdlib
@@ -52,6 +57,7 @@ fn build() {
 }
 
 fn bind() {
+    let out_dir = env::var("OUT_DIR").unwrap();
     // The bindgen::Builder is the main entry point
     // to bindgen, and lets you build up options for
     // the resulting bindings.
@@ -78,7 +84,7 @@ fn bind() {
         .allowlist_function("p_setcallback")
         .allowlist_function("p_print")
         .allowlist_function("branch_IntVar")
-        .clang_arg("-Ivendor/build") // generated from configure.py
+        .clang_arg(format!("-I{}/build", out_dir))
         .clang_arg("-Ivendor")
         .clang_arg(r"--std=gnu++11")
         .clang_arg(r"-xc++")
diff --git a/solvers/chuffed/build.sh b/solvers/chuffed/build.sh
index 6615852803..8f3faddacb 100644
--- a/solvers/chuffed/build.sh
+++ b/solvers/chuffed/build.sh
@@ -1,17 +1,26 @@
 #!/bin/bash
 
-SCRIPT_DIR=$(dirname "$0")
+SCRIPT_DIR="$(readlink -f "$(dirname "$0")")"
+cd "$SCRIPT_DIR"
 
-git submodule init
-git submodule update
-cd "$SCRIPT_DIR" || exit
+git submodule init -- vendor
+git submodule sync -- vendor
+git submodule update --init --recursive -- vendor
+
+
+if [[ -z "$OUT_DIR" ]]; then
+  echo "OUT_DIR env variable does not exist - did you run this script through cargo build?"
+  exit 1
+fi
 
 echo "------ BUILDING ------"
-cd vendor || exit
-cmake -B build -S .
-cmake --build build
-cd ..
+
+mkdir -p "$OUT_DIR/build"
+cd "$OUT_DIR/build"
+cmake -B . -S "$SCRIPT_DIR/vendor"
+cmake --build .
 
 # Build wrapper.cpp as static library
-c++ -c wrapper.cpp -Ivendor --std=c++11
+cd "$OUT_DIR" || exit 1
+c++ -c "$SCRIPT_DIR/wrapper.cpp" -I"$SCRIPT_DIR/vendor" --std=c++11
 ar rvs libwrapper.a wrapper.o
diff --git a/solvers/chuffed/clean.sh b/solvers/chuffed/clean.sh
deleted file mode 100755
index 2873cb0737..0000000000
--- a/solvers/chuffed/clean.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/bin/bash
-
-cargo clean
-rm -rf vendor/build
-rm libwrapper.a
-rm wrapper.o
diff --git a/solvers/minion/build.rs b/solvers/minion/build.rs
index b43de719dc..700704c829 100755
--- a/solvers/minion/build.rs
+++ b/solvers/minion/build.rs
@@ -11,12 +11,13 @@ use std::path::PathBuf;
 use std::process::Command;
 
 fn main() {
-    println!("cargo:rustc-rerun-if-changed=vendor");
+    let out_dir = env::var("OUT_DIR").unwrap();
+
+    println!("cargo:rerun-if-changed=vendor");
     println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo:rerun-if-changed=build.sh");
 
-    // must be ./ to be recognised as relative path
-    // from project root
-    println!("cargo:rustc-link-search=all=./solvers/minion/vendor/build/");
+    println!("cargo:rustc-link-search=all={}/build", out_dir);
     println!("cargo:rustc-link-lib=static=minion");
 
     // also need to (dynamically) link to c++ stdlib
@@ -54,6 +55,7 @@ fn build() {
 }
 
 fn bind() {
+    let out_dir = env::var("OUT_DIR").unwrap();
     // The bindgen::Builder is the main entry point
     // to bindgen, and lets you build up options for
     // the resulting bindings.
@@ -94,7 +96,7 @@ fn bind() {
         .allowlist_function("vec_int_new")
         .allowlist_function("vec_int_push_back")
         .allowlist_function("vec_int_free")
-        .clang_arg("-Ivendor/build/src/") // generated from configure.py
+        .clang_arg(format!("-I{}/build/src/", out_dir)) // generated from configure.py
         .clang_arg("-Ivendor/minion/")
         .clang_arg("-DLIBMINION")
         .clang_arg(r"--std=gnu++11")
diff --git a/solvers/minion/build.sh b/solvers/minion/build.sh
index 2bac9d9ef8..dab86d3105 100755
--- a/solvers/minion/build.sh
+++ b/solvers/minion/build.sh
@@ -1,23 +1,23 @@
 #!/bin/bash
 
-SCRIPT_DIR=$(dirname "$0")
-
-git submodule init
-git submodule update
+SCRIPT_DIR="$(readlink -f "$(dirname "$0")")"
 cd "$SCRIPT_DIR"
 
-echo "------ CONFIGURE STEP ------"
+git submodule init -- vendor
+git submodule sync -- vendor 
+git submodule update --init --recursive -- vendor
 
-if [ -d vendor/build ]; then
-  echo "vendor/build already exists; skipping"
-  echo "if you need to reconfigure minion (such as after an update), delete this directory!"
-else
-  mkdir -p vendor/build
-  cd vendor/build
-  python3 ../configure.py --lib --quick
+if [[ -z "$OUT_DIR" ]]; then
+  echo "OUT_DIR env variable does not exist - did you run this script through cargo build?"
+  exit 1
 fi
 
+echo "------ CONFIGURE STEP ------"
+
+mkdir -p "$OUT_DIR/build"
+cd "$OUT_DIR/build"
+python3 "$SCRIPT_DIR/vendor/configure.py" --lib --quick
+
 echo "------ BUILD STEP ------"
-cd "$SCRIPT_DIR"
-cd vendor/build
+cd "$OUT_DIR/build"
 make
diff --git a/etc/ci/genindex.py b/tools/ci/genindex.py
similarity index 100%
rename from etc/ci/genindex.py
rename to tools/ci/genindex.py
diff --git a/etc/ci/get_submodules_hash.sh b/tools/ci/get_submodules_hash.sh
similarity index 87%
rename from etc/ci/get_submodules_hash.sh
rename to tools/ci/get_submodules_hash.sh
index fa5aed8526..6c53d8a0be 100755
--- a/etc/ci/get_submodules_hash.sh
+++ b/tools/ci/get_submodules_hash.sh
@@ -14,7 +14,7 @@ cd $(git rev-parse --show-toplevel)
 git submodule update --init --recursive 1>&2 2>/dev/null
 
 { 
-  for module in $(sh "$CI_SCRIPTS_DIR/get_submodule_paths.sh")
+  for module in $(sh "$CI_SCRIPTS_DIR/../scripts/get_submodule_paths.sh")
   do
     git rev-parse "HEAD:$module" >> $SHAS
   done;
diff --git a/etc/scripts/gen_coverage.sh b/tools/gen_coverage.sh
similarity index 100%
rename from etc/scripts/gen_coverage.sh
rename to tools/gen_coverage.sh
diff --git a/etc/scripts/gen_coverage_all.sh b/tools/gen_coverage_all.sh
similarity index 94%
rename from etc/scripts/gen_coverage_all.sh
rename to tools/gen_coverage_all.sh
index 3e86503c43..bd87428de6 100755
--- a/etc/scripts/gen_coverage_all.sh
+++ b/tools/gen_coverage_all.sh
@@ -1,7 +1,7 @@
 # !/bin/bash
 # generate coverage for all crates in the workspace
 
-PATH_TO_GEN_COV="/etc/scripts/gen_coverage.sh"
+PATH_TO_GEN_COV="tools/gen_coverage.sh"
 echo_err () {
   echo "$@" 1>&2
 }
diff --git a/etc/scripts/gen_docs.sh b/tools/gen_docs.sh
similarity index 100%
rename from etc/scripts/gen_docs.sh
rename to tools/gen_docs.sh
diff --git a/etc/ci/get_submodule_paths.sh b/tools/plumbing/get_submodule_paths.sh
similarity index 81%
rename from etc/ci/get_submodule_paths.sh
rename to tools/plumbing/get_submodule_paths.sh
index b796b17481..a452ad591a 100755
--- a/etc/ci/get_submodule_paths.sh
+++ b/tools/plumbing/get_submodule_paths.sh
@@ -6,7 +6,7 @@
 # these paths are relative to the git repository.
 
 # go to top level of git repo
-cd $(git rev-parse --show-toplevel)
+cd $(git rev-parse --show-superproject-working-tree --show-toplevel | head -n 1)
 
 # https://stackoverflow.com/questions/12641469/list-submodules-in-a-git-repository
 git config --file .gitmodules --get-regexp path | awk '{print $2}'
diff --git a/tools/update-submodules.sh b/tools/update-submodules.sh
new file mode 100755
index 0000000000..68e9f2235e
--- /dev/null
+++ b/tools/update-submodules.sh
@@ -0,0 +1,28 @@
+#!/bin/bash
+# vim: cc=80
+
+# root of project
+cd $(dirname "$0")/..
+
+# update, initialise, and sync all submodules to ensure that changes are 
+# reflected here. `git submodule sync` means change where the submodule points 
+# to match .gitmodules, should it have changed (in particular, from a dev fork
+# to upstream).
+
+echo "=== Cleaning submodules ===" 1>&2
+
+bash ./tools/plumbing/get_submodule_paths.sh | 
+  {
+  while read -r submodule_path; do
+    cd "$submodule_path"
+    git clean -dfx .
+    cd - &> /dev/null
+  done 
+}
+
+echo "=== Updating and resetting submodules ===" 1>&2
+
+git submodule init --recursive
+git submodule sync --recursive
+git submodule update --init --recursive
+