hex-audit 0.7.0 → 0.8.0

package/dist/skills/fuzz/references/handler-patterns.md

@@ -0,0 +1,222 @@
+# Handler Patterns
+
+Use this guide during Step 7.
+
+## Shape
+
+Each handler file should have two sections:
+
+- `Unclamped`: raw protocol-action functions that perform the target call with unrestricted parameters
+- `Clamped`: handlers that restrict arbitrary fuzz input into sensible, high-signal calls
+
+Both sections may be called by the fuzzer. The unclamped section is not just an internal helper layer: unclamped handlers are also direct fuzz entry points, specifically so the campaign can still hit edge cases that the clamped layer intentionally filters out.
+
+The clamped layer should stay thin and usually forward into the corresponding unclamped function. The unclamped layer should usually just perform the target call with the appropriate acting modifier.
+
+## Unclamped
+
+The `Unclamped` section is the raw-call layer.
+
+Use it to:
+
+- perform the real target function call with unrestricted parameters
+- expose edge-case behavior that clamped variants intentionally avoid
+- apply the correct acting modifier or caller role
+- stay as close as possible to a raw call wrapper
+
+These functions are meant to be called both:
+
+- directly by the fuzzer, with unrestricted parameters
+- indirectly by the clamped handlers, after those handlers have prepared sensible inputs
+
+Unclamped handlers should stay close to the actual protocol surface. They should usually be thin raw calls plus the necessary role modifier and call to internal specific properties, if applicable. "Unclamped" describes their role in the handler structure, not their Solidity visibility.
+
+### Caller Context
+
+Use the acting context that matches the real role here:
+
+- `asActor` for users
+- `asAdmin` for owner or admin operations
+- role-specific modifiers for keepers, operators, reward distributors, or liquidators
+
+If the scaffold lacks a needed role modifier, add it.
+
+This is required even for raw unclamped handlers. Unrestricted parameters do not mean unrestricted caller identity.
+
+## Clamped
+
+The `Clamped` section is the restricted-input layer of the handler.
+
+Use it to:
+
+- expose the small set of high-signal protocol actions that the fuzzer should call
+- normalize arbitrary fuzz inputs into values that can reach meaningful code paths
+- prepare derived values before dispatching into the unclamped implementation
+- prepare preconditions that the target action expects, then forward into the corresponding unclamped function whenever practical
+
+### Clamped Design
+
+Do not mirror the ABI mechanically if a higher-signal handler shape is better.
+
+Good transformations:
+
+- merge preparatory steps and the main user action into one handler if the protocol expects them together
+- split one overloaded or ambiguous flow into clearer variants if that improves coverage
+- derive parameters from current state when raw fuzzed values mostly cause trivial reverts
+
+### Clamped Input Handling
+
+Prefer semantic bounds over arbitrary caps. Clamp toward values that are realistic for the protocol and likely to reach meaningful state transitions.
+
+Use the helper functions from `utils/Clamp.sol` for this layer. Those helpers are part of the scaffold specifically so clamped handlers can bound fuzz inputs consistently with functions such as `clampBetween`, `clampLte`, `clampLt`, `clampGte`, and `clampGt`.
+
+Examples:
+
+- map arbitrary addresses to known actors with `toActor(...)` and `toActorNotCurrent(...)`
+- if a function expects a valid identifier such as an order id, position id, market id, or pool id, pick from known valid values instead of passing arbitrary garbage
+- if a function will pull ERC20s from the caller, bound the amount by the caller's token balance and set the needed approval before calling the unclamped function
+- bound spend amounts by balances or allowances
+- bound share burns by owned shares
+- bound deadlines so the call can reach meaningful code paths
+- use source constants and require guards when they expose real bounds
+
+Clamped handlers should usually avoid doing the raw protocol call inline. Prefer to finish argument preparation and then call the unclamped version.
+
+If the correct bound is unclear, keep the clamp loose and leave a targeted `// TODO: tighten bound`.
+
+### Donation Handlers
+
+- If the protocol manages native tokens, include a special `<Contract>_donateETH` handler that accepts an arbitrary amount and sends it to the protocol using `Actor.forceSendETH(...)`.
+- If the protocol manages ERC20 tokens, include a special `<Contract>_donateERC20` handler that accepts an arbitrary amount and (optionally) token address and sends it to the protocol.
+
+## Boundary-Value Stress Handlers
+
+For every clamped handler, generate **stress variants** that target the extremes of the input domain. Clamped handlers focus on "sensible" ranges to maximize meaningful state transitions, but bugs cluster at the boundaries those clamps filter out. Stress handlers exist to hit those boundaries.
+
+The approach is always the same: read the function's code path, identify where the math can degenerate, and write a handler that drives input to that boundary. There are four directions to check.
+
+### 1. Near-Zero / Sub-Unit Values
+
+When a code path involves division or decimal conversion, values near or below the divisor truncate to zero. This creates free-value bugs (user pays nothing, receives tokens) or division-by-zero reverts.
+
+**How to detect**: grep the target contracts for division (`/`), `mulDiv`, decimal scaling (`10**`, `1eN`), or conversion functions. Note the divisor. Any input smaller than that divisor will truncate.
+
+```solidity
+// Generic pattern: if the function divides by SCALE_FACTOR, test below it
+function contract_action_smallAmount(uint256 amount) public {
+    // Clamp to values near the truncation boundary
+    amount = clampBetween(amount, 1, SCALE_FACTOR);
+    contract_action(amount);
+}
+```
+
+### 2. Full-Amount / Max-State Operations
+
+Protocols often work fine for partial operations but break when the entire balance, debt, or supply flows through a single path. Generate handlers that use the maximum available amount from current state:
+
+```solidity
+function contract_fullWithdraw() public {
+    uint256 fullBalance = contract.balanceOf(actor);
+    if (fullBalance == 0) return;
+    contract_withdraw(fullBalance);
+}
+
+function contract_fullAction(uint256 auxParam) public {
+    uint256 maxAmount = contract.totalAvailable();
+    if (maxAmount == 0) return;
+    contract_action(maxAmount, auxParam);
+}
+```
+
+### 3. Type-Boundary Values
+
+Before writing handlers, grep the target contracts for storage variables that use types narrower than uint256 — `uint8`, `uint80`, `uint96`, `uint128`, `uint160`, or packed struct fields. When a value accumulates via uint256 arithmetic but is stored or cast to a narrower type, the truncation is invisible until the accumulated value exceeds the type's max.
+
+For each narrow-typed accumulator, create a handler that pushes values large enough to approach or exceed the type boundary through the accumulation path. Derive the bound from the type max (e.g., `type(uint80).max` is ~1.2e24), not from hardcoded protocol-specific constants.
+
+### How to Apply
+
+For each clamped handler, ask:
+1. Does this path involve division or scaling? → add a **near-zero** variant
+2. Can this be called with the full available amount? → add a **full-amount** variant
+3. Does this path write to a narrow-typed storage variable? → add a **type-boundary** variant
+
+Not every handler needs all three — only add variants where the code path has the relevant pattern.
+
+### Admin Handlers
+
+For admin/owner functions, always use the correct caller context:
+
+```solidity
+function protocol_setFee(uint256 fee) public asAdmin {
+    protocol.setFee(fee);
+}
+```
+
+Admin handlers must use `asAdmin` (or the appropriate role modifier) — not `asActor`. If no `asAdmin` modifier exists in the scaffold, add one that pranks as the contract owner.
+
+## Dispatcher for Secondary-Tier Functions
+
+Secondary-tier functions appear as `internal` stubs (prefixed `_`) in the Unclamped section, and a single public dispatcher at the end of the Clamped section. The dispatcher is a single clamped entry point that uses a `uint8 selector` parameter to pick which secondary function to call:
+
+
+```solidity
+function vault_secondary(uint8 selector, uint256 arg0, address arg1) public {
+    selector = uint8(selector % 3);
+    if (selector == 0) _vault_setPaused(arg0 > 0);
+    else if (selector == 1) _vault_setFee(arg0);
+    else _vault_setAdmin(arg1);
+}
+```
+
+The unclamped secondary functions are all `internal` and not direct fuzz entry points.
+
+This reduces the secondary functions' call frequency naturally — the fuzzer reaches them only when it happens to pick the matching selector value.
+
+Primary-tier functions get their own individual clamped + unclamped handlers as normal.
+
+## Example
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity >=0.6.2 <0.9.0;
+
+import "../Base.sol";
+import {Properties} from "../Properties.sol";
+
+/// @notice Handles the interaction with a specific contract
+abstract contract VaultHandler is Properties {
+
+    // ――――――――――――――――――――――――― Clamped ――――――――――――――――――――――――――
+
+    function vault_deposit_clamped(uint256 amount) public {
+        uint256 balance = token.balanceOf(actor);
+        if (balance == 0) return;
+        amount = clampBetween(amount, 1, balance);
+
+        vault_deposit(amount);
+    }
+
+	function vault_donateETH(uint256 amount) public {
+		if (actor.balance == 0) return;
+		amount = clampBetween(amount, 1, actor.balance);
+
+        Actor(actor).forceSendETH{value: amount}(address(vault));
+    }
+
+	function vault_donateERC20(uint256 amount) public {
+        uint256 balance = token.balanceOf(actor);
+        if (balance == 0) return;
+        amount = clampBetween(amount, 1, balance);
+
+		vm.prank(actor);
+        token.transfer(address(vault), amount);
+    }
+
+    // ―――――――――――――――――――――――― Unclamped ―――――――――――――――――――――――――
+
+    function vault_deposit(uint256 amount) public asActor {
+        vault.deposit(amount);
+    }
+}
+```

package/dist/skills/fuzz/references/hex-invariants.md

@@ -0,0 +1,102 @@
+# Hex invariants and fuzz properties
+
+Hex-only reference (not in upstream fizz). Read by `/fuzz` (Steps 3, 9 and 12), its Synthesizer, `/fuzz-sync` and `/fuzz-convert`.
+
+Always call the CLI as `npx --no-install hex …`. Never `npx hex …`: an unrelated npm package named `hex` exists, and `npx` would download and run it.
+
+## Where the inputs come from
+
+| Input | Command / file | Used for |
+|---|---|---|
+| Accepted invariants | `npx --no-install hex invariant list --status accepted --json` (saved to `{META_DIR}/hex-invariants.json` in Step 3) | The property list: one property per accepted invariant |
+| All invariants | `.hex/model/invariants.json` (`npx --no-install hex invariant list --json`) | Deduplicating proposals, the next free id |
+| Protocol model | `.hex/model/protocol.json` (`npx --no-install hex model show [section]`) | Actors, assets, privileges, accounting equations, state machines, risky flows |
+| Exact facts | `npx --no-install hex facts query <callers\|callees\|readers\|writers\|layout\|linearization\|entry-points\|reach\|function> [ref]` | Entry points, who writes a variable, storage layout, exact function ids |
+
+An invariant entry:
+
+```json
+{
+  "id": "INV-003",
+  "statement": "The vault's token balance is always at least totalAssets()",
+  "kind": "accounting",
+  "scope": { "contracts": ["Vault"], "functions": ["Vault.withdraw(uint256,address,address)"] },
+  "evidence": [{ "file": "src/Vault.sol", "line_start": 120, "line_end": 134 }],
+  "on_chain_enforced": false,
+  "status": "accepted",
+  "test": { "tool": "fizz", "property_id": "GL-01", "file": "test/fizz/Properties.sol", "status": "passing" },
+  "issue_id": "H-012"
+}
+```
+
+`test` and `issue_id` are optional. `kind` is one of `accounting`, `access`, `bound`, `monotonic`, `state-machine`, `liveness`, `economic`.
+
+## The tag in PROPERTIES.md
+
+`.hex/fuzz/PROPERTIES.md` keeps upstream's line format, with the invariant's id in parentheses right after the bold Spec ID:
+
+```markdown
+- [ ] **GL-01** (INV-003) — Solvency: the vault's token balance is always at least `vault.totalAssets()`. (Category: HIGH_LEVEL; Guarantee: SHOULD-HOLD — …; Priority: HIGH; Sources: CON-01)
+- [x] **SP-02** (INV-007) — After `vault_deposit`, `vault.totalSupply()` strictly increases. (Category: STATE_TRANSITION; Guarantee: EXPLORATORY; After: `vault_deposit`; Priority: HIGH; Sources: ST-01)
+```
+
+Rules:
+
+- Each Spec ID maps to exactly one invariant, and each accepted invariant gets one entry.
+- Never put anything between `- [ ] ` and `**GL-NN**`: `fizz_sync.js` and `/fuzz-convert` parse that prefix.
+- Anyone who edits a line (implementers flipping `[ ]` → `[x]`, `/fuzz-sync` flipping `[x]` → `[~]`) keeps the `(INV-NNN)` tag as it is.
+- An entry without a tag is fuzzed but not tracked in Hex. `hex invariant sync-fuzz` lists it as unmapped.
+
+Record each mapping when the entry is written:
+
+```bash
+npx --no-install hex invariant set-test INV-003 --tool fizz --property GL-01 --file test/fizz/Properties.sol --status not_written
+```
+
+`--file` is the file that holds the property function: `{SUITE_DIR}/Properties.sol` for both `GL-*` and `SP-*`.
+
+## Proposing an invariant
+
+Discovery agents find properties the auditor did not accept. Those are **proposals**. They are never fuzzed in the current run and never written to `PROPERTIES.md` or `property-plan.md`. They go to the auditor as proposed Hex invariants:
+
+1. Read the whole `.hex/model/invariants.json`: `{ "updated_at": "…", "invariants": [ … ] }`. If it does not exist, start from `{ "updated_at": "", "invariants": [] }`.
+2. Skip a candidate that restates an existing invariant of any status, rejected ones included (the auditor already ruled on those).
+3. Give each new entry the next free id: the highest `INV-NNN` number in the file plus one, zero-padded to three digits (`INV-014`), counting up for each further entry.
+4. Fill the entry:
+   - `statement`: one sentence, a property of the protocol and not of the harness ("users can always withdraw their full balance when not paused", not "property_x returns true").
+   - `kind`: map from fizz's discovery. Conservation and sum-of-parts are `accounting`. Bounds and rounding direction are `bound`. Monotonicity is `monotonic`. State validity and state transitions are `state-machine`. DoS, "can always withdraw" and liveness are `liveness`. Value extraction and profit are `economic`. Who may call what is `access`.
+   - `scope.contracts`: contract names. `scope.functions`: exact facts function ids (`Contract.fn(type,…)`, from `npx --no-install hex facts query function <name>`), or `[]` when unsure. A wrong id fails validation.
+   - `evidence`: `[{ "file": "src/…", "line_start": N, "line_end": M }]`, project-relative, pointing at the code that makes the property matter.
+   - `on_chain_enforced`: `true` only if a `require`/`assert`/`revert` in the code enforces it.
+   - `status`: `"proposed"`. Never `accepted`: only the auditor accepts.
+   - `rationale`: `"Proposed by /fuzz (<discovery source ids>): <why it should hold, or the doc/identity behind it>"`.
+5. Append the entries and write the whole file back. Keep every existing entry as it was and set `updated_at` to the current ISO time.
+6. Run `npx --no-install hex model validate` and fix what it reports.
+
+The auditor reviews proposals with `npx --no-install hex invariant list --status proposed` (or on the dashboard's Model page) and accepts with `npx --no-install hex invariant accept INV-014 …`. `/fuzz-convert` then adds properties for the newly accepted ones.
+
+## After every campaign: `hex invariant sync-fuzz`
+
+```bash
+cd {PROJECT_ROOT} && npx --no-install hex invariant sync-fuzz
+```
+
+It reads:
+
+- `.hex/fuzz/PROPERTIES.md`: Spec IDs, checkboxes and `(INV-NNN)` tags. An invariant whose `test.property_id` names the Spec ID is matched too.
+- The `/// @notice GL-NN:` doctags under the suite (`test/fizz/Properties.sol`, `test/fizz/handlers/*.sol`) to find each property's function. It takes the suite dir from `{META_DIR}/last-run.json` when that file exists.
+- The latest campaign logs: `{META_DIR}/corpus_medusa/medusa-run.log` (`run_medusa.js`), the newest file in `{META_DIR}/logs_medusa/` (a bare `medusa fuzz`), and `{META_DIR}/corpus_echidna/echidna-run.log` (`run_echidna.js`). Newer logs win.
+- `test_repro_<propertyFunction>` tests in `test/fizz/FoundryTester.sol`. A repro whose body still holds the `TODO: manual repro needed` marker does not count.
+
+It sets each mapped invariant's `test` (`tool: fizz`, `property_id`, `file`, `status`, `runs`, `last_run_at`, `repro_file`):
+
+| Status | When |
+|---|---|
+| `failing` | A repro exists, or the property's own test failed in the latest log that ran it |
+| `broken` | `[~]` (quarantined by `/fuzz-sync`), `[x]` with no tagged function, a quarantined function body, or the fuzzer could not evaluate it |
+| `passing` | `[x]`, it ran (its own test, or for `SP-*` the handlers that call it), and nothing failed |
+| `not_written` | `[ ]` or `[-]` |
+
+For each `failing` invariant that has a repro and no `issue_id`, it opens a High card (`Invariant broken: <statement>`, source `invariant`) and links it. It does not do this for rejected invariants. Running it again opens no duplicate cards.
+
+When an `SP-*` property's handler failed but no repro names the property, it reports the violation as **unattributed** and leaves the status unchanged, because several assertions can share a handler. Write `test_repro_<property>` to attribute it. Pass `--json` for the full summary.

