@zigrivers/scaffold 3.25.1 → 3.27.0

package/README.md

@@ -29,7 +29,7 @@ Either way, Scaffold constructs the prompt and the target AI tool does the work.
 
 **Assembly engine** — At execution time, Scaffold builds a 7-section prompt from: system metadata, the meta-prompt, knowledge base entries, project context (artifacts from prior steps), methodology settings, layered instructions, and depth-specific execution guidance.
 
-**Knowledge base** — 235 domain expertise entries in `content/knowledge/` organized in eighteen categories (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension, research, data-science) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, rendering strategies, data stores, CLI patterns, game engines, library bundling, mobile deployment, batch and streaming pipelines, model training and serving, browser extension manifests and service workers, data-science reproducibility and notebook discipline, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
+**Knowledge base** — 267 domain expertise entries in `content/knowledge/` organized in nineteen categories (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension, research, data-science, web3) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, rendering strategies, data stores, CLI patterns, game engines, library bundling, mobile deployment, batch and streaming pipelines, model training and serving, browser extension manifests and service workers, data-science reproducibility and notebook discipline, smart-contract security and audit workflow, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
 
 **Methodology presets** — Three built-in presets control which steps run and how deep the analysis goes:
 - **deep** (depth 5) — all steps enabled, exhaustive analysis
@@ -368,7 +368,7 @@ Every `scaffold init` wizard question can be answered via CLI flags, making scaf
 | `--depth` | 1-5 | Custom methodology depth (requires `--methodology custom`) |
 | `--adapters` | comma-sep | AI adapters: claude-code, codex, gemini |
 | `--traits` | comma-sep | Project traits: web, mobile |
-| `--project-type` | string | web-app, mobile-app, backend, cli, library, game, data-pipeline, ml, browser-extension, research, data-science |
+| `--project-type` | string | web-app, mobile-app, backend, cli, library, game, data-pipeline, ml, browser-extension, research, data-science, web3 |
 | `--auto` | boolean | Non-interactive mode (uses Zod defaults for unset flags) |
 
 #### Web-App Config Flags (require `--project-type web-app` or auto-set it)
@@ -465,6 +465,14 @@ Data science has one forward-compatible config field in the schema, defaulted au
 |------|------|--------|
 | `dataScienceConfig.audience` | `solo` | Default (applied by the wizard and `--auto`). Covers the DS-1 audience (solo / small-team, local-first, prototyping). A future DS-2 release will extend the enum with `'platform'` (platform-engineered / larger-team DS) additively, without breaking existing configs. |
 
+#### Web3 Config (`--project-type web3`)
+
+Web3 has one forward-compatible config field in the schema, defaulted automatically — no CLI flags are needed in v1:
+
+| Config field | Values | Notes |
+|------|------|--------|
+| `web3Config.scope` | `contracts` | Default (applied by the wizard and `--auto`). Covers the W3-1 audience (smart-contract / protocol projects on EVM chains — Foundry / Hardhat). A future W3-2 release will extend the enum with `'dapp'` (web3 application / dApp) additively, without breaking existing configs. |
+
 #### Game Config Flags (require `--project-type game` or auto-set it)
 
 | Flag | Type | Values |
@@ -514,7 +522,7 @@ during assembly.
 
 - **Flag > auto > interactive**: Flags always take highest precedence. `--auto --engine unreal` uses defaults for everything except engine.
 - **Partial flags + interactive**: Provide some flags and the wizard asks only the remaining questions. `scaffold init --project-type game --engine unreal` prompts interactively for multiplayer, platforms, etc.
-- **Type-specific flags auto-set project type**: `--engine unity` automatically sets `--project-type game`, `--web-rendering ssr` sets `--project-type web-app`, `--backend-api-style rest` sets `--project-type backend`, `--cli-interactivity hybrid` sets `--project-type cli`, `--lib-visibility public` sets `--project-type library`, `--mobile-platform ios` sets `--project-type mobile-app`, `--pipeline-processing batch` sets `--project-type data-pipeline`, `--ml-phase training` sets `--project-type ml`, `--ext-manifest 3` sets `--project-type browser-extension`, `--research-driver code-driven` sets `--project-type research`. Error if conflicting type. (Data science currently has no dedicated CLI flags — pass `--project-type data-science` directly.)
+- **Type-specific flags auto-set project type**: `--engine unity` automatically sets `--project-type game`, `--web-rendering ssr` sets `--project-type web-app`, `--backend-api-style rest` sets `--project-type backend`, `--cli-interactivity hybrid` sets `--project-type cli`, `--lib-visibility public` sets `--project-type library`, `--mobile-platform ios` sets `--project-type mobile-app`, `--pipeline-processing batch` sets `--project-type data-pipeline`, `--ml-phase training` sets `--project-type ml`, `--ext-manifest 3` sets `--project-type browser-extension`, `--research-driver code-driven` sets `--project-type research`. Error if conflicting type. (Data science and web3 currently have no dedicated CLI flags — pass `--project-type data-science` or `--project-type web3` directly.)
 - **Cannot mix flag families**: `--web-rendering ssr --backend-api-style rest` is an error. Each flag family (`--web-*`, `--backend-*`, `--cli-*`, `--lib-*`, `--mobile-*`, `--pipeline-*`, `--ml-*`, `--research-*`, `--ext-*`, game) is exclusive.
 - **Validation**: `--depth` requires `--methodology custom`. `--online-services` requires `--multiplayer online` or `hybrid`. SSR/hybrid rendering is incompatible with static deploy target. Session auth requires server state (not static). ML inference projects must specify a serving pattern. Browser extensions must declare at least one capability (UI surface, content script, or background worker). Notebook-driven research cannot be fully autonomous.
 
@@ -610,6 +618,9 @@ scaffold init --auto --methodology deep --project-type research \
 # Solo / small-team data science project (reproducibility-first)
 scaffold init --auto --methodology deep --project-type data-science
 
+# Web3 smart-contract / protocol project (Foundry / Hardhat on EVM)
+scaffold init --auto --methodology deep --project-type web3
+
 # Multiplayer mobile game with Unity
 scaffold init --project-type game --methodology deep --auto \
   --engine unity --multiplayer online --target-platforms ios,android \
@@ -636,7 +647,7 @@ Scaffold supports **project-type overlays** — domain-specific knowledge and pi
 
 - **Injects domain knowledge** into existing pipeline steps (e.g., SSR caching strategies into `tech-stack`, API pagination patterns into `coding-standards`)
 
