diff --git a/content/battlechain/quickstart/deploy-first-contract.mdx b/content/battlechain/quickstart/deploy-first-contract.mdx
index 853234e..0dacbec 100644
--- a/content/battlechain/quickstart/deploy-first-contract.mdx
+++ b/content/battlechain/quickstart/deploy-first-contract.mdx
@@ -341,3 +341,13 @@ cast nonce --rpc-url https://testnet.battlechain.com:3051 <your-wallet-address>
 ### Transaction rejected: EIP-1559 not supported
 
 If you see an error like `transaction type not supported` or `only legacy transactions allowed`, add `--legacy` to your `forge script` command. See the warning above in Step 1.
+
+### Contract too large to deploy
+
+BattleChain enforces the standard EVM contract size limit of 24,576 bytes (EIP-170). If deployment fails with a size-related error, enable the Solidity optimizer in `foundry.toml`:
+
+```toml
+[profile.default]
+optimizer = true
+optimizer_runs = 200
+```
diff --git a/content/battlechain/tutorials/deploying-contracts.mdx b/content/battlechain/tutorials/deploying-contracts.mdx
index 193275f..33f5de8 100644
--- a/content/battlechain/tutorials/deploying-contracts.mdx
+++ b/content/battlechain/tutorials/deploying-contracts.mdx
@@ -26,6 +26,18 @@ remappings = [
 ]
 ```
 
+<Warning>
+**Contract size limit: 24,576 bytes**
+
+BattleChain enforces the standard EVM contract size limit (EIP-170). If your compiled bytecode exceeds 24,576 bytes, deployment will fail. Enable the Solidity optimizer in `foundry.toml` to reduce bytecode size:
+
+```toml
+[profile.default]
+optimizer = true
+optimizer_runs = 200
+```
+</Warning>
+
 ### Deploy with helpers
 
 Inherit `BCDeploy` (deploy only) or `BCScript` (deploy + agreement + attack mode):
diff --git a/package-lock.json b/package-lock.json
index aa7c22f..ee30b3a 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -23,7 +23,9 @@
         "react": "^19.2.4",
         "react-dom": "^19.2.4",
         "react-icons": "^5.5.0",
+        "rehype-autolink-headings": "^7.1.0",
         "rehype-prism-plus": "^2.0.1",
+        "rehype-slug": "^6.0.0",
         "remark-frontmatter": "^5.0.0",
         "remark-gfm": "^4.0.1",
         "three": "^0.182.0",
@@ -6275,6 +6277,11 @@
         "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
       }
     },
+    "node_modules/github-slugger": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-2.0.0.tgz",
+      "integrity": "sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw=="
+    },
     "node_modules/glob": {
       "version": "10.3.10",
       "resolved": "https://registry.npmjs.org/glob/-/glob-10.3.10.tgz",
@@ -6566,6 +6573,30 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/hast-util-heading-rank": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-heading-rank/-/hast-util-heading-rank-3.0.0.tgz",
+      "integrity": "sha512-EJKb8oMUXVHcWZTDepnr+WNbfnXKFNf9duMesmr4S8SXTJBJ9M4Yok08pu9vxdJwdlGRhVumk9mEhkEvKGifwA==",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-is-element": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-is-element/-/hast-util-is-element-3.0.0.tgz",
+      "integrity": "sha512-Val9mnv2IWpLbNPqc/pUem+a7Ipj2aHacCwgNfTiK0vJKl0LF+4Ba4+v1oPHFpf3bLYmreq0/l3Gud9S5OH42g==",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/hast-util-parse-selector": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/hast-util-parse-selector/-/hast-util-parse-selector-3.1.1.tgz",
@@ -9686,6 +9717,23 @@
         "regjsparser": "bin/parser"
       }
     },
+    "node_modules/rehype-autolink-headings": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/rehype-autolink-headings/-/rehype-autolink-headings-7.1.0.tgz",
+      "integrity": "sha512-rItO/pSdvnvsP4QRB1pmPiNHUskikqtPojZKJPPPAVx9Hj8i8TwMBhofrrAYRhYOOBZH9tgmG5lPqDLuIWPWmw==",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@ungap/structured-clone": "^1.0.0",
+        "hast-util-heading-rank": "^3.0.0",
+        "hast-util-is-element": "^3.0.0",
+        "unified": "^11.0.0",
+        "unist-util-visit": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/rehype-parse": {
       "version": "9.0.1",
       "resolved": "https://registry.npmjs.org/rehype-parse/-/rehype-parse-9.0.1.tgz",
@@ -9727,6 +9775,22 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/rehype-slug": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/rehype-slug/-/rehype-slug-6.0.0.tgz",
+      "integrity": "sha512-lWyvf/jwu+oS5+hL5eClVd3hNdmwM1kAC0BUvEGD19pajQMIzcNUd/k9GsfQ+FfECvX+JE+e9/btsKH0EjJT6A==",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "github-slugger": "^2.0.0",
+        "hast-util-heading-rank": "^3.0.0",
+        "hast-util-to-string": "^3.0.0",
+        "unist-util-visit": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
     "node_modules/remark-frontmatter": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/remark-frontmatter/-/remark-frontmatter-5.0.0.tgz",