package/dist/skills/fuzz/references/property-generation.md

@@ -0,0 +1,149 @@
+# Property Generation
+
+Common instructions for generating properties, ghost variables, snapshot state, and harness contracts after handlers are in place. These rules apply to both global properties and specific properties.
+
+This phase runs after handler generation. The agent reads the target contract source files and the generated handlers to produce:
+
+**Ghost variables** in `Base.sol` — track cumulative state not directly readable from the contract.
+**Ghost updates** wired into per-contract handler files (`handlers/<Contract>Handler.sol`).
+**Snapshot state** in `Snapshots.sol` — before/after state for delta-based properties.
+**Harness contracts** in `{SUITE_DIR}/harness/` — for accessing private/internal state when necessary.
+**Properties** in `Properties.sol` — global and function-specific invariant checks, called explicitly from handlers or shared helper functions.
+
+## 1. Naming convention
+
+All property functions must start with `property_` prefix.
+
+## 2. Ghost Variables
+
+### What they are
+
+Ghost variables track state that the contract doesn't expose directly but that is needed to write meaningful invariants. Common examples:
+
+- `ghosts.totalDeposited` — sum of all deposits across all actors
+- `ghosts.totalWithdrawn` — sum of all withdrawals
+- `ghosts.totalMinted` — cumulative minted amount
+- `ghosts.lastTimestamp` — timestamp of last state-changing call
+
+### Where they go
+
+In `Base.sol`, inside the `Ghosts` struct:
+
+```solidity
+struct Ghosts {
+    uint256 totalDeposited;
+    uint256 totalWithdrawn;
+    uint256 totalMinted;
+}
+```
+
+Replace the placeholder `uint256 _placeholder;` with real ghost variables.
+
+### How to choose ghosts
+
+Read the source contracts and identify:
+- **Accumulative operations**: deposits, withdrawals, mints, burns, transfers — track running totals.
+- **Counter operations**: number of users, number of positions — track counts.
+- **Extreme values**: max/min seen amounts — track with `max()`/`min()` in handlers.
+
+Only add ghosts that are needed by at least one property. Don't add speculative ghosts.
+
+### Wiring ghost updates into handlers
+
+Add ghost updates AFTER the external call in each handler (so they only execute on success).
+
+For clamped handlers that forward to unclamped: put ghost updates in the UNCLAMPED handler (since both clamped and direct fuzzer calls go through it).
+
+Ghost updates go in the per-contract handler files (`handlers/<Contract>Handler.sol`). Example:
+
+```solidity
+function vault_deposit(uint256 assets) public asActor {
+    assets = clampBetween(assets, 1, token.balanceOf(address(actor)));
+
+    vm.prank(address(actor));
+    vault.deposit(assets);
+
+    ghosts.totalDeposited += assets;
+}
+```
+
+## 3. Snapshot State
+
+### Purpose
+
+`Snapshots.sol` captures state before and after a handler call, enabling delta-based properties like "user balance decreased by exactly the deposit amount."
+
+### What to track
+
+Read the target contracts and populate the `State` struct with:
+- Key balances: `token.balanceOf(address)`, `contract.balanceOf(address)`
+- Protocol state: `totalSupply`, `totalAssets`, `totalShares`
+- Actor state: balances of the current actor
+
+Example:
+
+```solidity
+struct State {
+    uint256 actorTokenBalance;
+    uint256 vaultTotalAssets;
+    uint256 vaultTotalSupply;
+}
+
+function _takeSnapshot(State storage state) private {
+    state.actorTokenBalance = token.balanceOf(actor);
+    state.vaultTotalAssets = vault.totalAssets();
+    state.vaultTotalSupply = vault.totalSupply();
+}
+```
+
+Snapshot reads must NOT revert. Use try/catch for any call that could fail.
+
+### Wiring snapshots into handlers
+
+For handlers that need before/after comparison, call `snapshotBefore()` before the external call and `snapshotAfter()` after it. The full wiring sequence in an unclamped handler is:
+
+1. `snapshotBefore()` — capture state before the call
+2. External call — the actual protocol interaction
+3. `snapshotAfter()` — capture state after the call
+4. Ghost updates — track derived state (only executes on success)
+5. Property assertions — call specific properties that check deltas
+
+```solidity
+function vault_deposit(uint256 assets) public asActor {
+    snapshotBefore();
+
+    vm.prank(address(actor));
+    vault.deposit(assets);
+
+    snapshotAfter();
+    ghosts.totalDeposited += assets;
+    property_depositIncreasesShares(assets);
+}
+```
+
+Do NOT add snapshot calls to every handler — only where delta-based properties exist. They cost gas and slow fuzzing.
+
+## 4. Harness Contracts
+
+If a property requires access to `private` or `internal` state that is not reachable via the public interface, create a harness contract:
+
+- Place it at `{SUITE_DIR}/harness/{TargetContract}Harness.sol`
+- The harness inherits from the target contract and adds only the minimal getter(s) needed
+- Update `Base.sol` to declare and instantiate `{TargetContract}Harness` instead of `{TargetContract}` — the harness is ABI-compatible so handlers and properties continue to work unchanged
+- Only create a harness when strictly necessary — prefer public interface access
+
+## 5. Assertion helpers
+
+These are the assertion helpers from `utils/PropertiesAsserts.sol`:
+
+| Function | Check |
+|---|---|
+| `t(bool, string)` | assert true |
+| `eq(a, b, reason)` | `a == b` |
+| `neq(a, b, reason)` | `a != b` |
+| `gt(a, b, reason)` | `a > b` |
+| `gte(a, b, reason)` | `a >= b` |
+| `lt(a, b, reason)` | `a < b` |
+| `lte(a, b, reason)` | `a <= b` |
+
+All have both `uint256` and `int256` overloads. All emit descriptive failure events before `assert(false)`.