-The game overlay additionally adjusts step enablement, remaps artifact references, and adds dependency overrides (because game development has fundamentally different artifacts). The web-app, backend, CLI, library, mobile-app, data-pipeline, ML, browser-extension, research, and data-science overlays are **knowledge-only** — they inject domain expertise into existing steps without changing which steps run or how they depend on each other. The research type additionally supports **domain sub-overlays** (quant-finance, ml-research, simulation) that layer domain-specific knowledge on top of the core research overlay, and the backend type supports a `fintech` sub-overlay. Both research and backend accept `domain` as either a single string or an array (e.g. `domain: ['quant-finance', 'simulation']`) for stacking multiple sub-overlays; the wizard and CLI flags remain single-select in v1, so multi-domain stacking requires hand-editing `.scaffold/config.yml`.
+The game overlay additionally adjusts step enablement, remaps artifact references, and adds dependency overrides (because game development has fundamentally different artifacts). The web-app, backend, CLI, library, mobile-app, data-pipeline, ML, browser-extension, research, data-science, and web3 overlays are **knowledge-only** — they inject domain expertise into existing steps without changing which steps run or how they depend on each other. The research type additionally supports **domain sub-overlays** (quant-finance, ml-research, simulation) that layer domain-specific knowledge on top of the core research overlay, and the backend type supports a `fintech` sub-overlay. Both research and backend accept `domain` as either a single string or an array (e.g. `domain: ['quant-finance', 'simulation']`) for stacking multiple sub-overlays; the wizard and CLI flags remain single-select in v1, so multi-domain stacking requires hand-editing `.scaffold/config.yml`.
 
 Overlays are composable with methodology presets. An MVP web-app gets fewer steps at lower depth; a deep backend project gets exhaustive analysis of every architectural decision.
 
@@ -652,6 +663,7 @@ Overlays are composable with methodology presets. An MVP web-app gets fewer step
 | `browser-extension` | `browser-extension-overlay.yml` | 12 entries (architecture, manifest configuration, service workers, content scripts, cross-browser, store submission, testing, security) | Manifest version, UI surfaces, content script, background worker |
 | `research` | `research-overlay.yml` + domain sub-overlays | 25 entries (experiment loop, tracking, overfitting prevention, backtesting, risk metrics, architecture search, simulation) | Experiment driver, interaction mode, domain, experiment tracking |
 | `data-science` | `data-science-overlay.yml` | 13 entries (reproducibility, experiment tracking, notebook discipline, model evaluation, data versioning, dev environment, observability, project structure, conventions, requirements, security, testing, architecture) | Audience (`solo` default; `platform` reserved for DS-2) |
+| `web3` | `web3-overlay.yml` | 14 entries (Foundry tooling, smart-contract security, upgradeability, gas optimization, oracles, audit workflow, deployment, testing patterns, EVM fundamentals, ABI/interface design, event/log indexing, supply-chain) | Scope (`contracts` default; `dapp` reserved for W3-2) |
 | `game` | `game-overlay.yml` | 24 entries (engines, networking, audio, VR/AR, economy, save systems, certification) | Engine, multiplayer, platforms, economy, narrative, and 6 more |
 
 ### Game Development
@@ -737,7 +749,7 @@ These answers control which conditional steps activate. A single-player puzzle g
 
 #### Multi-type Detection
 
-`scaffold adopt` detects 11 project types from manifest files and directory layouts:
+`scaffold adopt` detects 12 project types from manifest files and directory layouts:
 
 | Type | Key Signals |
 |------|-------------|
@@ -752,6 +764,7 @@ These answers control which conditional steps activate. A single-player puzzle g
 | `browser-extension` | `manifest.json` with `manifest_version` field |
 | `research` | `program.md` + `results.tsv`, backtest/strategy files with trading deps, optimization deps + experiment dirs, simulation framework deps |
 | `data-science` | Marimo signals required (`marimo` dep or `.marimo.toml`); DVC (`dvc.yaml`, `.dvc/config`, `dvc` py dep) is supplementary evidence only. Low-tier; defers to `ml` / `research` / `data-pipeline` when those match at medium/high tier |
+| `web3` | `foundry.toml` or `hardhat.config.{ts,js,cjs,mjs}` (medium-tier); `remappings.txt`, `lib/forge-std` are supplementary low-tier signals. EVM-only scope. Library-collision boundary pinned by tiebreak (high-tier `library` wins over medium-tier `web3` for published-library Hardhat projects) |
 
 Each detector returns a confidence tier (high/medium/low) with evidence trails. Override detection with `--project-type <type>`.
 
@@ -1311,6 +1324,124 @@ At depth 1-3, reviews are Claude-only — still thorough with multiple passes, b
 - **At least one additional CLI** — Codex, Gemini, and/or Claude CLI. All three dispatched independently as MMR channels when available. Missing Codex or Gemini channels fall back to compensating Claude passes (labeled `[compensating: Codex-equivalent]` / `[compensating: Gemini-equivalent]`, single-source confidence); if Claude itself is unavailable, the review proceeds with the remaining channels — MMR does not compensate for a missing Claude channel.
 - **Valid authentication** — Scaffold checks before every dispatch (run `mmr config test` to pre-flight all three at once) and tells you if credentials need refreshing
 
