diff --git a/gel/_internal/arch.md b/gel/_internal/arch.md
index d866e67f1..88f935241 100644
--- a/gel/_internal/arch.md
+++ b/gel/_internal/arch.md
@@ -148,6 +148,83 @@ Run `python tools/gen_models.py` to generate test models into your virtual envir
      and you should be able to just run `$ pytest`.
 
 
+### Setup gotchas
+
+#### Using a system-wide `pytest` install
+
+Errors like `ModuleNotFoundError: No module named typing_inspection’` can
+occur when using a system wide pytest installation.
+
+This can be caused by having run either `pip install pytest` outside a venv
+or `apt install python3-pytest`.
+
+If you want to keep these installations, you can still run tests locally by
+running `python -m pytest`.
+
+#### `make clean && make` to fix binary incompatibilities
+
+Errors such as:
+```bash
+gel.protocol.protocol.ExecuteContext size changed, may indicate binary
+incompatibility. Expected 152 from C header, got 184 from PyObject
+```
+
+Indicate that a `pyx` file has changed. A clean rebuild is necessary.
+
+
+#### Fix `site-packages/gel.pth` to resolve wall of mypy test errors
+
+A large number of mypy errors such as:
+```
+RuntimeError: mypy check failed for test_modelgen_operators_integer_arithmetic 
+
+test code:
+...
+
+mypy stdout:
+models/__shapes__/std/net/__init__.py:14: error: Cannot find implementation or library stub for module named "gel.models.pydantic"  [import-not-found]
+models/__shapes__/std/net/__init__.py:17: error: Class cannot subclass "AnyEnum" (has type "Any")  [misc]
+models/__shapes__/std/net/__init__.py:22: error: Class cannot subclass "AnyEnum" (has type "Any")  [misc]
+models/__shapes__/std/enc.py:14: error: Cannot find implementation or library stub for module named "gel.models.pydantic"  [import-not-found]
+models/__shapes__/std/enc.py:17: error: Class cannot subclass "AnyEnum" (has type "Any")  [misc]
+models/__shapes__/sys/__init__.py:20: error: Cannot find implementation or library stub for module named "gel.models.pydantic"  [import-not-found]
+models/__shapes__/sys/__init__.py:53: error: Class cannot subclass "AnyEnum" (has type "Any")  [misc]
+models/__shapes__/sys/__init__.py:60: error: Class cannot subclass "AnyEnum" (has type "Any")  [misc]
+models/__shapes__/sys/__init__.py:65: error: Class cannot subclass "AnyEnum" (has type "Any")  [misc]
+models/__shapes__/sys/__init__.py:70: error: Class cannot subclass "AnyEnum" (has type "Any")  [misc]
+models/__shapes__/sys/__init__.py:75: error: Class cannot subclass "AnyEnum" (has type "Any")  [misc]
+models/__shapes__/sys/__init__.py:80: error: Class cannot subclass "AnyEnum" (has type "Any")  [misc]
+```
+
+Indicates the `site-packages/gel.pth` file is not set up correctly.
+Possible causes include:
+- missing the prerequisite step
+- changing the project directory name
+- etc.
+
+For a better understanding of why this error occurs, look at in `_testbase.py`
+for the functions `BaseModelTestCase.setUpClass()` and `_typecheck`. A test
+class annotated with `@tb.typecheck` will:
+- set up a temp directory with the pydantic model.
+- create a copy of test function in a dummy class
+- run mypy on this file in a subprocess
+- check the result code
+
+
+#### Other errors
+
+Some other errors that are caused by a weird environment, but more details are
+needed. If you see one of these, please note the steps used to fix them!
+
+```bash
+Traceback (most recent call last):
+  File "<string>", line 1, in <module>
+  File "/home/dnwpark/work/dev-3.12/edgedb-python/gel/__init__.py", line 32,
+  in <module>
+    from gel.datatypes.datatypes import Record, Set, Object, Array
+ImportError: cannot import name 'Record' from 'gel.datatypes.datatypes'
+```
+
 ### Running Tests
 
 ```bash