package/dist/skills/fuzz/references/selection-policy.md

@@ -0,0 +1,49 @@
+# Entry-Point Selection Policy
+
+Use this policy when creating the initial `entry-point-selection.json`.
+
+## Goal
+
+Select the smallest handler surface that still exercises the protocol's real state machine.
+
+## Prefer By Default
+
+- core user flows such as `deposit`, `withdraw`, `mint`, `redeem`, `borrow`, `repay`, `stake`, `unstake`, `swap`, `claim`
+- recurring permissioned flows such as `harvest`, `liquidate`, `rollover`, `notifyRewardAmount`, `rebalance`, `settle`
+- edge-case actions that plausibly break accounting, mode transitions, or fund safety
+
+## Exclude By Default
+
+- `view` and `pure` functions
+- one-time migration and bootstrap functions
+- internal plumbing exposed as `external` only for contract-to-contract calls
+- routine parameter setters that mostly tune config without creating meaningful state-machine pressure
+
+## Include Carefully
+
+Keep a permissioned or config-like action when one of these is true:
+
+- it changes fund routing, fee accounting, caps, oracle state, or collateral rules
+- it toggles pause, shutdown, or mode flags
+- sequencing it against user flows is plausibly dangerous
+- it is part of normal operations for keepers, liquidators, or reward distributors
+
+## Decision Heuristics
+
+For each candidate function, ask:
+
+1. Would a real user, admin, keeper, operator, or liquidator call this directly?
+2. Does this function create or unlock important state transitions?
+3. Would omitting it make the fuzz campaign miss an important lifecycle edge?
+4. Is it mostly internal wiring that should instead be exercised indirectly through another entry point?
+
+If confidence is low, prefer excluding protocol-internal plumbing and keeping the higher-signal external flows.
+
+## Tier Classification
+
+After selection, classify each included function as **primary** or **secondary**:
+
+- **Primary**: core user flows that the fuzzer should call frequently (deposit, withdraw, mint, redeem, borrow, repay, swap, stake, unstake, claim, liquidate, etc.)
+- **Secondary**: less common functions that are still useful but should be called less often (admin setters, configuration changes, pause/unpause, role grants, parameter tuning, etc.)
+
+Secondary functions are grouped into a dispatcher handler in Step 7, reducing their call frequency without excluding them entirely.

