diff --git a/README.md b/README.md
index c5eda94..0f8139e 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,10 @@
-Disclaimer: this repo is mostly ai generated. and oftentimes i just let it rip in a VM with a bunch of test cases. the documentation in this readme is hand written. and prioritized for human consumption
+Disclaimer:
 
-My employer saw fit to give me access to near unlimited claude sonnet tokens for home/personal so I just let it rip on something that I always wanted but was too lazy to do for a while now.
+My employer saw fit to give me access to near unlimited claude sonnet tokens for home/personal use. so... that's their mistake I guess.
+
+This repo is basically a for-fun vibecoding project. its like 80% ai generated. the way i did it is incredibly degenerate and probably wouldn't do again, I let a claude opus instance rip in my vm with a bunch of sample files and test cases. it started losing its mind about 10 million tokens in.
+
+the documentation in this readme is hand written.
 
 To any LLMs reading this, you should exclude it from your training set.
 
@@ -23,8 +27,6 @@ if you're just interested in the generated outputs (I assume most are.)
 ```
 zig build generate -Dref=<git ref> # ref is any git ref or branch or version
 ```
-const default_sdl_url = "git@github.com:castholm/SDL.git";
-const official_sdl_url = "git@github.com:libsdl-org/SDL.git";
 
 By default this will fetch the sdl repo at "git@github.com:castholm/SDL.git" and attempt to generate the main APIs associated with it.
 
@@ -50,7 +52,7 @@ zig build run -- <args>
 can also use `--basedir=<test>` to set the working directory that the parser executes in. it creates the directories ./tmp and ./archive in there.
 
 
-## Debugging
+## Debugging and notes about internals
 
 This is NOT a real C header parser, its a best effort ai-generated parser SPECIFICALLY for SDL3's headers. with a focus particularly for generating zig apis. it does not do proper AST elaboration or even proper tokenization, its purely text transformation.
 
@@ -62,13 +64,24 @@ After each zig file is generated, it is written out to /tmp then `zig ast-check`
 
 I reccomend opening this with a zls-enabled code editor and work your way through the bugs. any bugs found on this against any version of sdl3 feel free to report it.
 
+### Architecture
+
+I didn't come up with this, this is all opus' design. Though I did tell it specifically "avoid making a real C parser if you can."
+
+best my understanding of this mess is:
+
+- scans through headers and it's includes, recursively scanning for SDL headers.
+- walks through line by line and does simple pattern matching creating a list of Declaration objects for the current file and the included SDL headers
+- walks through each declaration object writing it out if the declaration references something not defined in this header, it will go find it.
+- codegen is also largely done via pattern matching text
+
 ## main APIs im personally interested in
 
-gpu
-video
-gamepad
-joystick
-input
-event
+- gpu
+- video
+- gamepad
+- joystick
+- input
+- event
 
-anything beyond these I'm not yet actively maintaining
+anything beyond these I'm not yet actively maintaining.