+## Build Observability
+
+Build observability gives you a live view of what is happening during a multi-agent implementation run — who claimed what task, which decisions were made, where work is stalled, and whether the codebase conforms to your standards. All data lives under `.scaffold/` and never interferes with the normal pipeline.
+
+### Ledger events
+
+```bash
+scaffold observe event task_claimed   --task-id T-42 --task-title "Add auth flow"
+scaffold observe event decision_made  --task-id T-42 --decision "Use JWT" --rationale "Stateless auth for microservices"
+scaffold observe event task_completed --task-id T-42
+scaffold observe event pr_opened      --pr-number 17
+```
+
+Events are written to `.scaffold/activity.jsonl` (append-only, lockfile-safe). Each event is stamped with a worktree ID, actor label, branch, and ISO-8601 timestamp.
+
+### Progress snapshot
+
+```bash
+scaffold observe progress                       # terminal snapshot
+scaffold observe progress --replay              # full timeline with git/PR/test events fused in
+scaffold observe progress --no-stall-check      # suppress the Needs Attention surface
+scaffold observe progress --output=docs/status.md  # write to a custom path
+```
+
+`--replay` fuses the ledger with six adapter event streams (git, GitHub, MMR, pipeline state, test results, pipeline docs) into a chronological timeline. The "Needs Attention" surface fires when work appears stalled — unclaimed tasks, unreviewed PRs, unresolved blockers, or repeated lens skips.
+
+### Audit
+
+```bash
+scaffold observe audit                          # run all eight lenses (A–H)
+scaffold observe audit --scope=code             # lenses A–G (code conformance only)
+scaffold observe audit --scope=docs             # lens H (cross-document consistency only)
+scaffold observe audit --profile=full           # include LLM-graded Lens H sub-checks
+scaffold observe audit --lens G-decisions       # run a single lens
+scaffold observe audit --output=docs/audit.md   # write to a custom path
+```
+
+Eight lenses cover TDD evidence (A), acceptance-criteria coverage (B), coding-standards compliance (C), stack conformance (D), design-token usage (E), scope coverage (F), decision-log completeness (G), and cross-document consistency (H). Findings get stable IDs for cross-run tracking:
+
+```bash
+scaffold observe ack abc123 --note "accepted, tracked in INFRA-77"
+scaffold observe ack abc123 --status open       # reopen a previously acknowledged finding
+```
+
+`scaffold observe audit` exits 1 when the verdict is `blocked` (findings at or above `fix_threshold`). This makes it composable as a CI gate.
+
+### Automated fix flow
+
+```bash
+scaffold observe audit --fix
+```
+
+After the initial audit, Scaffold dispatches an AI agent for each blocking finding, verifies the fix, and writes a post-fix report:
+
+1. **Plan** — filter and sort blocking findings (P0 first, then by lens).
+2. **Dispatch** — spawn the configured fix agent (default: `claude -p`) with the finding prompt on stdin. Output is live-streamed so you see what the agent is doing.
+3. **Verify** — re-run the finding's lens to confirm the issue is resolved (up to `per_finding_max_attempts` retries).
+4. **Report** — run a full post-fix audit and write `docs/audits/<id>-postfix.{md,json}`.
+
+Press Ctrl-C at any time — Scaffold reverts any staged changes the fix agents made and re-applies your original WIP, leaving the working tree unchanged.
+
+Configure via `.scaffold/observability.yaml`:
+```yaml
+fix:
+  dispatcher_command: "claude -p"   # change to any CLI that reads stdin
+  timeout_s: 300
+  per_finding_max_attempts: 3
+```
+
+### Worktree harvest and teardown
+
+When running parallel agents in separate worktrees, collect their activity before removing the worktree:
+
+```bash
+# Harvest a live worktree's ledger into the central archive
+scaffold observe harvest --worktree=../my-feature-worktree
+
+# Rotate stale archive entries (worktrees that no longer exist)
+scaffold observe harvest --recover
+
+# Full teardown: harvest + remove worktree + delete branch
+scripts/teardown-agent-worktree.sh ../my-feature-worktree
+```
+
+Harvested events accumulate in `.scaffold/activity-archive/`. `--recover` scans for entries whose worktree is gone and rotates them into monthly `YYYY-MM.jsonl` archives.
+
+### Dashboard
+
+```bash
+scripts/generate-dashboard.sh
+```
+
+The generated dashboard includes "Build Progress" and "Audit" panels that refresh from the sidecar JSON files. Each panel shows stall signals, a timeline, findings by severity, and lens skip counts.
+
+### Phase-boundary audits
+
+`scaffold complete <step>` automatically runs a cross-document audit (Lens H) after completing any phase-boundary step — `user-stories`, `tech-stack`, `coding-standards`, `design-system`, `implementation-plan`, or `implementation-playbook`. The audit result is printed inline (`[audit] N findings (verdict=…) — see docs/audits/…`) but never blocks the state transition.
+
+Configure via `.scaffold/observability.yaml`:
+```yaml
+phase_audit:
+  enabled: true    # set false to disable
+  timeout_s: 60
+  detached: false  # true = fire-and-forget (non-blocking always)
+```
+
+### MMR `doc-conformance` channel
+
+```bash
+mmr review --channels=doc-conformance
+```
+
+Runs `scaffold observe audit` as a built-in MMR channel, mapping findings to MMR's Finding shape with stable composite location IDs (`<source_doc>::<lens_id>::<short_id>`). Disabled by default — enable per-project in `.mmr.yaml`:
+```yaml
+channels_enabled:
+  - doc-conformance
+```
+
 ## Methodology Presets
 
 Not every project needs all 60 steps. Choose a methodology when you run `scaffold init`:
@@ -1394,7 +1525,7 @@ scaffold dashboard
 
 ## Knowledge System
 
