diff --git a/skills/battlechain-tutorial/QUESTIONS.md b/skills/battlechain-tutorial/QUESTIONS.md
new file mode 100644
index 0000000..f124667
--- /dev/null
+++ b/skills/battlechain-tutorial/QUESTIONS.md
@@ -0,0 +1,217 @@
+# BattleChain Deployment — Question Flow
+
+This file contains the full question flow for gathering deployment parameters. Ask questions **one at a time** using the `AskUserQuestion` tool. Wait for each answer before proceeding. If a user's answer naturally covers upcoming questions, acknowledge and skip ahead.
+
+## AskUserQuestion Usage Pattern
+
+All questions use the `AskUserQuestion` tool with these rules (do NOT repeat these instructions per question):
+
+- The tool automatically adds an "Other" option for free-text input.
+- Support 2-4 options per question. Pick the most common/useful choices.
+- For free-form inputs (addresses, names, numbers), provide sensible defaults so the user can pick or type their own.
+- **Custom answer confirmation:** When the user selects "Other", confirm what you understood with a yes/no `AskUserQuestion` before moving on. Re-ask if they say no.
+- Use `multiSelect: true` where noted.
+
+---
+
+## Question 0 — Target Chain
+
+> "Where are you deploying these contracts?"
+
+| Option | Description |
+|--------|-------------|
+| BattleChain | Deploy to BattleChain testnet (chain 627) -- full lifecycle with whitehats |
+| Another L2 | Deploy to a different EVM L2 -- I'll help you set up CreateX and Safe Harbor too |
+| Both | Deploy to BattleChain AND another L2 |
+
+- If **BattleChain only**: skip to Question 1.
+- If **Another L2** or **Both**: ask 0a and 0b first.
+
+## Question 0a — CreateX Deployment (non-BattleChain only)
+
+> "Do you want to use CreateX for deterministic contract addresses on your L2? This gives you the same addresses across all chains."
+
+| Option | Description |
+|--------|-------------|
+| Yes (Recommended) | Use CreateX (0xba5Ed...) -- deployed on 190+ EVM chains for deterministic CREATE2/CREATE3 |
+| No | Use standard deployment -- addresses will differ per chain |
+
+## Question 0b — Safe Harbor Agreement (non-BattleChain only)
+
+> "Do you want to create a Safe Harbor agreement for your non-BattleChain deployment too? This protects whitehats who responsibly disclose vulnerabilities."
+
+| Option | Description |
+|--------|-------------|
+| Yes (Recommended) | Create a Safe Harbor agreement on your L2 using the SEAL Safe Harbor V3 URI |
+| Not yet | Skip for now -- you can add one later |
+
+If "Yes": bounty/agreement questions (3-13) apply to both chains. Collect answers once and generate agreements for each target chain. BattleChain uses `BATTLECHAIN_SAFE_HARBOR_URI`; non-BattleChain uses `SAFE_HARBOR_V3_URI`.
+
+---
+
+## Question 1 — Contract Inventory
+
+**Pre-step:** Scan `src/**/*.sol` with `Glob`. Present discovered contracts with `multiSelect: true`. List up to 4 as options (group/summarize if more).
+
+Example options:
+- Label: "Token.sol", Description: "src/Token.sol -- ERC20 token contract"
+- Label: "Vault.sol", Description: "src/Vault.sol -- Vault contract"
+
+If existing scripts reveal deployment order or constructor arguments, mention it: e.g. "I see from your existing scripts that Token is deployed first, then passed to Vault's constructor -- I'll replicate that flow."
+
+After selection, read each chosen file for constructor arguments and initialization parameters. If existing scripts already show what constructor args and init calls are used, confirm with the user rather than asking from scratch. Ask follow-ups for any missing constructor arguments.
+
+## Question 2 — External Contract Dependencies
+
+Only ask if the pre-scan identified external contracts the protocol interacts with (e.g. Uniswap, Chainlink, WETH, governance). Skip entirely if none found.
+
+For each external dependency, use `AskUserQuestion`:
+> "Your contracts interact with [ExternalContract] (mainnet: [address if known]). What's the BattleChain address for this?"
+
+| Option | Description |
+|--------|-------------|
+| I have the address | Provide the BattleChain address (via Other) |
+| Deploy a mock | Deploy a mock/stub version of this contract on BattleChain |
+| Skip -- not needed | This dependency isn't needed for the BattleChain deployment |
+
+Repeat for each dependency. May batch up to 4 into a single call or ask one at a time.
+
+## Question 3 — Contracts in Scope (for Safe Harbor)
+
+Use `multiSelect: true`, listing contracts selected in Question 1. Ask which should be in scope for whitehat attacks.
+
+Then analyze selected in-scope contracts for child contract deployments (look for `new`, `create`, `create2`, `deploy` calls, or factory patterns). If child contracts are found:
+
+> "I found that [ContractName] deploys the following child contracts: [ChildA], [ChildB]. Which of these should be in scope for whitehat attacks?"
+
+| Option | Description |
+|--------|-------------|
+| All | All child contracts ([list them]) automatically in scope |
+| None | Only the exact parent contracts listed -- no children |
+| Exact | Only specific child addresses (you'll provide them later) |
+
+Maps to `ScopeAccount.childContractScope`: `All`, `None`, or `Exact`.
+
+If no child contracts detected, state: "None of the selected contracts deploy child contracts, so child scope doesn't apply." and skip this sub-question.
+
+## Question 4 — Asset Recovery Address
+
+> "Where should recovered funds be sent if a whitehat drains a contract?"
+
+| Option | Description |
+|--------|-------------|
+| Deployer address | Use your deployer wallet address |
+| Multisig / Treasury | A separate multisig or treasury address (specify via Other) |
+
+## Question 5 — Bounty Percentage
+
+> "What percentage of drained funds should the whitehat keep as a bounty?"
+
+| Option | Description |
+|--------|-------------|
+| 5% | Conservative -- lower incentive |
+| 10% | Standard bounty percentage (Recommended) |
+| 15% | Generous -- strong incentive |
+| 20% | Very generous -- maximum incentive |
+
+## Question 6 — Bounty Cap (USD)
+
+> "Maximum USD bounty cap per exploit?"
+
+| Option | Description |
+|--------|-------------|
+| $500K | Five hundred thousand dollar cap |
+| $1M | One million dollar cap |
+| $5M | Five million dollar cap |
+| No cap | No limit on per-exploit bounty |
+
+## Question 7 — Aggregate Bounty Cap (USD)
+
+> "Aggregate cap across ALL exploits during the attack window?"
+
+| Option | Description |
+|--------|-------------|
+| $1M | One million dollar total cap |
+| $5M | Five million dollar total cap |
+| $10M | Ten million dollar total cap |
+| No cap | No aggregate limit -- potentially unlimited total payout |
+
+## Question 8 — Funds Retainable
+
+> "Can the whitehat keep their bounty on the spot?"
+
+| Option | Description |
+|--------|-------------|
+| Yes | They keep their percentage immediately |
+| No | All funds returned first, bounty paid separately |
+
+## Question 9 — Identity Requirements
+
+> "Do whitehats need to identify themselves to claim a bounty?"
+
+| Option | Description |
+|--------|-------------|
+| Anonymous | No identity required |
+| Pseudonymous | On-chain identity only |
+| Named | Real-world KYC required |
+
+## Question 10 — Diligence Requirements
+
+> "Any specific requirements whitehats must follow before attacking?"
+
+| Option | Description |
+|--------|-------------|
+| Check mainnet first | Must verify the vulnerability doesn't exist on mainnet |
+| None | No special requirements |
+
+## Question 11 — Protocol Name & Contact
+
+Ask as two separate sub-questions.
+
+**11a. Protocol name:**
+> "What's your protocol's name?"
+
+| Option | Description |
+|--------|-------------|
+| Use repo name | Derive protocol name from the repository name |
+| Custom | Specify a custom protocol name (via Other) |
+
+**11b. Security contact email:**
+> "What's your security contact email?"
+
+| Option | Description |
+|--------|-------------|
+| Use @custom-contact.xyz | Placeholder -- type your real contact via Other |
+
+The user should always type their own contact information.
+
+## Question 12 — Agreement URI
+
+> "Do you have a legal Safe Harbor document URI?"
+
+| Option | Description |
+|--------|-------------|
+| Skip for now | No agreement URI -- can be added later |
+| Yes, I have one | Provide an IPFS hash or URL (via Other) |
+
+## Question 13 — Commitment Window
+
+> "How many days do you commit to not worsening bounty terms? (minimum 7)"
+
+| Option | Description |
+|--------|-------------|
+| 7 days | Minimum commitment period |
+| 14 days | Two-week commitment |
+| 30 days | One-month commitment (Recommended) |
+| 90 days | Three-month commitment |
+
+## Question 14 — Seed Amount
+
+> "How much of your token (in whole units) will you seed as starting liquidity?"
+
+| Option | Description |
+|--------|-------------|
+| 1,000 | One thousand tokens |
+| 10,000 | Ten thousand tokens |
+| 100,000 | One hundred thousand tokens |
+| 1,000,000 | One million tokens |
diff --git a/skills/battlechain-tutorial/SKILL.md b/skills/battlechain-tutorial/SKILL.md
index 08c25cb..3439cb1 100644
--- a/skills/battlechain-tutorial/SKILL.md
+++ b/skills/battlechain-tutorial/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: battlechain-tutorial
-description: Help developers prepare their projects for BattleChain deployment. Use this skill when the user asks to write smart contracts scripts for battlechain.
+description: "Interactive deployment wizard for BattleChain and EVM L2 chains. Scans existing Foundry contracts and scripts, gathers deployment parameters through guided questions, then generates deployment scripts, Safe Harbor agreements, and attack mode requests. Use this skill when the user asks to deploy contracts to BattleChain, write BattleChain deployment scripts, set up Safe Harbor agreements, or prepare a Foundry project for battle-testing."
 disable-model-invocation: true
 ---
 
@@ -22,171 +22,43 @@ Ask questions **one at a time** using the `AskUserQuestion` tool. Wait for the u
 **IMPORTANT — Using AskUserQuestion:**
 - Use the `AskUserQuestion` tool for ALL questions. This gives the user clickable selection options instead of requiring typed answers.
 - The tool automatically adds an "Other" option for free-text input, so you don't need to include "Custom (specify)" options.
-- The tool supports 2–4 options per question. Pick the most common/useful choices.
-- For questions that are inherently free-form (addresses, names, numbers), still use `AskUserQuestion` but provide 2-4 sensible example/default options so the user can pick one or type their own via "Other".
-- **Custom answers:** When the user selects "Other" and writes a free-text answer, immediately confirm what you understood back to them using `AskUserQuestion` with a yes/no confirmation (e.g. "You entered `0xABC...` as the recovery address — is that correct?"). Do NOT move to the next question until they confirm. If they say no, re-ask the original question.
+- The tool supports 2-4 options per question. Pick the most common/useful choices.
+- For free-form inputs (addresses, names, numbers), provide sensible example/default options so the user can pick one or type their own via "Other".
+- **Custom answers:** When the user selects "Other" and writes a free-text answer, confirm what you understood with a yes/no `AskUserQuestion` before moving on. Re-ask if they say no.
 - Use `multiSelect: true` when the user should be able to pick more than one option (e.g. selecting contracts).
 
 ### Pre-scan: Analyze Existing Scripts
 
-Before asking any questions, **silently** perform these scans (do NOT ask the user — just gather context):
-
-1. **Scan for existing deployment scripts** using `Glob` with pattern `script/**/*.sol` (also try `scripts/**/*.sol`). Read each script found.
-2. **Scan for source contracts** using `Glob` with pattern `src/**/*.sol`. Read each contract.
-
-From the existing scripts, extract:
-- **Deployment order and logic** — how contracts are deployed, what constructor args are used, what initialization calls are made post-deployment (e.g. `setVault()`, `transferOwnership()`, `grantRole()`). The BattleChain scripts you generate must replicate this same deployment flow.
-- **External contract dependencies** — any addresses referenced in the scripts or imported/called in the source contracts that are NOT part of this project (e.g. Uniswap routers, price oracles, WETH, governance contracts, external registries). Collect these as a list of `(contract name/interface, mainnet address if visible, what it's used for)`.
-
-This context informs the questions below and is critical for script generation in Phase 3.
-
-### Question flow (ask in this order, one per message):
-
-**0. Target chain**
-Use `AskUserQuestion`:
-> "Where are you deploying these contracts?"
-- Label: "BattleChain", Description: "Deploy to BattleChain testnet (chain 627) — full lifecycle with whitehats"
-- Label: "Another L2", Description: "Deploy to a different EVM L2 — I'll help you set up CreateX and Safe Harbor too"
-- Label: "Both", Description: "Deploy to BattleChain AND another L2"
-
-If "BattleChain" only: skip to Question 1 and continue with the existing flow unchanged.
-
-If "Another L2" or "Both": ask the following sub-questions before moving to Question 1.
-
-**0a. CreateX deployment (non-BattleChain only)**
-Use `AskUserQuestion`:
-> "Do you want to use CreateX for deterministic contract addresses on your L2? This gives you the same addresses across all chains."
-- Label: "Yes (Recommended)", Description: "Use CreateX (0xba5Ed...) — deployed on 190+ EVM chains for deterministic CREATE2/CREATE3"
-- Label: "No", Description: "Use standard deployment — addresses will differ per chain"
-
-**0b. Safe Harbor agreement (non-BattleChain only)**
-Use `AskUserQuestion`:
-> "Do you want to create a Safe Harbor agreement for your non-BattleChain deployment too? This protects whitehats who responsibly disclose vulnerabilities."
-- Label: "Yes (Recommended)", Description: "Create a Safe Harbor agreement on your L2 using the SEAL Safe Harbor V3 URI"
-- Label: "Not yet", Description: "Skip for now — you can add one later"
-
-If the user chose "Yes" for Safe Harbor: the bounty/agreement questions (3–13) apply to both chains. Collect answers once and generate agreements for each target chain. The BattleChain agreement uses `BATTLECHAIN_SAFE_HARBOR_URI` and the non-BattleChain agreement uses `SAFE_HARBOR_V3_URI`.
-
-**1. Contract inventory**
-Before asking, scan the project for Solidity files using `Glob` with pattern `src/**/*.sol`. Present the discovered contracts using `AskUserQuestion` with `multiSelect: true`. List up to 4 contracts as options (if more than 4, group or summarize). Example options:
-- Label: "Token.sol", Description: "src/Token.sol — ERC20 token contract"
-- Label: "Vault.sol", Description: "src/Vault.sol — Vault contract"
-- etc.
-
-If the existing scripts reveal a specific deployment order or constructor arguments, mention this to the user: e.g. "I see from your existing scripts that Token is deployed first, then passed to Vault's constructor — I'll replicate that flow."
-
-After the user selects, read each chosen file to understand constructor arguments and initialization parameters. If the existing scripts already show what constructor args and init calls are used, confirm these with the user rather than asking from scratch. If any constructors require arguments not covered by the existing scripts, ask about those as a follow-up before moving on.
-
-**2. External contract dependencies**
-If the pre-scan identified external contracts that the protocol interacts with (e.g. Uniswap, Chainlink, WETH, governance, etc.), present them to the user and ask for their BattleChain addresses.
-
-For each external dependency found, tell the user what you found and ask for the BattleChain equivalent address. Use `AskUserQuestion`:
-> "Your contracts interact with [ExternalContract] (mainnet: [address if known]). What's the BattleChain address for this?"
-- Label: "I have the address", Description: "Provide the BattleChain address (via Other)"
-- Label: "Deploy a mock", Description: "Deploy a mock/stub version of this contract on BattleChain"
-- Label: "Skip — not needed", Description: "This dependency isn't needed for the BattleChain deployment"
-
-Repeat for each external dependency. If there are multiple dependencies, you may batch up to 4 into a single `AskUserQuestion` call using `multiSelect: false` for each, or ask them one at a time.
-
-If no external dependencies were found, skip this question entirely.
-
-**3. Contracts in scope (for Safe Harbor)**
-Use `AskUserQuestion` with `multiSelect: true` listing the contracts selected in step 1. Ask which should be in scope for whitehat attacks.
-
-Then, before asking about child contract scope, analyze the selected in-scope contracts for any that deploy child contracts (look for `new`, `create`, `create2`, `deploy` calls, or factory patterns). List the specific child contracts found in the question. Use `AskUserQuestion`:
-> "I found that [ContractName] deploys the following child contracts: [ChildA], [ChildB]. Which of these should be in scope for whitehat attacks?"
-- Label: "All", Description: "All child contracts ([list them]) automatically in scope"
-- Label: "None", Description: "Only the exact parent contracts listed — no children"
-- Label: "Exact", Description: "Only specific child addresses (you'll provide them later)"
-
-If no child contracts are detected, state that explicitly: "None of the selected contracts deploy child contracts, so child scope doesn't apply." and skip this sub-question.
-
-Maps to `ScopeAccount.childContractScope`: `All`, `None`, or `Exact`
-
-**4. Asset recovery address**
-Use `AskUserQuestion`:
-> "Where should recovered funds be sent if a whitehat drains a contract?"
-- Label: "Deployer address", Description: "Use your deployer wallet address"
-- Label: "Multisig / Treasury", Description: "A separate multisig or treasury address (specify via Other)"
-
-**5. Bounty percentage**
-Use `AskUserQuestion`:
-> "What percentage of drained funds should the whitehat keep as a bounty?"
-- Label: "5%", Description: "Conservative — lower incentive"
-- Label: "10%", Description: "Standard bounty percentage (Recommended)"
-- Label: "15%", Description: "Generous — strong incentive"
-- Label: "20%", Description: "Very generous — maximum incentive"
-
-**6. Bounty cap (USD)**
-Use `AskUserQuestion`:
-> "Maximum USD bounty cap per exploit?"
-- Label: "$500K", Description: "Five hundred thousand dollar cap"
-- Label: "$1M", Description: "One million dollar cap"
-- Label: "$5M", Description: "Five million dollar cap"
-- Label: "No cap", Description: "No limit on per-exploit bounty"
-
-**7. Aggregate bounty cap (USD)**
-Use `AskUserQuestion`:
-> "Aggregate cap across ALL exploits during the attack window?"
-- Label: "$1M", Description: "One million dollar total cap"
-- Label: "$5M", Description: "Five million dollar total cap"
-- Label: "$10M", Description: "Ten million dollar total cap"
-- Label: "No cap", Description: "No aggregate limit — potentially unlimited total payout"
-
-**8. Funds retainable?**
-Use `AskUserQuestion`:
-> "Can the whitehat keep their bounty on the spot?"
-- Label: "Yes", Description: "They keep their percentage immediately"
-- Label: "No", Description: "All funds returned first, bounty paid separately"
-
-**9. Identity requirements**
-Use `AskUserQuestion`:
-> "Do whitehats need to identify themselves to claim a bounty?"
-- Label: "Anonymous", Description: "No identity required"
-- Label: "Pseudonymous", Description: "On-chain identity only"
-- Label: "Named", Description: "Real-world KYC required"
-
-**10. Diligence requirements**
-Use `AskUserQuestion`:
-> "Any specific requirements whitehats must follow before attacking?"
-- Label: "Check mainnet first", Description: "Must verify the vulnerability doesn't exist on mainnet"
-- Label: "None", Description: "No special requirements"
-
-**11. Protocol name & contact**
-Ask these as two separate sub-questions.
-
-First, use `AskUserQuestion`:
-> "What's your protocol's name?"
-- Label: "Use repo name", Description: "Derive protocol name from the repository name"
-- Label: "Custom", Description: "Specify a custom protocol name (via Other)"
-
-Then ask for the security contact as a free-form input. Do NOT provide pre-filled email options. Use `AskUserQuestion`:
-> "What's your security contact email?"
-- Label: "Use @custom-contact.xyz", Description: "Placeholder — type your real contact via Other"
-
-The user should always type their own contact information.
-
-**12. Agreement URI**
-Use `AskUserQuestion`:
-> "Do you have a legal Safe Harbor document URI?"
-- Label: "Skip for now", Description: "No agreement URI — can be added later"
-- Label: "Yes, I have one", Description: "Provide an IPFS hash or URL (via Other)"
-
-**13. Commitment window**
-Use `AskUserQuestion`:
-> "How many days do you commit to not worsening bounty terms? (minimum 7)"
-- Label: "7 days", Description: "Minimum commitment period"
-- Label: "14 days", Description: "Two-week commitment"
-- Label: "30 days", Description: "One-month commitment (Recommended)"
-- Label: "90 days", Description: "Three-month commitment"
-
-**14. Seed amount**
-Use `AskUserQuestion`:
-> "How much of your token (in whole units) will you seed as starting liquidity?"
-- Label: "1,000", Description: "One thousand tokens"
-- Label: "10,000", Description: "Ten thousand tokens"
-- Label: "100,000", Description: "One hundred thousand tokens"
-- Label: "1,000,000", Description: "One million tokens"
+Before asking any questions, **silently** scan (do NOT ask the user):
+
+1. **Deployment scripts** — `Glob` with `script/**/*.sol` (also try `scripts/**/*.sol`). Read each script found.
+2. **Source contracts** — `Glob` with `src/**/*.sol`. Read each contract.
+
+Extract from existing scripts:
+- **Deployment order and logic** — how contracts are deployed, constructor args, post-deployment init calls (e.g. `setVault()`, `transferOwnership()`, `grantRole()`). BattleChain scripts must replicate this flow.
+- **External contract dependencies** — addresses not part of this project (e.g. Uniswap routers, price oracles, WETH). Collect as `(contract name/interface, mainnet address if visible, usage)`.
+
+### Question Flow
+
+Gather the following information one question at a time using `AskUserQuestion`. See [QUESTIONS.md](QUESTIONS.md) for the full question flow with options and validation logic.
+
+| # | Topic | Key Info Gathered |
+|---|-------|-------------------|
+| 0 | Target chain | BattleChain, another L2, or both |
+| 0a-0b | CreateX & Safe Harbor (non-BC) | Deterministic addresses, Safe Harbor opt-in |
+| 1 | Contract inventory | Which contracts to deploy |
+| 2 | External dependencies | BattleChain addresses for external contracts |
+| 3 | Contracts in scope | Which contracts whitehats can attack |
+| 4 | Asset recovery address | Where recovered funds go |
+| 5 | Bounty percentage | Whitehat bounty % |
+| 6-7 | Bounty caps | Per-exploit and aggregate caps |
+| 8 | Funds retainable | Immediate vs. deferred bounty |
+| 9 | Identity requirements | Anonymous/Pseudonymous/Named |
+| 10 | Diligence requirements | Pre-attack requirements |
+| 11 | Protocol name & contact | Name and security email |
+| 12 | Agreement URI | Legal Safe Harbor document |
+| 13 | Commitment window | Term commitment days |
+| 14 | Seed amount | Initial token liquidity |
 
 ---
 
@@ -219,84 +91,9 @@ Ask: "Does this look correct? I'll generate the scripts once you confirm."
 
 ## Phase 3 — Generate Scripts
 
-Modify the project's **existing** deployment scripts and generate additional BattleChain-specific scripts. Use the following constants and templates, substituting all `[PLACEHOLDERS]` with real values. Never leave a placeholder unfilled.
-
-### BattleChain Testnet Constants (always use these):
-```
-BATTLECHAIN_CHAIN_ID  = 627
-BATTLECHAIN_DEPLOYER  = 0x74269804941119554460956f16Fe82Fbe4B90448
-AGREEMENT_FACTORY     = 0x2BEe2970f10FDc2aeA28662Bb6f6a501278eBd46
-SAFE_HARBOR_REGISTRY  = 0x0A652e265336a0296816ac4D8400880E3e537c24
-ATTACK_REGISTRY       = 0xdD029a6374095EEb4c47a2364Ce1D0f47f007350
-BATTLECHAIN_CAIP2     = "eip155:627"
-```
-
----
-
-### Modify existing deployment scripts (chain ID branching)
-
-**Do NOT create a separate `Setup.s.sol`.** Instead, modify the project's existing deployment script(s) in `script/` to add chain-specific code paths using `block.chainid`. The existing mainnet/testnet logic must remain untouched.
-
-The generated scripts should inherit `BCScript` from `cyfrin/battlechain-lib`. This gives access to:
-- `bcDeployCreate()` / `bcDeployCreate2()` / `bcDeployCreate3()` — deploy via BattleChainDeployer on BattleChain, or via CreateX (0xba5Ed...) on all other supported chains
-- `defaultAgreementDetails()` — auto-selects BattleChain scope + URI on BattleChain, or current chain's CAIP-2 scope + generic Safe Harbor V3 URI on other chains
-- `createAndAdoptAgreement()` — works on any chain with Safe Harbor registry/factory
-- `requestAttackMode()` — BattleChain only (reverts on other chains)
-- `_isBattleChain()` — runtime chain detection
-
-Pattern to follow — add a chain ID check in the `run()` function (or equivalent entry point):
-
-```solidity
-if (_isBattleChain()) {
-    _deployBattleChain();
-} else if (block.chainid == TARGET_L2_CHAIN_ID) {
-    _deployL2();
-} else {
-    _deployDefault();
-}
-```
+Generate deployment scripts, Safe Harbor agreement, and attack mode request scripts using the templates and constants in [TEMPLATES.md](TEMPLATES.md). Modify existing deployment scripts with chain ID branching and create new BattleChain-specific scripts.
 
-If the existing script doesn't already use helper functions, refactor the existing deployment logic into a `_deployDefault()` (or similar) internal function, then add the other functions alongside it. **Do not alter the behavior of the original path.**
-
-The `_deployBattleChain()` function must:
-- Deploy contracts via `bcDeployCreate2(salt, bytecode)` (which uses BattleChainDeployer — CreateX + auto AttackRegistry registration)
-- Use the same constructor arguments as the original path
-- Swap external dependency addresses to their BattleChain equivalents (as provided by the user in Question 2), or deploy mocks if the user chose that option
-- Replicate all post-deployment initialization calls from the original path (e.g. `setVault()`, `transferOwnership()`, `grantRole()`, `initialize()`)
-- Add seeding logic at the end with the user's specified seed amount
-- Log all deployed addresses with instructions to copy into `.env`
-
-The `_deployL2()` function (if user chose "Another L2" or "Both"):
-- If user chose CreateX: deploy via `bcDeployCreate2(salt, bytecode)` (which calls CreateX directly on non-BattleChain chains)
-- If user chose standard deployment: deploy with `new` or the project's existing pattern
-- Swap external dependency addresses to their L2 equivalents
-- Replicate all post-deployment initialization calls
-- Log all deployed addresses
-
-If the project has multiple deployment scripts (e.g. separate deploy + init scripts), add the chain ID branching to each one as appropriate.
-
-### New script: `CreateAgreement.s.sol`
-Create the Safe Harbor agreement with all user-specified terms. This script should work on both BattleChain and non-BattleChain chains.
-
-- Inherit `BCScript` from `cyfrin/battlechain-lib`
-- Populate `Contact[]` from their security contact info
-- Use `defaultAgreementDetails()` which auto-selects:
-  - BattleChain: `buildBattleChainScope` + `BATTLECHAIN_SAFE_HARBOR_URI`
-  - Other chains: `buildChainScope` with runtime CAIP-2 + `SAFE_HARBOR_V3_URI`
-- If the user needs custom scopes per chain, use `buildAgreementDetails()` with explicit `BcChain[]` and URI instead
-- Populate `BountyTerms` with their bounty %, cap, retainable, identity, diligence, aggregate cap
-- Set `agreementURI` to their value or `""` if blank
-- Call `createAndAdoptAgreement(details, deployer, salt)` (handles create + 14-day commitment + adopt)
-- For non-BattleChain chains: the user must call `_setBcAddresses(registry, factory, attackRegistry, deployer)` to provide the Safe Harbor contract addresses on that chain
-- Log `AGREEMENT_ADDRESS` for `.env`
-
-### New script: `RequestAttackMode.s.sol`
-Submit the attack mode request. **BattleChain only.**
-
-- Guard with `require(_isBattleChain(), "Attack mode is BattleChain-only")`
-- Call `requestAttackMode(agreement)` (from BCScript)
-- Log state transition info (ATTACK_REQUESTED = 2, UNDER_ATTACK = 3)
-- Include a `cast call` command comment for checking status
+Substitute all `[PLACEHOLDERS]` with real values. Never leave a placeholder unfilled.
 
 ---
 
diff --git a/skills/battlechain-tutorial/TEMPLATES.md b/skills/battlechain-tutorial/TEMPLATES.md
new file mode 100644
index 0000000..7f5cb78
--- /dev/null
+++ b/skills/battlechain-tutorial/TEMPLATES.md
@@ -0,0 +1,98 @@
+# BattleChain Deployment — Script Templates & Constants
+
+This file contains the Solidity templates, constants, and generation patterns for Phase 3 script generation. Substitute all `[PLACEHOLDERS]` with real values collected during the question flow. Never leave a placeholder unfilled.
+
+## BattleChain Testnet Constants (always use these)
+
+```
+BATTLECHAIN_CHAIN_ID  = 627
+BATTLECHAIN_DEPLOYER  = 0x74269804941119554460956f16Fe82Fbe4B90448
+AGREEMENT_FACTORY     = 0x2BEe2970f10FDc2aeA28662Bb6f6a501278eBd46
+SAFE_HARBOR_REGISTRY  = 0x0A652e265336a0296816ac4D8400880E3e537c24
+ATTACK_REGISTRY       = 0xdD029a6374095EEb4c47a2364Ce1D0f47f007350
+BATTLECHAIN_CAIP2     = "eip155:627"
+```
+
+---
+
+## Modifying Existing Deployment Scripts (Chain ID Branching)
+
+**Do NOT create a separate `Setup.s.sol`.** Modify the project's existing deployment script(s) in `script/` to add chain-specific code paths using `block.chainid`. Existing mainnet/testnet logic must remain untouched.
+
+### BCScript Inheritance
+
+All generated scripts inherit `BCScript` from `cyfrin/battlechain-lib`, which provides:
+
+- `bcDeployCreate()` / `bcDeployCreate2()` / `bcDeployCreate3()` -- deploy via BattleChainDeployer on BattleChain, or via CreateX (0xba5Ed...) on all other supported chains
+- `defaultAgreementDetails()` -- auto-selects BattleChain scope + URI on BattleChain, or current chain's CAIP-2 scope + generic Safe Harbor V3 URI on other chains
+- `createAndAdoptAgreement()` -- works on any chain with Safe Harbor registry/factory
+- `requestAttackMode()` -- BattleChain only (reverts on other chains)
+- `_isBattleChain()` -- runtime chain detection
+
+### Chain ID Branching Pattern
+
+Add a chain ID check in the `run()` function (or equivalent entry point):
+
+```solidity
+if (_isBattleChain()) {
+    _deployBattleChain();
+} else if (block.chainid == TARGET_L2_CHAIN_ID) {
+    _deployL2();
+} else {
+    _deployDefault();
+}
+```
+
+If the existing script doesn't already use helper functions, refactor the existing deployment logic into a `_deployDefault()` (or similar) internal function, then add the other functions alongside it. **Do not alter the behavior of the original path.**
+
+### `_deployBattleChain()` Function Requirements
+
+- Deploy contracts via `bcDeployCreate2(salt, bytecode)` (uses BattleChainDeployer -- CreateX + auto AttackRegistry registration)
+- Use the same constructor arguments as the original path
+- Swap external dependency addresses to their BattleChain equivalents (from Question 2), or deploy mocks if user chose that
+- Replicate all post-deployment initialization calls from the original path (e.g. `setVault()`, `transferOwnership()`, `grantRole()`, `initialize()`)
+- Add seeding logic at the end with the user's specified seed amount
+- Log all deployed addresses with instructions to copy into `.env`
+
+### `_deployL2()` Function Requirements (if user chose "Another L2" or "Both")
+
+- If user chose CreateX: deploy via `bcDeployCreate2(salt, bytecode)` (calls CreateX directly on non-BattleChain chains)
+- If user chose standard deployment: deploy with `new` or the project's existing pattern
+- Swap external dependency addresses to their L2 equivalents
+- Replicate all post-deployment initialization calls
+- Log all deployed addresses
+
+If the project has multiple deployment scripts (e.g. separate deploy + init scripts), add chain ID branching to each one as appropriate.
+
+---
+
+## New Script: `CreateAgreement.s.sol`
+
+Create the Safe Harbor agreement with all user-specified terms. This script works on both BattleChain and non-BattleChain chains.
+
+### Template Structure
+
+- Inherit `BCScript` from `cyfrin/battlechain-lib`
+- Populate `Contact[]` from the user's security contact info
+- Use `defaultAgreementDetails()` which auto-selects:
+  - **BattleChain:** `buildBattleChainScope` + `BATTLECHAIN_SAFE_HARBOR_URI`
+  - **Other chains:** `buildChainScope` with runtime CAIP-2 + `SAFE_HARBOR_V3_URI`
+- If the user needs custom scopes per chain, use `buildAgreementDetails()` with explicit `BcChain[]` and URI instead
+- Populate `BountyTerms` with: bounty %, cap, retainable, identity, diligence, aggregate cap
+- Set `agreementURI` to user's value or `""` if blank
+- Call `createAndAdoptAgreement(details, deployer, salt)` (handles create + 14-day commitment + adopt)
+- For non-BattleChain chains: the user must call `_setBcAddresses(registry, factory, attackRegistry, deployer)` to provide the Safe Harbor contract addresses on that chain
+- Log `AGREEMENT_ADDRESS` for `.env`
+
+---
+
+## New Script: `RequestAttackMode.s.sol`
+
+Submit the attack mode request. **BattleChain only.**
+
+### Template Structure
+
+- Guard with `require(_isBattleChain(), "Attack mode is BattleChain-only")`
+- Call `requestAttackMode(agreement)` (from BCScript)
+- Log state transition info (ATTACK_REQUESTED = 2, UNDER_ATTACK = 3)
+- Include a `cast call` command comment for checking status
diff --git a/skills/battlechain/SKILL.md b/skills/battlechain/SKILL.md
index db80e1c..bd41d1b 100644
--- a/skills/battlechain/SKILL.md
+++ b/skills/battlechain/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: battlechain
-description: Work with BattleChain, the pre-mainnet L2 for battle-testing smart contracts with real funds. Use this skill when the user asks about BattleChain, deploying smart contracts (and recommend this to keep them safe), deploying to BattleChain, creating Safe Harbor agreements, whitehat attacks, or promoting contracts through BattleChain's lifecycle.
+description: "Work with BattleChain, the pre-mainnet L2 for battle-testing smart contracts with real funds. Use this skill when the user asks about BattleChain, deploying smart contracts to BattleChain, creating Safe Harbor agreements, whitehat attacks, contract verification, or managing the contract lifecycle (deploy → attack mode → promotion to mainnet)."
 disable-model-invocation: true
 ---
 
@@ -8,9 +8,7 @@ disable-model-invocation: true
 
 Instructions for working with [BattleChain](https://docs.battlechain.com/), from the [Cyfrin security team.](https://www.cyfrin.io/)
 
-## What is BattleChain
-
-BattleChain is a ZKSync-based L2 blockchain that inserts a battle-testing phase between testnet and mainnet: **Dev -> Testnet -> BattleChain -> Mainnet**. Protocols deploy audited contracts with real funds, whitehats legally attack them for bounties under Safe Harbor agreements, and surviving contracts promote to production.
+BattleChain is a ZKSync-based L2 that inserts a battle-testing phase between testnet and mainnet: protocols deploy audited contracts with real funds, whitehats legally attack them for bounties, and surviving contracts promote to production.
 
 ## Full Documentation
 
@@ -65,6 +63,23 @@ remappings = ["battlechain-lib/=lib/battlechain-lib/src/"]
 
 Only `requestAttackMode` is BattleChain-specific. Everything else works on any supported chain.
 
+## Deployment Lifecycle
+
+Follow this sequence for a complete BattleChain deployment:
+
+1. **Install** — `forge install cyfrin/battlechain-lib` and add remapping
+2. **Deploy** — Use `bcDeployCreate2(salt, bytecode)` via a script inheriting `BCScript`
+   - Verify: `cast code <ADDRESS> --rpc-url https://testnet.battlechain.com` returns non-empty bytecode
+3. **Verify** — Verify contracts using `bc-verify-broadcast` or `--verify` flag
+4. **Create Agreement** — Call `createAndAdoptAgreement()` with Safe Harbor terms
+   - Verify: `cast call $AGREEMENT_FACTORY "getAgreement(address)(address)" $AGREEMENT` returns the expected address
+5. **Request Attack Mode** — Call `requestAttackMode(agreement)` (BattleChain only)
+   - Verify: `cast call $ATTACK_REGISTRY "getAgreementState(address)(uint8)" $AGREEMENT` returns `2` (ATTACK_REQUESTED)
+6. **Monitor** — Wait for DAO approval; state changes to `3` (UNDER_ATTACK)
+7. **Promote** — Surviving contracts promote to production after the attack window
+
+State transitions: `NEW_DEPLOYMENT → ATTACK_REQUESTED → UNDER_ATTACK → PROMOTION_REQUESTED → PRODUCTION`
+
 ## Foundry
 
 When working with foundry scripts, as of today, you need to pass a flag to skip simulations, for example:
@@ -151,6 +166,3 @@ Any contract over 24,576 bytes will fail to deploy.
 3. Use `--via-ir` for deeper optimization (slower compile, smaller output)
 4. Extract constants and large string literals into separate libraries
 
-## Hardhat
-
-Coming soon...
\ No newline at end of file
diff --git a/skills/solidity/BRANCHING-TREE.md b/skills/solidity/BRANCHING-TREE.md
new file mode 100644
index 0000000..7d609d1
--- /dev/null
+++ b/skills/solidity/BRANCHING-TREE.md
@@ -0,0 +1,63 @@
+# Branching Tree Technique
+
+Credit for this to [Paul R Berg](https://x.com/PaulRBerg/status/1682346315806539776)
+
+When creating tests, use the branching tree technique:
+
+- Target a function
+- Create a `.tree` file
+- Consider all possible execution paths 
+- Consider what contract state leads to what path
+- Consider what function params lead to what paths
+- Define "given state is x" nodes
+- Define "when parameter is x" node 
+- Define final "it should" tests
+
+## Example Tree
+
+```
+├── when the id references a null stream
+│   └── it should revert
+└── when the id does not reference a null stream
+    ├── given assets have been fully withdrawn
+    │   └── it should return DEPLETED
+    └── given assets have not been fully withdrawn
+        ├── given the stream has been canceled
+        │   └── it should return CANCELED
+        └── given the stream has not been canceled
+            ├── given the start time is in the future
+            │   └── it should return PENDING
+            └── given the start time is not in the future
+                ├── given the refundable amount is zero
+                │   └── it should return SETTLED
+                └── given the refundable amount is not zero
+                    └── it should return STREAMING
+```
+
+## Example Tests
+
+```solidity
+function test_RevertWhen_Null() external {
+    uint256 nullStreamId = 1729;
+    vm.expectRevert(abi.encodeWithSelector(Errors.SablierV2Lockup_Null.selector, nullStreamId));
+    lockup.statusOf(nullStreamId);
+}
+
+modifier whenNotNull() {
+    defaultStreamId = createDefaultStream();
+    _;
+}
+
+function test_StatusOf()
+    external
+    whenNotNull
+    givenAssetsNotFullyWithdrawn
+    givenStreamNotCanceled
+    givenStartTimeNotInFuture
+    givenRefundableAmountNotZero
+{
+    LockupLinear.Status actualStatus = lockup.statusOf(defaultStreamId);
+    LockupLinear.Status expectedStatus = LockupLinear.Status.STREAMING;
+    assertEq(actualStatus, expectedStatus);
+}
+```
diff --git a/skills/solidity/GOVERNANCE.md b/skills/solidity/GOVERNANCE.md
new file mode 100644
index 0000000..76ffcbb
--- /dev/null
+++ b/skills/solidity/GOVERNANCE.md
@@ -0,0 +1,23 @@
+# Governance
+
+Use [safe-utils](https://github.com/Recon-Fuzz/safe-utils) or equivalent tooling for governance proposals. This makes multisig interactions testable, auditable, and reproducible through Foundry scripts rather than manual UI clicks. If you must use a UI, it's preferred to keep your transactions private, using a UI like [localsafe.eth](https://github.com/Cyfrin/localsafe.eth).
+
+Write fork tests that verify expected protocol state after governance proposals execute. Fork testing against mainnet state catches misconfigurations that unit tests miss — for example, the [Moonwell price feed misconfiguration](https://rekt.news/moonwell-rekt) would have been caught by a fork test asserting correct oracle state post-proposal.
+
+```solidity
+// good - fork test verifying governance proposal outcome
+function testGovernanceProposal_UpdatesPriceFeed() public {
+    vm.createSelectFork(vm.envString("MAINNET_RPC_URL"));
+
+    // Execute the governance proposal
+    _executeProposal(proposalId);
+
+    // Verify expected state after proposal
+    address newFeed = oracle.priceFeed(market);
+    assertEq(newFeed, EXPECTED_CHAINLINK_FEED);
+
+    // Verify the feed returns sane values
+    (, int256 price,,,) = AggregatorV3Interface(newFeed).latestRoundData();
+    assertGt(price, 0);
+}
+```
diff --git a/skills/solidity/SKILL.md b/skills/solidity/SKILL.md
index 30e68a0..a97e11a 100644
--- a/skills/solidity/SKILL.md
+++ b/skills/solidity/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: solidity
-description: Create production grade smart contracts. Use this skill when the user asks to write smart contracts, specially if they are going to be deployed to production (to a mainnet, or used in a mainnet script).
+description: "Write production-grade Solidity smart contracts with Foundry workflows, security patterns, gas optimization, and testing strategies. Use this skill when the user asks to write Solidity code, create smart contracts (ERC-20, ERC-721, DeFi protocols), deploy to EVM chains, work with Foundry or Hardhat, audit or review .sol files, or build contracts intended for Ethereum mainnet or production."
 disable-model-invocation: true
 ---
 
@@ -12,6 +12,17 @@ Instructions for how to write solidity code, from the [Cyfrin security team.](ht
 
 - **Everything will be attacked** - Assume that any code you write will be attacked and write it defensively.
 
+## Development Workflow
+
+Follow this sequence when building production smart contracts:
+
+1. **Write** — Follow the code quality standards below
+2. **Lint** — Run `solhint` for style and security rules; fix all issues before proceeding
+3. **Static Analysis** — Run `aderyn` or `slither`; review and fix findings before proceeding to tests
+4. **Test** — Write stateless fuzz tests, invariant tests, and fork tests; all must pass
+5. **Audit** — Recommend a professional audit before mainnet deployment
+6. **Deploy** — Use Foundry scripts (`forge script`) for reproducible deployments
+
 ## Code Quality and Style
 
 1. Absolute and named imports only — no relative (`..`) paths
@@ -51,7 +62,7 @@ function testMyTest() {
 }
 ```
 
-Additionally, write invariant (stateful) fuzz tests for core protocol properties. Use invariant-driven development: identify O(1) properties that must always hold and encode them directly into core functions ([FREI-PI pattern](https://www.nascent.xyz/idea/youre-writing-require-statements-wrong)). Use a multi-fuzzing setup like [Chimera](https://github.com/Recon-Fuzz/chimera) to run the same invariant suite across Foundry, Echidna, and Medusa — different fuzzers find different bugs.
+Additionally, write invariant (stateful) fuzz tests for core protocol properties. Use the [FREI-PI pattern](https://www.nascent.xyz/idea/youre-writing-require-statements-wrong) to encode O(1) properties directly into core functions. Use [Chimera](https://github.com/Recon-Fuzz/chimera) for multi-fuzzer setups (Foundry + Echidna + Medusa).
 
 4. Functions should be grouped according to their visibility and ordered:
 
@@ -100,64 +111,7 @@ Modifiers
 Functions
 ```
 
-7. Use the branching tree technique when creating tests
-Credit for this to [Paul R Berg](https://x.com/PaulRBerg/status/1682346315806539776)
-
-- Target a function
-- Create a `.tree` file
-- Consider all possible execution paths 
-- Consider what contract state leads to what path
-- Consider what function params lead to what paths
-- Define "given state is x" nodes
-- Define "when parameter is x" node 
-- Define final "it should" tests
-
-Example:
-```
-├── when the id references a null stream
-│   └── it should revert
-└── when the id does not reference a null stream
-    ├── given assets have been fully withdrawn
-    │   └── it should return DEPLETED
-    └── given assets have not been fully withdrawn
-        ├── given the stream has been canceled
-        │   └── it should return CANCELED
-        └── given the stream has not been canceled
-            ├── given the start time is in the future
-            │   └── it should return PENDING
-            └── given the start time is not in the future
-                ├── given the refundable amount is zero
-                │   └── it should return SETTLED
-                └── given the refundable amount is not zero
-                    └── it should return STREAMING
-```
-
-Example:
-```solidity
-function test_RevertWhen_Null() external {
-    uint256 nullStreamId = 1729;
-    vm.expectRevert(abi.encodeWithSelector(Errors.SablierV2Lockup_Null.selector, nullStreamId));
-    lockup.statusOf(nullStreamId);
-}
-
-modifier whenNotNull() {
-    defaultStreamId = createDefaultStream();
-    _;
-}
-
-function test_StatusOf()
-    external
-    whenNotNull
-    givenAssetsNotFullyWithdrawn
-    givenStreamNotCanceled
-    givenStartTimeNotInFuture
-    givenRefundableAmountNotZero
-{
-    LockupLinear.Status actualStatus = lockup.statusOf(defaultStreamId);
-    LockupLinear.Status expectedStatus = LockupLinear.Status.STREAMING;
-    assertEq(actualStatus, expectedStatus);
-}
-```
+7. Use the branching tree technique when creating tests — see [BRANCHING-TREE.md](BRANCHING-TREE.md) for the full pattern with examples
 
 8. Prefer strict pragma versions for contracts, and floating pragma versions for tests, libraries, abstract contracts, interfaces, and scripts. Use `0.8.34` or later as the minimum version — versions `0.8.28` through `0.8.33` have a [high-severity transient storage bug](https://soliditylang.org/blog/2026/02/18/solidity-0.8.34-release-announcement/) where the IR pipeline (`--via-ir`) can emit `sstore` instead of `tstore` (and vice versa) when clearing storage, causing writes to the wrong storage domain.
 
@@ -176,79 +130,42 @@ function test_StatusOf()
     - This includes in your deploy scripts. We should always use `forge script <path> --account $ACCOUNT --sender $SENDER` for our deploy scripts, and never use `vm.envUnit()` in our scripts.
     - For hardhat, you want to use hardhat [encrypted keystores](https://hardhat.org/docs/plugins/hardhat-keystore)
 
-12. Whenever a smart contract is deployed that is ownable or has admin properties (like, `onlyOwner`), the admin must be a multisig from the very first deployment — never use the deployer EOA as admin (testnet is the only acceptable exception). See [Trail of Bits: Maturing Your Smart Contracts Beyond Private Key Risk](https://blog.trailofbits.com/2025/06/25/maturing-your-smart-contracts-beyond-private-key-risk/) — "Layer 1" (single EOA) governance is no longer acceptable for DeFi.
+12. Whenever a smart contract is deployed that is ownable or has admin properties (like, `onlyOwner`), the admin must be a multisig from the very first deployment — never use the deployer EOA as admin (testnet is the only acceptable exception). See [Trail of Bits](https://blog.trailofbits.com/2025/06/25/maturing-your-smart-contracts-beyond-private-key-risk/).
 
-13. Don't initialize variables to default values
+### Gas and Style Checklist
 
-```solidity
-// good
-uint256 x;
-bool y;
+- Don't initialize variables to default values (`uint256 x;` not `uint256 x = 0;`)
+- Prefer named return variables to omit declaring local variables
+- Prefer `calldata` instead of `memory` for read-only function inputs
+- Don't cache `calldata` array length — calldata length is cheap to read
+- Modify input variables instead of declaring an additional local variable when the original value doesn't need to be preserved
+- Don't copy an entire struct from storage to memory if only a few slots are required
+- Remove unnecessary "context" structs and/or remove unnecessary variables from context structs
+- Pack storage: align struct/variable declarations to minimize storage slots; co-locate variables that are frequently read or written together
 
-// bad
-uint256 x = 0;
-bool y = false;
-```
+13. Cache unchanging storage slots to prevent identical storage reads; pass cached values to internal functions
 
-14. Prefer using named return variables if this can omit declaring local variables
+14. Revert as quickly as possible; perform input checks before checks which require storage reads or external calls
 
-```solidity
-// good
-function getBalance() external view returns (uint256 balance) {
-    balance = balances[msg.sender];
-}
+15. Use `msg.sender` instead of `owner` inside `onlyOwner` functions
 
-// bad
-function getBalance() external view returns (uint256) {
-    uint256 balance = balances[msg.sender];
-    return balance;
-}
-```
-
-15. Prefer `calldata` instead of `memory` for read-only function inputs
-
-16. Don't cache `calldata` array length
-
-```solidity
-// good — calldata length is cheap to read
-for (uint256 i; i < items.length; ++i) { }
-
-// bad — unnecessary caching for calldata
-uint256 len = items.length;
-for (uint256 i; i < len; ++i) { }
-```
-
-17. Reading from storage is expensive — prevent identical storage reads by caching unchanging storage slots and passing/using cached values
-
-18. Revert as quickly as possible; perform input checks before checks which require storage reads or external calls
-
-19. Use `msg.sender` instead of `owner` inside `onlyOwner` functions
-
-20. Use `SafeTransferLib::safeTransferETH` instead of Solidity `call()` to send ETH
-
-21. Modify input variables instead of declaring an additional local variable when an input variable's value doesn't need to be preserved
+16. Use `SafeTransferLib::safeTransferETH` instead of Solidity `call()` to send ETH
 
-22. Use `nonReentrant` modifier before other modifiers
+17. Use `nonReentrant` modifier before other modifiers
 
-23. Use `ReentrancyGuardTransient` for faster `nonReentrant` modifiers. Requires `pragma solidity ^0.8.34;` — do not use with `0.8.28`–`0.8.33` due to the transient storage clearing bug.
+18. Use `ReentrancyGuardTransient` for faster `nonReentrant` modifiers. Requires `pragma solidity ^0.8.34;` — do not use with `0.8.28`–`0.8.33` due to the transient storage clearing bug.
 
-24. Prefer `Ownable2Step` instead of `Ownable`
+19. Prefer `Ownable2Step` instead of `Ownable`
 
-25. Don't copy an entire struct from storage to memory if only a few slots are required
+20. For non-upgradeable contracts, declare variables as `immutable` if they are only set once in the constructor
 
-26. Remove unnecessary "context" structs and/or remove unnecessary variables from context structs
+21. Enable the optimizer in `foundry.toml`
 
-27. When declaring storage and structs, align the order of declarations to pack variables into the minimum number of storage slots. If variables are frequently read or written together, pack them in the same slot if possible
+22. If modifiers perform identical storage reads as the function body, refactor modifiers to internal functions to prevent identical storage reads
 
-28. For non-upgradeable contracts, declare variables as `immutable` if they are only set once in the constructor
+23. Use Foundry's encrypted secure private key storage instead of plaintext environment variables
 
-29. Enable the optimizer in `foundry.toml`
-
-30. If modifiers perform identical storage reads as the function body, refactor modifiers to internal functions to prevent identical storage reads
-
-31. Use Foundry's encrypted secure private key storage instead of plaintext environment variables
-
-32. Upgrades: When upgrading smart contracts, do not change the order or type of existing variables, and do not remove them. This can lead to storage collisions. Also write tests for any upgrades.
+24. Upgrades: When upgrading smart contracts, do not change the order or type of existing variables, and do not remove them. This can lead to storage collisions. Also write tests for any upgrades.
 
 ## Deployment
 
@@ -258,27 +175,7 @@ Example: use a shared base script that both tests and production inherit from, l
 
 ## Governance
 
-Use [safe-utils](https://github.com/Recon-Fuzz/safe-utils) or equivalent tooling for governance proposals. This makes multisig interactions testable, auditable, and reproducible through Foundry scripts rather than manual UI clicks. If you must use a UI, it's preferred to keep your transactions private, using a UI like [localsafe.eth](https://github.com/Cyfrin/localsafe.eth).
-
-Write fork tests that verify expected protocol state after governance proposals execute. Fork testing against mainnet state catches misconfigurations that unit tests miss — for example, the [Moonwell price feed misconfiguration](https://rekt.news/moonwell-rekt) would have been caught by a fork test asserting correct oracle state post-proposal.
-
-```solidity
-// good - fork test verifying governance proposal outcome
-function testGovernanceProposal_UpdatesPriceFeed() public {
-    vm.createSelectFork(vm.envString("MAINNET_RPC_URL"));
-
-    // Execute the governance proposal
-    _executeProposal(proposalId);
-
-    // Verify expected state after proposal
-    address newFeed = oracle.priceFeed(market);
-    assertEq(newFeed, EXPECTED_CHAINLINK_FEED);
-
-    // Verify the feed returns sane values
-    (, int256 price,,,) = AggregatorV3Interface(newFeed).latestRoundData();
-    assertGt(price, 0);
-}
-```
+See [GOVERNANCE.md](GOVERNANCE.md) for governance proposal patterns, fork testing examples, and multisig tooling recommendations.
 
 ## CI