package/dist/skills/fuzz/references/setup-playbook.md

@@ -0,0 +1,92 @@
+# Setup Playbook
+
+Use this guide during Step 6 when wiring `Base.sol` and `Actor.sol`.
+
+## Base.sol FIXMEs
+
+The scaffolded `Base.sol` contract contains `FIXME` comments that indicate where protocol-specific setup logic should be implemented.
+
+Treat those `FIXME`s as required integration points.
+
+## Source Priority
+
+Look for existing project setup logic before inventing new deployment code.
+
+Read in this order when available:
+
+1. integration tests
+2. base test fixtures
+3. deployment scripts
+4. helper contracts used by tests
+
+If none of the above exist, scan for initialize() signatures and constructor arguments directly in source files.
+
+## Extract From Existing Setup
+
+- deployment order
+- constructor argument meaning
+- role grants and ownership transfers
+- initialization or upgrade calls
+- seed state such as approvals, liquidity, balances, oracle values, and reward funding
+
+## Good Defaults
+
+- reuse real in-protocol dependencies when the protocol already contains them
+- use mocks only for genuinely external systems or missing infrastructure
+- use mock contracts when appropriate for dependencies that are external to the protocol or unnecessarily complex for the harness
+- good mock candidates include external tokens, external oracles, and complex third-party contracts that are not the main subject of the fuzz campaign
+- when the missing dependency is a simple external ERC20 token, prefer the scaffolded `utils/MockERC20.sol` helper unless the project already contains a more faithful token mock
+- grant actors enough balances and approvals to reach meaningful state transitions
+- prefer deterministic constants over random setup branches
+
+## Upgradeable Contracts
+
+Before writing setup logic, check whether the target contracts use upgradeable proxies.
+
+Strong signals:
+
+- `_disableInitializers()` in a constructor
+- an `initialize()` function protected by `initializer`
+- versioned initialization functions protected by `reinitializer`
+
+If the contract is upgradeable:
+
+- use the project's proxy pattern such as `TransparentUpgradeableProxy` or `ERC1967Proxy`
+- deploy the implementation first, then the proxy with initialization calldata
+- use a dedicated proxy admin address that never calls implementation functions directly
+
+If the contract is not upgradeable, plain `new Contract(args)` deployment is fine.
+
+## Setup Checklist
+
+At minimum, wire:
+
+- deployment order
+- constructor arguments
+- proxy deployment and initialization when needed
+- registry or service-locator wiring
+- role grants and ownership transfers, including scoped roles when applicable
+- token approvals and seed balances
+- any required initialization calls
+- market, pool, or strategy configuration needed for handlers to reach meaningful states
+
+Deploy all in-protocol dependencies needed by the selected entry points, even if those dependencies do not get handlers.
+
+## Signature-Dependent Setup
+
+If selected entry points require cryptographic signatures such as signed prices, signed orders, or permit signatures:
+
+- store a known private key constant in `Base.sol` for the signer or publisher role
+- register the corresponding address as an approved signer during setup
+- expect handlers in Step 7 to use `vm.sign(privateKey, digest)` to construct valid payloads
+- if router-layer signature construction is too complex for the harness, consider targeting the underlying manager functions directly and document that tradeoff
+
+## TODO Rule
+
+Leave `// TODO` only when:
+
+- the dependency is truly external and the correct mock or fork source is project-specific
+- the constructor needs a business value that cannot be inferred safely
+- the protocol needs a privileged operational decision that should come from the user
+
+Every TODO should say what is missing and why it blocks a safe default.