-Scaffold ships with 235 domain expertise entries organized in eighteen categories:
+Scaffold ships with 267 domain expertise entries organized in nineteen categories:
 
 - **core/** (26 entries) — eval craft, testing strategy, domain modeling, API design, database design, system architecture, ADR craft, security best practices, operations, task decomposition, user stories, UX specification, design system tokens, user story innovation, AI memory management, coding conventions, tech stack selection, project structure patterns, task tracking, CLAUDE.md patterns, multi-model review dispatch, review step template, dev environment, git workflow patterns, automated review tooling, vision craft
 - **product/** (5 entries) — PRD craft, PRD innovation, gap analysis, vision craft, vision innovation
@@ -1414,6 +1545,7 @@ Scaffold ships with 235 domain expertise entries organized in eighteen categorie
 - **browser-extension/** (12 entries) — Manifest V3, content scripts, service workers, cross-browser compatibility, extension security, store submission
 - **research/** (25 entries) — experiment loop architecture, parameter optimization, overfitting prevention, experiment tracking, security/sandboxing; domain knowledge for quant-finance (backtesting, risk metrics, market data, strategy patterns), ML-research (architecture search, ablation studies, evaluation), and simulation (engine integration, parameter spaces, compute management)
 - **data-science/** (13 entries) — reproducibility, experiment tracking, notebook discipline, model evaluation, data versioning, dev environment (Marimo/Jupyter/Hex), observability, project structure, conventions, requirements, security, testing, architecture
+- **web3/** (14 entries) — Foundry tooling and dev environment, smart-contract security and common vulnerabilities, upgradeability patterns, gas optimization, oracles and external data, audit workflow, deployment and verification, testing patterns, access control, EVM/contract architecture, conventions, project structure, requirements
 
 Each pipeline step declares which knowledge entries it needs in its frontmatter. The assembly engine injects them automatically. Knowledge files with a `## Deep Guidance` section are optimized for the CLI — only the deep guidance content is loaded into the assembled prompt, skipping the summary to avoid redundancy with the prompt text.
 
@@ -1622,7 +1754,7 @@ All build inputs live under `content/`:
 content/
 ├── pipeline/         # 60 meta-prompts organized by 16 phases (phases 0-15, including build)
 ├── tools/            # 10 tool meta-prompts (stateless, category: tool)
-├── knowledge/        # 235 domain expertise entries (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension, research, data-science)
+├── knowledge/        # 267 domain expertise entries (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension, research, data-science, web3)
 ├── methodology/      # 3 YAML presets (deep, mvp, custom)
 └── skills/           # Skill templates with {{markers}} for multi-platform resolution (includes mmr)
 ```

package/content/knowledge/web3/web3-access-control.md

@@ -0,0 +1,189 @@
+---
+name: web3-access-control
+description: Role-based access control for smart contracts — Ownable2Step, OpenZeppelin AccessControl, Safe multisig as admin, TimelockController on dangerous ops, role separation, and decentralization via renouncing
+topics: [web3, access-control, openzeppelin, multisig, timelock]
+---
+
+Most contract exploits are not novel cryptography — they are either missing access-control checks ("anyone can call `setFeeRecipient`") or a single admin key getting drained, phished, or coerced. Access control is the answer to three questions: who can change what, when can they change it, and whose consent is required to authorize the change. A protocol whose answer is "the deployer EOA, immediately, alone" is a protocol one phishing email away from a post-mortem. Production-grade access control replaces each of those answers with a deliberate engineering choice: granular roles, time-locked execution windows, and multi-party signing.
+
+## Summary
+
+Default to OpenZeppelin's `AccessControl` over `Ownable` for anything heading to mainnet — multiple narrow roles beat one omnipotent owner, and revocation lets you respond to a key compromise without a redeploy. When you do need single-admin semantics in an early prototype, use `Ownable2Step` not raw `Ownable`, so a fat-fingered transfer to a wrong address cannot brick your protocol. The admin role itself should live on a Safe multisig — 2-of-3 minimum, 3-of-5 typical for serious TVL — with signers on different hardware in different physical locations. Wrap every irreversible operation (upgrades, treasury drains, fee-cap changes, oracle swaps) in a `TimelockController` with a 24–72 hour delay so users can exit if a malicious or compromised proposal lands. Separate `MINTER_ROLE`, `PAUSER_ROLE`, `UPGRADER_ROLE`, and `TREASURER_ROLE` to distinct multisigs where the budget allows, and renounce roles you no longer need once decentralization milestones are reached.
+
+## Deep Guidance
+
+### Ownable vs AccessControl
+
+`Ownable` gives you exactly one privileged address — the `owner` — and one modifier, `onlyOwner`. That is fine for a hackathon contract or a private prototype. It is wrong for anything production-bound, because every privileged operation in your protocol now collapses to the same key: pausing, upgrading, withdrawing treasury, rotating oracle, minting. Compromise that key and the attacker gets everything in one transaction.
+
+The post-mortem pattern is depressingly consistent: protocol launches with `Ownable` and a single key on a laptop, team plans to "migrate to a multisig later," the migration keeps slipping because nothing is on fire, the laptop is compromised, attacker calls every `onlyOwner` function in a single transaction, protocol is drained. The fix is not "be more careful with the key" — it is to never have a contract whose privileged surface is one key in the first place.
+
+`AccessControl` from OpenZeppelin gives you `bytes32`-identified roles, each independently grantable and revocable, gated by an `onlyRole(ROLE)` modifier. The `DEFAULT_ADMIN_ROLE` controls grants and revocations; everything else is whatever you define. Default to `AccessControl` for production:
+
+```solidity
+import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
+
+contract Protocol is AccessControl {
+    bytes32 public constant MINTER_ROLE   = keccak256("MINTER_ROLE");
+    bytes32 public constant PAUSER_ROLE   = keccak256("PAUSER_ROLE");
+    bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
+
+    constructor(address admin) {
+        _grantRole(DEFAULT_ADMIN_ROLE, admin); // admin can grant/revoke others
+    }
+
+    function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE) {
+        // ...
+    }
+}
+```
+
+`AccessControl` also gives you `hasRole(role, account)` for off-chain queries (your indexer, your dashboard, your audit checklist), `getRoleAdmin(role)` for understanding the grant hierarchy, and the standard `RoleGranted` / `RoleRevoked` / `RoleAdminChanged` events for the kind of monitoring an EOA owner cannot offer. The auditability of the system is itself a security property — when every grant lands as an indexed event, missing or unexpected role grants are observable, not invisible.
+
+`Ownable` makes sense in exactly one narrow case: a brand-new contract where you genuinely have only one privileged action and you will migrate to `AccessControl` before mainnet. Anything else, reach for `AccessControl` from the first commit.
+
+The two are not mutually exclusive at the protocol level — you can have an `Ownable2Step` factory that deploys `AccessControl`-based clones — but pick one as the canonical access pattern for any given contract. Mixing `onlyOwner` and `onlyRole(DEFAULT_ADMIN_ROLE)` in the same contract is a footgun: reviewers have to mentally re-derive which check actually gates a given function, and a future maintainer will inevitably gate one function with the wrong modifier.
+
+### Two-step ownership transfer (Ownable2Step)
+
+If you must use `Ownable`, use `Ownable2Step`. Raw `Ownable.transferOwnership(newOwner)` is a single-call transfer: type the wrong address (zero-knowledge-proof copy-paste hash, address with one character flipped, an address that is actually a contract that cannot accept ownership) and your protocol is now owned by a black hole. There is no recovery.
+
+`Ownable2Step` requires the recipient to actively `acceptOwnership` in a second transaction:
+
+```solidity
+import {Ownable2Step, Ownable} from "@openzeppelin/contracts/access/Ownable2Step.sol";
+
+contract Treasury is Ownable2Step {
+    constructor(address initialOwner) Ownable(initialOwner) {}
+    // existing owner calls transferOwnership(newOwner); pendingOwner = newOwner
+    // newOwner calls acceptOwnership(); owner = newOwner, pendingOwner = 0
+}
+```
+
+The pending-owner pattern means a wrong address simply never accepts, the transfer expires harmlessly, and you try again. Never deploy raw `Ownable` to mainnet — the fat-fingering risk is real and the cost of `Ownable2Step` is one extra transaction at handoff time. The same two-step pattern applies inside `AccessControl` for admin-role transfers: grant the new admin first, verify they hold the role, then revoke the old one. Atomic role swaps with no overlap are the same hazard as one-step ownership transfers.
+
+Real-world incidents have happened where a team intended to transfer ownership to a multisig but pasted an address that was actually a contract with no payable fallback, or an address from the wrong network's deployment — in both cases the new owner could neither act on the contract nor recover from the mistake. Two-step transfer makes both classes of error visible during the pending window: the recipient calls `acceptOwnership` from the intended address or the handoff fails safely.
+
+A quick decision tree for new contracts:
+
+- One privileged action, prototype scope, throwaway deploy → `Ownable` is fine.
+- One privileged action, mainnet deploy, single admin → `Ownable2Step` only.
+- Two or more privileged actions, or any mainnet deploy with meaningful TVL → `AccessControl`.
+- Any contract that may be upgraded later → `AccessControl` from day one, because retrofitting roles into a deployed `Ownable` contract via upgrade is painful and error-prone.
+
+### Roles via OpenZeppelin AccessControl
+
+Roles are `bytes32` identifiers, by convention `keccak256("ROLE_NAME")`. Define each role as a `public constant` so off-chain tooling can read it from the ABI. Use `_grantRole` and `_revokeRole` inside the constructor or admin functions; user-facing grants go through `grantRole(role, account)` which is gated by the role's admin (defaults to `DEFAULT_ADMIN_ROLE`). Never hand-compute the bytes32 literal in code reviews — paste the keccak256 call instead, because reviewers compare role definitions across files by their string name, not by their hash.
+
+```solidity
+bytes32 public constant TREASURER_ROLE = keccak256("TREASURER_ROLE");
+
+constructor(address adminMultisig, address treasurerMultisig) {
+    _grantRole(DEFAULT_ADMIN_ROLE, adminMultisig);
+    _grantRole(TREASURER_ROLE, treasurerMultisig);
+}
+
+function withdrawFees(address to, uint256 amount) external onlyRole(TREASURER_ROLE) {
+    // ...
+}
+```
+
+A subtle hazard with `_grantRole` in constructors: if you grant `DEFAULT_ADMIN_ROLE` to two addresses (say, an EOA deployer and the eventual multisig), you have just doubled your attack surface for the entire lifetime of the contract. Grant exactly one admin from the constructor, then have that admin perform any further grants in a subsequent transaction so the on-chain history records each privilege handoff as a distinct event.
+
+Set distinct admin roles per role with `_setRoleAdmin(MINTER_ROLE, MINTER_ADMIN_ROLE)` when you want minter grants to require a different multisig than the protocol-wide admin. That extra layer is worth it for roles that are commonly granted (a permissioned launchpad granting minter rights to dozens of partners) so the global admin key is not constantly touched.
+
+Emit and index the standard `RoleGranted` and `RoleRevoked` events that `AccessControl` provides for free — your off-chain monitoring (Tenderly, OpenZeppelin Defender, custom indexer) should page on any role-membership change so an unexpected grant cannot land silently. Off-chain visibility is half the value of on-chain access control: a granted role nobody noticed is the same as an unconfigured permission. Pair this with a published `roles.md` listing the canonical holder of each role so the community can independently verify that on-chain reality matches the documented governance.
+
+A common mistake worth calling out explicitly: granting `DEFAULT_ADMIN_ROLE` to the `msg.sender` of the constructor when deploying from a CI script. The deployer EOA now permanently holds the protocol's most powerful role, and unless step two of your deploy script is a `grantRole(DEFAULT_ADMIN_ROLE, multisig)` followed by `renounceRole(DEFAULT_ADMIN_ROLE, msg.sender)` in the same forge script, you have a window where the deployer key gates everything. Bake the multisig address into the constructor or deploy script parameters and grant the admin role to the multisig directly from the constructor; never use the deployer EOA as a permanent admin.
+
+### Multisig (Safe)
+
+Every privileged role on mainnet goes behind a Safe — `safe.global`, formerly Gnosis Safe — never an EOA. A Safe is itself a smart contract that requires `M-of-N` signatures from configured signer addresses before executing any transaction. The trade-off is simple: an EOA owner is a single phishing email or compromised laptop away from a drained protocol; a 3-of-5 Safe survives any two signers being compromised or unavailable.
+
+Defaults worth memorizing:
+
+- **2-of-3** — minimum acceptable for any mainnet deployment with non-trivial value. Three signers, two required. Cheap to operate, survives one compromise.
+- **3-of-5** — typical for serious TVL. Five signers (ideally with operational diversity — different team members, different geographies, different hardware vendors), three required. Survives two compromises and tolerates one signer being on vacation.
+- **4-of-7 or 5-of-9** — for protocols with eight-or-nine-figure TVL or those acting as governance for a DAO treasury.
+
+Signer hygiene matters as much as the threshold. Every signer holds their key on a hardware wallet (Ledger, GridPlus, Keystone) — never a hot wallet, never a browser extension as the sole layer. Rotate signers when team members leave: `addOwnerWithThreshold` and `removeOwner` are governance operations, not afterthoughts. Publish the current signer set and threshold in your docs so users can verify the Safe matches your stated security model. The Safe should hold `DEFAULT_ADMIN_ROLE` and any sensitive operational role; passing `safe.address` as the admin in the constructor is the standard pattern.
+
+Two operational practices worth wiring up at deployment time:
+
+- **Rehearse a signing ceremony before mainnet.** Have every signer connect their hardware, review the transaction in Safe's UI, simulate via Tenderly, and sign — for a no-op transaction like a self-pause-and-unpause. The first time someone signs should not be the night of an incident, and unfamiliar tooling is how `_setImplementation` gets signed by accident.
+- **Threshold-aware time budget.** A 3-of-5 across three time zones means the realistic time-to-execute is hours, not minutes. Size your `Pausable` kill-switch on a tighter 2-of-3 ops Safe so emergency pauses are fast, and keep the slow `DEFAULT_ADMIN_ROLE` on the wider Safe.
+
+### Timelock (TimelockController)
+
+A multisig stops one compromised key. A timelock stops a compromised multisig — or, more commonly, a coerced one. `TimelockController` from OpenZeppelin sits between the multisig and the protocol: dangerous operations are first `schedule`d (recording the call hash and a delay), then `execute`d after the delay elapses. During the delay, the call is publicly visible on-chain; if it is malicious, users have time to exit.
+
+Coercion is the often-overlooked threat model. A 3-of-5 Safe defeats one or two compromised keys but does not defeat a court order, a physical threat to multiple signers in the same jurisdiction, or social-engineering of a quorum through a coordinated phishing campaign. The timelock buys 48 hours during which the broader community can observe the proposed action, raise the alarm, and exit positions even if every signer wanted the operation to land. It also creates a real audit trail for any future post-mortem about whether the operation was legitimate.
+
+```solidity
+import {TimelockController} from "@openzeppelin/contracts/governance/TimelockController.sol";
+
+// proposers: addresses that can schedule (typically the Safe multisig)
+// executors: addresses that can execute after delay (often address(0) for "anyone")
+// minDelay: seconds — 48 hours is typical for protocol-altering ops
+address[] memory proposers = new address[](1);
+proposers[0] = safeMultisig;
+address[] memory executors = new address[](1);
+executors[0] = address(0); // anyone can execute after the delay
+TimelockController timelock = new TimelockController(
+    48 hours,   // delay
+    proposers,
+    executors,
+    address(0)  // admin — set to 0 to lock the timelock's own params
+);
+```
+
+Note the `address(0)` admin: passing zero means the timelock cannot have its own parameters (delay, proposer set, executor set) changed after deployment except through the timelock itself. That bootstraps a system where any change to the timelock's own configuration has to go through the timelock's delay — including a change to the delay itself. Leaving the admin set to an EOA or even the Safe means the multisig can shorten the delay with no warning, defeating the whole point.
+
+Grant the protocol's `UPGRADER_ROLE`, `DEFAULT_ADMIN_ROLE`, or treasury-drain role to the `timelock` address, not to the Safe directly. The Safe proposes via `timelock.schedule(...)`; after 48 hours, anyone calls `timelock.execute(...)`. The pause kill-switch stays on the Safe directly (you cannot time-lock an emergency); the dangerous knobs are slow. Publish a monitoring feed of all scheduled operations — Tenderly Alerts, OpenZeppelin Defender, or a custom indexer — so users do not have to watch the mempool themselves.
+
+Calibrate the delay to your protocol's exit time. A lending market where users can withdraw collateral in one transaction can run a 24h timelock; a liquid-staking protocol with a 7-day unbonding queue needs a 7-day-plus timelock or users have no real exit window. The asymmetry to avoid: a 24h timelock on an upgrade whose effect users cannot exit from in 24h is security theater. Pair the timelock with an `OperationCancelled` event so the multisig can publicly back out of a proposal mid-window if it discovers a mistake, and so users can verify cancellations rather than guess.
+
+One pitfall worth noting: the timelock's `execute` permission. If `executors` is set to a specific address rather than `address(0)`, only that address can execute scheduled operations. Setting it to the multisig means a hostile multisig can simply refuse to execute a beneficial proposal it scheduled; setting it to `address(0)` means anyone can execute after the delay, which is almost always what you want — the multisig commits to the operation by scheduling it, and the community guarantees execution by being able to send the final transaction themselves.
+
+### Role separation
+
+Granular roles only matter if they are held by genuinely different parties. A `MINTER_ROLE`, `PAUSER_ROLE`, `UPGRADER_ROLE`, and `TREASURER_ROLE` all held by the same Safe collapse back to a single point of compromise — the ABI looks like role separation, but the on-chain reality is one key gating everything. Reviewers will spot this immediately; users may not, which is precisely the kind of asymmetry that destroys trust after an incident. Where the operational budget supports it, each role goes on a different multisig:
+
+- **`MINTER_ROLE`** — held by the issuance multisig, ideally with a `MAX_MINT_PER_PERIOD` cap enforced in-contract. Compromise mints tokens; it does not drain the treasury.
+- **`PAUSER_ROLE`** — held by an ops multisig with lower threshold (2-of-3) for faster incident response. Compromise pauses the protocol; it does not steal funds. Often paired with a `GUARDIAN_ROLE` that can pause but not unpause, so a noisy alert can trigger a halt without exposing the unpause power to the same hot key.
+- **`UPGRADER_ROLE`** — held by a governance multisig behind the timelock. Compromise of the multisig still requires waiting out the timelock with users watching. See `web3-upgradeability.md` for the proxy-admin coupling.
+- **`TREASURER_ROLE`** — held by a treasury multisig with the highest threshold and most conservative signer set. Withdrawals above a configured threshold should additionally require the timelock; small operational disbursements can bypass the delay.
+- **`FEE_RECIPIENT`** — often stored as an address rather than a role; restrict who can change it with `DEFAULT_ADMIN_ROLE` behind the timelock. The fee recipient is a common phishing target because a single-line config change can redirect every protocol fee — keep it slow.
+
+The principle: any single multisig compromise should bound the blast radius to one role's worth of damage. A pauser key getting phished should not drain the treasury.
+
+Smaller protocols routinely cannot afford four distinct multisigs with non-overlapping signers, and that is fine — collapse to two (an "ops" Safe for pause and an "admin" Safe for everything else) rather than one. Document the consolidation honestly in your security model: "we run a single 3-of-5 Safe for all privileged roles" is a defensible position with a clear risk profile; "we have four roles" while all four point at the same address is misleading documentation and an audit finding waiting to happen.
+
+In-contract caps are the complement to role separation: a `MINTER_ROLE` with a `MAX_MINT_PER_DAY` ceiling is materially safer than the same role without one, because a compromised minter cannot exceed the cap in a single block. Caps on the most blast-prone roles (mint rate, fee ceiling, oracle drift tolerance, withdrawal-from-treasury rate) are cheap to add at deploy time and very hard to bolt on after an incident.
+
+### Renouncing roles
+
+`renounceRole(role, msg.sender)` permanently removes the calling account from a role with no recovery. Use it deliberately at decentralization milestones — once the protocol parameters are frozen and the community is governing through a DAO contract, renounce `DEFAULT_ADMIN_ROLE` from the original deployer multisig so the role becomes uncallable. The on-chain renouncement is auditable proof that the team can no longer unilaterally change the protocol.
+
+Critically, `renounceRole` only removes the role from `msg.sender` — the caller. There is no way to renounce on behalf of someone else, which is deliberate: a stolen admin key cannot be "renounced out" by the rest of the team, only revoked through normal `revokeRole` machinery. Users sometimes confuse "the team renounced ownership" (a single account dropping its own role) with "the protocol is unowned" (no account holds the admin role). The two coincide only when the team is the sole admin and explicitly renounces. Verify on-chain via `hasRole(DEFAULT_ADMIN_ROLE, account)` for every previously-privileged address, not by reading a blog post.
+
+```solidity
+// after a governance vote moves admin to a DAO timelock:
+protocol.renounceRole(protocol.DEFAULT_ADMIN_ROLE(), originalDeployerMultisig);
+// future grants/revokes must go through the DAO
+```
+
+Two cautions. First, renouncing is irreversible: if you renounce the only admin and then discover you needed it for an upgrade, you have bricked the upgrade path. Stage decentralization — grant the new admin first, exercise it once on a no-op operation to prove it works, then renounce the old. Second, renounce specific roles, not blanket admin: an "immutable" stage usually still wants a pauser for emergencies. Audit each role independently and decide which ones are safe to surrender.
+
+A pragmatic decentralization ladder, in order of typical adoption:
+
+1. **Deploy with EOA as admin** for the launch week, when bugs are likeliest and fast iteration matters. Tolerable only because TVL is still capped by deposit limits.
+2. **Migrate admin to a small team Safe** (2-of-3) once the contract is stable enough that the team is no longer hot-fixing daily.
+3. **Add a `TimelockController` between the Safe and the protocol** for upgrade and treasury operations. Pause stays on the Safe directly.
+4. **Expand to a larger, more diverse Safe** (3-of-5 or 4-of-7) as TVL grows.
+5. **Migrate admin to a DAO governance contract** that itself proposes through the timelock, once the community is real and voting power is sufficiently distributed.
+6. **Renounce role-specific admin powers** as parameters are locked permanently (e.g., supply cap, fee ceiling) — turn dials into constants.
+
+Each step is a deliberate governance event with its own announcement, monitoring window, and rollback plan. Skipping straight from step 1 to step 6 is the "rugpull-by-incompetence" pattern that bricks more protocols than malicious admins do.
+
+See `web3-upgradeability.md` for how the proxy-admin role interacts with this access-control model, `web3-audit-workflow.md` for the operational checks an audit will run against your role wiring, and `web3-security.md` for the wider security layer this access-control model lives inside.

package/content/knowledge/web3/web3-architecture.md

@@ -0,0 +1,162 @@
+---
+name: web3-architecture
+description: EVM smart-contract architecture decisions — modular vs monolithic decomposition, OpenZeppelin baseline, state minimization, library vs inheritance, diamond pattern caveats, and external-call discipline
+topics: [web3, architecture, solidity, evm, openzeppelin]
+---
+
+This overlay targets **EVM** chains — Ethereum mainnet, the major L2s (Arbitrum, Optimism, Base, zkSync, Polygon zkEVM), and other EVM-compatible execution layers running Solidity 0.8.x bytecode. Non-EVM ecosystems (Solana / Anchor, Aptos and Sui / Move, Cosmos / CosmWasm) have fundamentally different storage, account, and execution models and are deliberately out of scope here; a future W3-2 overlay may cover dApp / frontend work and non-EVM runtimes. Architecture in this doc means the contract-side decisions a protocol lead makes before the first `forge build`: how to decompose, what to inherit, how state is laid out, and where the trust boundaries fall.
+
+## Summary
+
+Decompose by responsibility, not by cleverness: a protocol over ~500 LOC almost always wants multiple contracts (each under 500 LOC of behavior), a small single-purpose contract is fine as one file. Inherit from `OpenZeppelin` for every standard primitive — ERC20, ERC721, `AccessControl`, `Pausable`, `ReentrancyGuard` — never re-implement them. Pack storage so each `struct` fits the fewest 32-byte slots possible and mark deploy-time constants `immutable` (or `constant` for compile-time literals) — every saved SLOAD is real money for users. Reach for libraries when logic is pure utility callable from many contracts, and for inheritance when you want shared state and roles. Avoid the `diamond pattern` (EIP-2535) unless you genuinely hit the 24 KB code-size limit or need pluggable facets — it adds storage-layout and audit complexity most protocols never need.
+
+## Deep Guidance
+
+### EVM-only scope
+
+This doc assumes Solidity ≥0.8.20 targeting EVM bytecode. L2-specific quirks (precompile differences, calldata pricing on rollups, account abstraction on zkSync) are noted only where they change a decomposition decision. If your protocol must run on Solana or Move-based chains, the entire decomposition vocabulary here — contracts, libraries, inheritance, slots — does not translate, and you should not generalize from this overlay. The reverse direction is roughly safe: most of what works on Ethereum mainnet works on any EVM L2, with gas constants and finality assumptions adjusted; consult chain-specific docs before deploying anything that depends on `block.timestamp` granularity, opcode pricing, or `msg.sender == tx.origin`.
+
+### Modular vs monolithic decomposition
+
+The default rule is brutal and useful: **if the contract is over ~500 lines of behavior, split it.** Above that line, auditors stop being able to hold the whole thing in their head, your test surface explodes, and you start brushing against the 24 KB deployed-code limit. Below it, one contract is almost always the right answer — cross-contract calls cost ~2,600 gas of `CALL` overhead plus calldata, and every external surface is a new trust boundary you must reason about. Split along responsibility lines: a vault, an oracle adapter, and a fee router are three contracts; a single ERC20 with a mint guard is one. Per-contract LOC budget keeps each component reviewable, but more importantly it forces you to name the boundary — what does this contract own, what does it merely call?
+
+The tradeoffs to weigh consciously:
+
+| Concern             | Monolithic                                  | Modular                                       |
+|---------------------|---------------------------------------------|-----------------------------------------------|
+| Gas per user action | Cheapest — internal calls are JUMP          | +2,600 gas per `CALL` plus calldata          |
+| Upgradeability      | All-or-nothing redeploy                     | Swap one module without touching others       |
+| Audit surface       | One file, one storage layout                | Multiple interfaces, every boundary is review |
+| Code-size headroom  | Tight against 24 KB EIP-170 limit           | Each contract has its own 24 KB budget        |
+
+A useful heuristic: if two responsibilities never share storage and could be developed by different people without merge conflicts, they should be different contracts.
+
+Concrete worked example — a yield vault that supports multiple collateral types and a single fee recipient. Three contracts beat one:
+
+- `Vault.sol` — accounting for shares, deposits, withdrawals, share-price math. ERC4626-shaped.
+- `StrategyRegistry.sol` — maps each collateral asset to an approved strategy adapter; governance can rotate strategies without touching the vault.
+- `FeeRouter.sol` — collects performance fees, splits between protocol treasury and stakers; can be swapped to change fee policy.
+
+If you wrote that as one contract you would have ~800 lines, three independent governance flows tangled together, and every audit finding in one area would force re-review of the whole file. Three contracts gives you a 300 / 250 / 150 LOC split where each piece has one job and one storage layout. The gas cost of the extra `CALL`s — call it ~5,000 gas per deposit — is real but small relative to the SLOAD-heavy share accounting that dominates the transaction.
+
+### OpenZeppelin as baseline
+
+Never re-implement standard primitives. `OpenZeppelin` contracts have been audited dozens of times, formally verified in pieces, and are the de-facto reference implementations auditors expect to see. Inherit, don't fork:
+
+```solidity
+// src/Vault.sol
+pragma solidity 0.8.24;
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
+import {Pausable} from "@openzeppelin/contracts/utils/Pausable.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+
+contract Vault is ERC20, AccessControl, Pausable, ReentrancyGuard {
+    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
+    // ...
+}
+```
+
+The mental model: OZ is your standard library. If you find yourself writing `_transfer` or a `nonReentrant` modifier from scratch, stop. See `web3-access-control.md` for how role partitioning composes with `AccessControl`.
+
+Pin OZ to an exact minor version in `foundry.toml` (or `package.json` for Hardhat) and bump it deliberately — OZ ships breaking changes between majors (v4 → v5 reworked `AccessControl` initialization, removed `Ownable` defaults, and changed several event signatures). Track their security advisories; an audited OZ release is one of the few dependencies whose patch notes you should actually read on update. If you must override OZ internals, do so by overriding `_update`, `_mint`, or other documented hooks rather than copy-pasting the contract — every fork loses the next round of fixes.
+
+### State minimization
+
+Every storage slot is 20,000 gas to write the first time and 2,900 gas to update — at $50 ETH gas this is real money per user action. Two disciplines pay for themselves immediately. **First, pack structs to fit slots.** The EVM lays out storage in 32-byte (256-bit) slots; smaller types share a slot when declared contiguously:
+
+```solidity
+// 1 slot total — uint64 + uint64 + uint128 = 256 bits
+struct Position {
+    uint64 openedAt;        // timestamp fits in uint64 until year 584942417355
+    uint64 lastUpdatedAt;
+    uint128 amount;         // up to ~3.4e38 — plenty for most token amounts
+}
+
+// vs. the naive 3-slot version
+struct PositionBad {
+    uint256 openedAt;
+    uint256 lastUpdatedAt;
+    uint256 amount;
+}
+```
+
+**Second, use `immutable` for values fixed at deploy and `constant` for compile-time literals.** Both live in bytecode, not storage, so reads cost ~3 gas instead of ~2,100:
+
+```solidity
+contract Vault {
+    address public immutable asset;          // set once in constructor
+    uint256 public constant MAX_FEE_BPS = 500; // compile-time
+
+    constructor(address _asset) {
+        asset = _asset;
+    }
+}
+```
+
+A third habit worth naming: **prefer events over storage for log-shaped data**. If a value is consumed off-chain (UI, indexer, subgraph) and never read by another contract, emit an event instead of writing storage. Events are roughly an order of magnitude cheaper than `SSTORE` and don't bloat the state your node operators carry forever.
+
+One subtlety to watch: struct packing only works when fields are declared in order from smallest to largest within a 32-byte slot, and only for **value types** (uints, addresses, bools, bytes32). Dynamic types (`string`, `bytes`, arrays, mappings) always occupy their own slot regardless of position, so don't try to "pack" them. Use `forge inspect <Contract> storage-layout` (Foundry) or `hardhat-storage-layout` to dump the actual layout and verify your packing assumptions before you ship — guessing is how you end up with a 4-slot struct you thought was 1.
+
+### Libraries vs inheritance
+
+Solidity offers two reuse mechanisms and they answer different questions. A `library` is pure logic — no state, no inheritance hierarchy, called via `DELEGATECALL` (for `external` library functions) or inlined at compile (for `internal`). Use libraries when the logic is stateless and called from many contracts: math helpers, byte manipulation, signature recovery. The `using X for Y` syntax attaches library functions to a type for ergonomic call sites:
+
+```solidity
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+contract Vault {
+    using SafeERC20 for IERC20;
+
+    function withdraw(IERC20 token, address to, uint256 amount) external {
+        token.safeTransfer(to, amount); // resolves to SafeERC20.safeTransfer(token, to, amount)
+    }
+}
+```
+
+Use **inheritance** when you want shared state, roles, modifiers, or a partial implementation — `ERC20`, `AccessControl`, and `Pausable` all carry storage and require inheritance. Rule of thumb: stateless and reusable → library; stateful and specializable → base contract. Beware deep inheritance chains (more than three levels): C3 linearization, function-override resolution, and storage-layout ordering all become harder to reason about, and auditors will flag it. If your hierarchy looks like a Java class tree, refactor toward composition with internal helpers instead.
+
+Two further library-design notes worth remembering. **`internal` library functions are inlined** at the call site, so they cost nothing extra in deployed bytecode beyond the inlined ops — they are essentially free abstraction. **`external` library functions** are deployed as a separate contract and invoked via `DELEGATECALL`, which means they share the caller's storage layout and execution context but live at their own address; you must link the library at deployment time. For most utility code (math helpers, conversion, packing), `internal` is what you want — keep external libraries for genuinely large logic blocks where the deployment-size savings justify the linking step.
+
+### Diamond pattern (EIP-2535)
+
+The diamond pattern routes calls through a proxy to one of many "facet" contracts via a function-selector table, letting a single address expose effectively unlimited code. It is the answer when you genuinely need pluggable facets — large protocols like Aave v3 use related patterns — or when you are wedged against the **24 KB EVM contract-size limit** (EIP-170). For everything else it is over-engineering with real cost: storage layout is now governed by namespaced "diamond storage" patterns that auditors must reason about, upgrade flows multiply, and tooling support is uneven. Default to plain proxies or no upgradeability at all (see `web3-upgradeability.md`), and only adopt the `diamond pattern` after you have written down the specific facets you need and confirmed a simpler decomposition won't fit. Premature diamonds have shipped more bugs than they have prevented.
+
+A simple checklist before reaching for a diamond:
+
+1. Have you tried splitting into 2–3 plain contracts that share an interface? Most "we need a diamond" intuitions dissolve here.
+2. Is the 24 KB code-size limit a *current* problem, or a hypothetical future one? Don't pre-pay for a complexity tax you may never owe.
+3. Do you actually need to add new facets after deployment, or do you just want clean module boundaries? The latter is better served by separate contracts with explicit interfaces.
+4. Does your audit firm have diamond expertise on the team you'd hire? If not, you are also paying for their learning curve.
+
+### External call discipline
+
+Every `CALL` to another contract is a trust boundary — execution leaves your codebase and re-enters at the callee's whim. Two disciplines: type your external interactions through **interfaces**, not concrete types, and treat every external call as a reentrancy and revert risk (see `web3-security.md` for Checks-Effects-Interactions). Interfaces decouple deployment order, let you point at a mock in tests, and document the API surface in one place:
+
+```solidity
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+interface IUniswapV2Pair {
+    function getReserves() external view returns (uint112, uint112, uint32);
+}
+
+contract Adapter {
+    IERC20 public immutable token;
+    IUniswapV2Pair public immutable pair;
+    // ...
+}
+```
+
+Public/external functions are your API; everything else stays `internal` for gas (cheaper than `public`/`external` jumps) and composability. Document the external surface with NatSpec — `@notice`, `@param`, `@return` — because that is what auditors and integrators read first. For oracles and any data source you don't control, see `web3-oracles-and-external-data.md` for staleness, deviation, and fallback discipline.
+
+A final architectural habit: write the **interface file first**. Before implementing `Vault`, write `IVault.sol` with the function signatures, NatSpec, and custom errors you intend to expose. That file becomes the contract between your code and every integrator, and reviewing it before implementation forces you to commit to an API surface you can defend in audit. The implementation may evolve; the interface should not, except by versioning a new one alongside it.
+
+Three concrete external-call rules worth codifying as review checks:
+
+1. **Never `.call{value: x}("")` without checking the return value.** Solidity 0.8 will not auto-revert on a failed low-level call; you must `require(success, "transfer failed")` or use a custom error. Better still, use OZ's `Address.sendValue` which does it for you.
+2. **Wrap any function that hands execution to an external contract with `nonReentrant`**, even if you "know" the callee is trusted. Trust assumptions rot — an audited token today becomes a callback-injecting fork tomorrow.
+3. **Pull, don't push.** When sending value or tokens to a user-supplied address, prefer the pull-payment pattern (record an entitlement, let them withdraw) over pushing in the same transaction. One failing recipient cannot then brick a batch operation for everyone else. `web3-security.md` covers this in depth.
+
+Taken together, the architecture decisions in this doc compose: a modular layout makes role partitioning (`web3-access-control.md`) tractable, immutable interfaces make upgrades (`web3-upgradeability.md`) safer, and disciplined external-call boundaries make oracle integration (`web3-oracles-and-external-data.md`) something you can actually reason about. The point is not to memorize patterns — it is to make the constraints of the EVM (gas, code size, immutability, public mempool) visible in the shape of the code itself, so they show up at design time rather than during an audit two weeks before mainnet.