diff --git a/images/docs/idkit-flow.svg b/images/docs/idkit-flow.svg
new file mode 100644
index 0000000..fbe44cf
--- /dev/null
+++ b/images/docs/idkit-flow.svg
@@ -0,0 +1,5 @@
+
+
+eyJ2ZXJzaW9uIjoiMSIsImVuY29kaW5nIjoiYnN0cmluZyIsImNvbXByZXNzZWQiOnRydWUsImVuY29kZWQiOiJ4nO1dWVfbyFx1MDAxMn6fX8Hhvo51u7t6nTd2s5qwXHUwMDA1mJnDkW1cdTAwMTlcdTAwMGJky8g22z3577faLJK12MZcdTAwMTjGyUByclx1MDAxMi2tUnd9VV9VVyn/+21hYbH30PFcdTAwMTb/WFj07mtu4Ncj927xd3v81ou6ftjGU2zw727Yj2qDK5u9Xqf7x3//XHUwMDFi3+HUwtbTXV7gtbx2r4vX/Yn/Xlj43+DPxHNcIq/Wc9uXgTe4YXAq8ShCIX14L2xcdTAwMGaeSzlnWoGmr1x1MDAxN/jtundvx6xWXHUwMDFl49H87ipK0fPqeKbhXHUwMDA2XS8+Y1x1MDAwZi2u3PZXNjeCx4hcdTAwMWPf8N3NXHUwMDBi3q5dPMS3N/wgOOw9XHUwMDA0XHUwMDAzYbshvmB8rtuLwmvvu1/vNa1AqeNFd0Vh/7LZ9rrdoXvCjlvze1x1MDAwZvZcdTAwMTghr0efZuaPhfiIfUGmXHUwMDE0dSQnXHUwMDAwWjOmQLyetfeXXGaVXHUwMDBlkZKBXCLEKKlVSrCVMFxiIyvYf8jgJ1x1MDAxNq3q1q4vUb52Pb6m5tV53Y2vuXt5XcpcdTAwMWPQhFx1MDAxYco1kZQp/npJ0/Mvmz17XHLKqVx1MDAxNeGGSSG1NFwiIYo3WFx1MDAxMcGpXCJCJJbZPr+zWY9V5unFdtZKx3vdtT3d2u7XtepcdTAwMWN73/mrUHjBpn9/vNPRZd/4S3v7lbXjlVp7Z/H5/N/xckZuy9u0T273gyC5Ju3685pcZp2o2lx1MDAxM2tpLU5qckKVjs/q1F2DVuWqWl9dZ5VHXHUwMDFhyp2EkFx0tXejKLxbfD3zIyNov1N3n5SWKqWk1IThisfzXHUwMDE3+O3rtLBBWLuO9Xxw9Mfv08COJlx1MDAxNipccjtcdTAwMDJUac2VyMHdPplcdTAwMWN3jZ39iJnW/cbZWcecXHUwMDFjXGKiTZPNO+40d1x1MDAwNEJcdTAwMGJcdTAwMDSAlCSNO8JcdTAwMWMjXHUwMDExj1RcdTAwMWHJXHJ5XHUwMDFm7lx1MDAxYY1GXHUwMDE2dFo7QjBKKSdGXHUwMDAyMXmYXHUwMDAz6nBEXHUwMDFjwVx0lUowmcFcdTAwMWNcdTAwMTcgtCGE/iyYK0aFUoZcdTAwMThtZoVcbi9cYvxON1x1MDAxZlx1MDAxMywxX1x1MDAxOUxoKXDV8zFBJ8dE+bHsnn6HXHUwMDAzb3P1zPdaXHUwMDFie2V+tTPnmNDUOIpcbiqkMFrhRFxmg0JJ4WitiTBUMKK0mD0oqHYoICzxMajukuWBovCSZ0xcdTAwMTjG0YMhqr4wkcLESE9BNdeFqNDoR1BcdTAwMTCVx9D22eSoeNThmXuoS/ewro6bWydnPVWTXHUwMDA1qKhFYbdbarq9WnNcdTAwMGWwoYxCnia0JEoyLfQwNLSWXHUwMDBlY8YozihwljDmU0HDrVx1MDAxMlwisuiQzEGXZL2VUJRcdC6z6ECPIdCbWFx0KZXAjE7Dg1x1MDAwYmZcdTAwMDRcdTAwMTfyXHUwMDBiXHUwMDFlb4SHIUXwYIRcdTAwMTEkzoRDXHUwMDFlPGByeNx21781ljsnW9WVIDi5Wr7zutf0V4BcdTAwMDczXHUwMDBlsl7UWrxEcZpcdTAwMTZsjuCBLoVKNIVf8EjDo+fd9/KQoVmx32CKalxu+W6DT46LpUpzU19U25XaRv/i6nxn++5y56hcdTAwMDBcdTAwMTdNt9bsR15cdTAwMTEm2CdiQoBDXHUwMDE00ndBUflRK1N0iilcdTAwMDfDQPytXHKS/LRgsb5Tz/5cdTAwMWHHpryaMTmEiivHoG1cdTAwMDKkdKhcdTAwMTFGZTGhSFx1MDAxYVx1MDAwM8ogTIUx41wi+Z9RxWOpwnbv0H9cdTAwMWPYbz10dN1t+YFdonjBXHUwMDA2uo/zfFx1MDAxNvajhaVO56/2d7/XXFzYXFzd9lx1MDAxM5iwVy1cdTAwMDX+ZXtgn1F6L1x1MDAxYVx1MDAwMkzPr7nB61x1MDAwNb2wXHUwMDEzn63hc12/7UXZeVxuI//Sb7vB0UQyuP1eeOB1n16sXHUwMDE39b3k3HjlV1x1MDAxNu0wMb0zZMSY9OFXzFx1MDAxYmpcZuVcZvJcIqjTN4C+tSu+VU+OaOm4sX78XHUwMDEwRObgpupcdTAwMTWAfk5cIihgQjroPdCvKPwtYkw/Z/OMNVxiQKhcdTAwMDZDXHUwMDExke9yg1x1MDAxZpvNs0vMNWg5LrVwXHUwMDE4rN97RyvR3pkqXHTPO19cdTAwMDa9fJ90hLBea1x1MDAwNNK9Oj5fbq6Wy9F2//D2+nOthFx1MDAxMUjOSVx1MDAxMlx0XHUwMDFml3DD6LNcdTAwMThcdTAwMWFcdTAwMWFcdFxuWvw8nngqJofG8Xrtxj1aWtk566xcdTAwMWQ+XpVVfXurOu/QkMZcdTAwMTGCXGIjgDLJ0tAgwjFKKCNcdTAwMDVcdTAwMTNcdTAwMWHR8z6G+GFcdDfKwEiD8fA4fvhTwFx1MDAwMm2DmFlcdTAwMWV6ZMZNy1wiUGicUU1cdTAwMTnN44incnJMuLVL8rB+0Fs/v4D7S3rY/ra0NudJaFx1MDAwMMJcdTAwMWQlXGaGXCJCobHmmYSbdlxmoXQwQ1xciVx1MDAwZshCz1wi4UatKlx1MDAxMVx1MDAwMmMzbv8+TIxOKVx1MDAxOCjcXHUwMDEylYZxme8n1OSY8Fx1MDAxZq83ut/NaWW7dOTvwJG8bZT1z5BPXHUwMDAwplx1MDAxOVx1MDAxMin0l0RcdTAwMDG6XHUwMDAzOVxmXGatjcM4XHUwMDEwMITjlVK+XHUwMDBmXHUwMDE4XHUwMDFmmU9QioA0Sv9cdTAwMTI06jOxkdiByaTbQGlm9yHy4KEnh8f6Q+2Y3TSkXHUwMDFi6fPd4851LVrvbf9cbvBcdTAwMDDmaIqKKZnWXHUwMDE0NMwvPCiGQ1pQMzbf9u/DR1G+zVx1MDAwMC9CXHUwMDA2zjFcdTAwMTBNjMiNvc1cdTAwMWKQscXWXHUwMDBl72py97R3eHV22t6qdNuiXHUwMDAwXHUwMDE5c5NwXHUwMDAzxoUjOXJJ1DnAMDzFpoA4nFx1MDAxMa6YQt9BzVx1MDAwNyXcXHUwMDEwe4ZzXHUwMDAx6J4oUjadg1xukUZcdTAwMDFcdTAwMTOSYNwx1kn8jDpcdTAwMWVLNU3C7XtcdTAwMThcdTAwMDV1m+367CxbzoPfm1p7gtba3dZ15WHjuH6iRHi45Ncjf3Uv8XZDVUVD+s1cZpGOpMZwXGZcdTAwMTcgsVxiT0ZfgEMxrqaogWhuXHUwMDEzZPxFNVx1MDAwMZQj0NwqiT5cdTAwMDHttcmqJrHbNFx1MDAxOKxJblN4KrmRmcXcLGAzeVj2XHUwMDExdiSJsrHwSVjS8mIuqOI6spdlZM9HfqRcdTAwMTGPTpGikYBMXHUwMDFhXHUwMDE1z+nC3KqWjEhcXJdcdOz4hNVuuc4moa3bu6biVq5uWo+3XHUwMDA3eyd7Z/dX3fLjm4rdKCqUoEmoTGowOqGflv3PhIQkKS55/fvfv+deXaj8g7szalx1MDAxZlx1MDAwZpd5w27PjXrLqFxyfvsy/SZeu15wZnDXklx1MDAwNXXTczO6hfclz6XR71x1MDAwNdXwblxmbVx1MDAxOLVeXHUwMDE56zLMLZ6Mi+JoXFwkV4pcdTAwMDHQXGalVMRhklx1MDAxMqlcdLH5iNguvFhcdTAwMTdGqCNcdNGUa1x1MDAxYtiKvPxawvN9mZPYnGzmm5Nh/Xm2XHUwMDFiqKZcdTAwMWFcdE4mOLKvVJx4xtWQlFxunkiyTWw5hsSYIbxfXFz8flx1MDAxNIaNhVx1MDAwM++m73VcdTAwMTNK+Wa6MDknaPn1ejLsXHUwMDFjplx1MDAwNeM8dJopXHUwMDE0yD9cdTAwMWK2sCVcdTAwMWZcdTAwMGVuXGI5vtp7OLlcdTAwMGY2OyV1T9REbFx1MDAwMVlcdTAwMDBFQmDDL4WAZik2jOGzQ22do5GGiWTpyitdkFxiaFx0XG6JtFx1MDAxMVx1MDAxY/lpXHUwMDFlXeCA0bigXHUwMDAyXHUwMDA0hqTJUb7wXHUwMDFk43vr3XRBcZCGXGKeS1x1MDAxN4phzzWnXHUwMDE4XHUwMDEw0mlgPyVhOFxyzjZcdTAwMWGl67qCm/3woLZRqt7v9N9IXHUwMDE4qFx1MDAxMDyJln+EMJRcbvV/cDar+j8rZchfsVx0KFx1MDAwM1x1MDAxMLQhSEhxXG4o4ULG4H8u+mKOXHUwMDA2hovK0MQkw/E4VkZSIaRcdTAwMDCCrExRnUj5fVGGMSblZHLOgNMsyKCuO8d60MJkXHUwMDEyZ2CLvclHcIZpXHUwMDEx/sJcdTAwMTnOt1x1MDAxN1x1MDAwNm53XHUwMDFl6MJcdTAwMThcdTAwMTedplx1MDAwYlnRZ1WyM2pcdTAwMDOWiMKtJlx1MDAwYlGpZLJ4dUx28Lr82L9TusZqO61LMP7lUeW0P1xyomaVMVx1MDAxZptcdTAwMTlEhXOkZtLuXHUwMDFioKVKpU4woJFcdTAwMGUwrqVlSlx1MDAxOFx1MDAwNFx1MDAxNifMJ7AwvchtdztuhGqVTVx1MDAwZlwiWXaYsXzcSEWAJbrlXk3eiGted1xcObd1XGZcdTAwMTC/SH7CcN1vnrn7cvNKrV1vlDdXXHUwMDBmNjpcdTAwMWKtT26l81b4XHUwMDE27Z92r+5qO1x1MDAxN5F/XHUwMDA2rLa8MkxcdTAwMWTe0UrHXHUwMDE18KnCj4QxPVhcdTAwMWOJK4vCXFxQQXHHhFBcdTAwMTJcdTAwMTePUzMxqDaCoHRCz6u360erjWB5q3x6SsI5r18gSjma2bJcdTAwMWRcIjlcdTAwMTEsxVx1MDAwMChcdTAwMGXhUKFAXHRcdTAwMThsXHUwMDExXHUwMDE1t0W8XHUwMDE3V5RzR2gyaMFcdTAwMDBha12zuLLSIJ5sqYUguHgsk4fXXG5cdTAwMTB2NHHio2E1SVxm8Ib0/DvwMFx1MDAxZEdcctxubyVstfxcdTAwMWWKsW/597tY7NC5mdJ5SsAxRlrdXHUwMDEwQlx1MDAxYlBDXHTAXHUwMDEydVxiiXWDScrGXHUwMDBlyMCxfevM2O5cdTAwMGaqyHB8gOSXXG6utORow1x1MDAwNeVm3HhGO1xiJ7x+XHUwMDEwUYi41XswnCBcdTAwMGXGXHUwMDFhSivUWlxm241cdTAwMWE7nHEwctGSYvRcdTAwMDdcXDA5NFx1MDAxY+LWtmvjYeCoNCDHXHKntCOBgqFcdTAwMDTHJCzOPz3NXlx1MDAwNlnjxuPGIYDLwIjlXHUwMDFlLN6MXHUwMDFijGekI5XgQLWQXGb98tjJXHUwMDAzhYFcYjVcdTAwMTjvKkaYijnrYDhNXHUwMDFjYbtSXGbyWYwykqFa/nCMWFx1MDAwN2wwJDGAIVxmmoXh8YSDY6H8KJw0Y4VTjiQomuHSPlx1MDAxZPjwuyo0XFw2qy9wOqhCMva+4YRtKkBlR2PAJVx1MDAwMOrSuPFw9Vx1MDAxY1uxjXOnXHUwMDA0ciRqhnVFgFx1MDAwM4rZ5ylcIlx1MDAxOZr5sVx1MDAwMzLqUFBcXFx1MDAxMcVcdTAwMTgqrIRhaFx1MDAwMNJcdTAwMWIurVx1MDAxZVx1MDAxYnwgXHUwMDFkv7olqm1q2XbXXHUwMDAxvrR9qWH1o1x1MDAxNjqA2lx1MDAwNFx1MDAxNjqKj1x1MDAxNbHIdmRMeIIlXHUwMDFjLiYsU/BwOeBcdTAwMDDTb+NcdTAwMDMxhV3I6E5cdTAwMTGzQ30zY9jDt5VvleiiXHLRt8OwdSi7XHUwMDA317DamHf2gFZDXHUwMDEyQH81KG+kaVZOtDVcdTAwMDO44spIYnfUP46VXHUwMDBi5lx1MDAxMKlccj5cdTAwMTGBgFqek4jg2mFg0IooxD3GxYmas+e+Y4lcdTAwMTZcdTAwMGIoXHUwMDFmt4lcdTAwMWaFR+xcdTAwMDFOztrfLr+X1suPd7tcdTAwMDdXXHUwMDA3yUpcdTAwMTZcdTAwMDFLXHUwMDE3W0DctVrpqn8nxe65emTJXHUwMDBi5oHVf+xcdTAwMDcypmYxiTRcdTAwMDBotNKUW7uP9lx1MDAxMn/k0FWvaYH4OUNdPsuoQ8hO/pHunsyzM4mAhKp3vUGAYlx1MDAwYnXzzNbRiETDSMM1Mp2giz/mQ1x1MDAwMfHMOUyyS/2kS1dcdTAwMGYrbGPpbrt/XHUwMDBlN2RNt0T5ZmljrvNcdOjbXHUwMDA2gY20XHJcdTAwMWRGpPZWkFx1MDAxYaJHXHUwMDAyTtBb2uJPKP5SwnzkXHUwMDEz8JBBXG5Axnb83fqbrVO/zlfD2sNSq9sqqahcdTAwMTH9UvlcdTAwMDStSFwijJ0un3A+bT5BXHUwMDE1d9JiZEqMSDZwjq3hq7b3Ny/EUk2K6qnZu/aWVdJizSUlXHUwMDEwwFx1MDAxY7DxlyG2gs6kgYWG3NFSikHcIJTWXHUwMDFmXHUwMDA2rHRCIadxdnw+gVxuXGYqNbKbz8PVzFx1MDAxM1xuU1x1MDAwM+IrofCVUChcdTAwMWXuK6GQXHUwMDFj7yuhMHLAXzOh4M44oYAxdGFCQWiMs5P1I+PYQ6V0vnPRiZrrlWr/5HEn2tuB2vWcs1x1MDAwN44wXHUwMDEzg05Fhlx1MDAxNjTRXHUwMDFl9JJPoFx1MDAwZSBhRz1G7qBUcdfYe8lcdTAwMDNYhWUgjKSF+Vx1MDAwNDRJaM3tJ3FQ0yRNflx1MDAxM+elKYBcblRoXHUwMDE4x1x1MDAxZMrls4vzK31TXa/3ujft5tHd0W6yNGexsu3e9juCrN6oysVDlZdafmIpP5HVf1xizZhJxP9U7b+5+ld71bv1grDjRVx1MDAwYvth1HODf6bvYLQk78hcdTAwMDZU35pccpgk2zOyaUFzgoqOfMV+I0qTXHUwMDE0ozfMtojFXHUwMDFmuFx1MDAxNVx1MDAxOSwxIVx1MDAxY4XsSqPx54KynK5cdTAwMDVcdTAwMDSPXHUwMDAzVodcdTAwMDSjjHxVIeaXXGbV3l2FyFx1MDAxOC6VViyvjkhcdTAwMTcms1x1MDAxMYbK+p9ET9pHXHUwMDE3IVx1MDAxZeyt+Huef9fuXFy36lx1MDAwN7C/dn96f/RJXHUwMDE5yJlcdTAwMDZcdTAwMTmFym9/Slx1MDAxOb1cdTAwMWbBO1LRWGLVnz/s/VTMNPpcdTAwMTPaeHUrrFx1MDAwZqY+jKr+kJdp+PdxwDb0xo4gw/w5y49iVVx1MDAxYopcZoukXHUwMDFjvdsxpZRcdTAwMTLjXHJcZuMw8LKBh0o1iFxmn1x1MDAwNTPiXHUwMDE1Zlm3+Xq8XHUwMDE13nq7/pPoXfvhp2eUjKSMo9CQMd45PSGaI0+2X9hiXHUwMDE0g6pcdTAwMTSfMpo7aL7R3XLQXHUwMDAySNZ0f9V3Tm2s6/nGOre8U2JAxEReaXhxcSfaXHUwMDBijG5kcklmVd1JXHUwMDAwjIzn8iev7lx1MDAxY8N8Pr66c5Kk9+g+XHUwMDEwzlx1MDAxY2qYTbVIXG4s1dhFKbpcdTAwMThcZjNcZlx1MDAxM/Y/YSB5nV1cXDnoxFFhpFRoXHUwMDA1SW4nXGJGVlx1MDAxOPLY5Fxu2I8rfeE6XHUwMDE31967SZgm1Fx1MDAxYV2S2YBcdTAwMWJcdTAwMTjcws8sUaKQ04jkf1x1MDAwN/DhNGyjfPu41NzchaWL49Wm5/GLjYh80nbMbGlYIVx1MDAwMuxPKUf538/ERlx1MDAxN1nPiokhf8Q5Vtp+lU5wZWRG8DdSs9F7uVx0sf121697XHUwMDEzyk205IpIZWtJmTbpd1x1MDAwMG6oNEJqNGSK/kzcLFx1MDAxZlwiXHUwMDEzcDNgmjrafneaMcVookvj2axcdTAwMWJwgEjCcOaQwCUqlV/MurLZXHUwMDEym4PnSorcXHUwMDE0lVx1MDAxYZVx+/fa8Mbk3FxmzTTOvUl+jWGifl3kytp+XHUwMDE471x1MDAwM9hcdTAwMTn+XHRTfb/jhZ2deJHfePirPTdcdTAwMTRtXGY3SlO0XHUwMDAy+d/M0357NuqLbqdz2MNZfrWKi7e+d7ec/1x0PvtcdTAwMTW+356tgdV/b+D+f/z24//dvrDDIn0= Your App With IDKit World App Proof Request ZK Proof Your Backend World ID Developer Portal ZK Proof Verify Proof
\ No newline at end of file
diff --git a/world-id/idkit/integrate.mdx b/world-id/idkit/integrate.mdx
index a4be0cd..0c15147 100644
--- a/world-id/idkit/integrate.mdx
+++ b/world-id/idkit/integrate.mdx
@@ -1,17 +1,27 @@
---
-title: "Integrate"
+title: "IDKit"
+sidebarTitle: "Integrate"
+description: "Integrate World ID into your app"
"og:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png"
"twitter:image": "https://raw.githubusercontent.com/worldcoin/developer-docs/main/images/docs/docs-meta.png"
---
import IDKitResponse from "/snippets/idkit-response.mdx";
-IDKit is our solution for integrating World ID. You can use the React SDK for a pre-built widget or the JS and mobile SDKs for a custom integration.
+IDKit is the SDK for integrating World ID into your app. It handles proof requests, verification flows, and communication with the World App — so your backend receives a cryptographic proof of human, not personal data.
-To familiarize yourself with the core concepts of World ID, check out this [page](/world-id/concepts).
+It's available as a React widget for drop-in integration, or as JS, Swift, and Kotlin SDKs for custom flows. To familiarize yourself with the core concepts of World ID, check out this [page](/world-id/concepts).
> Tip: To integrate faster, give your coding agent the [Build with LLMs prompt](/world-id/idkit/build-with-llms) — copy it once, paste into Claude, Cursor, or any AI coding assistant.
+## How it works
+
+Your app sends a **proof request** through IDKit, challenging the user to prove something about themselves — such as uniqueness, document possession, or liveness — based on their [credentials](/world-id/overview#credentials). The user's World App generates a zero-knowledge proof without revealing any personal data. Your backend then verifies that proof and stores a **nullifier** (a per-app, per-action identifier) to prevent the same person from verifying twice.
+
+
+
+There are four components: your **client** (where IDKit runs), your **backend** (which signs requests and verifies proofs), the **World App** (on the user's device), and the **Developer Portal** (which validates proofs on-chain). The steps below walk through each piece.
+
# Step 1: Install IDKit
Make sure you're using the latest `4.x` version.
@@ -341,7 +351,7 @@ CREATE TABLE nullifiers (
```
-## Architecture overview
+## Architecture detail
```mermaid
sequenceDiagram