validate-docs-section

name	validate-docs-section
description	Validate and perfect a Nethereum documentation section end-to-end. Use when working on docs sections (getting-started, core-foundation, signing, smart-contracts, defi, evm-simulator, devchain, account-abstraction, data-indexing, mud-framework, wallet-ui, consensus, client-extensions). Covers use case definition, NuGet README verification against source code with compilation, guide page creation, Claude Code plugin skill creation per use case, sidebar updates, and build verification. Trigger when user mentions validating docs, fixing a docs section, creating guides, or perfecting documentation for any Nethereum section.
argument-hint	["section-name"]

Validate Documentation Section

You are perfecting the documentation for a section of the Nethereum Docusaurus site. This is a staged workflow with user approval gates — never skip a gate.

Golden rule: ZERO HALLUCINATION. Every class name, method name, namespace, parameter, and code example must be verified against actual source code. Code examples must compile.

Paths

What	Path
Nethereum source	C:/Users/SuperDev/Documents/Repos/Nethereum/src/
Package READMEs	C:/Users/SuperDev/Documents/Repos/Nethereum/src/{Package}/README.md
Docusaurus docs	C:/Users/SuperDev/Documents/Repos/Nethereum.Documentation/docs/
Sync script	C:/Users/SuperDev/Documents/Repos/Nethereum.Documentation/scripts/sync-readmes.js
Sidebar config	C:/Users/SuperDev/Documents/Repos/Nethereum.Documentation/sidebars.ts
User skills plugin	C:/Users/SuperDev/Documents/Repos/Nethereum/plugins/nethereum-skills/skills/
Internal dev skills	C:/Users/SuperDev/Documents/Repos/Nethereum/.claude/skills/
Tests & examples	C:/Users/SuperDev/Documents/Repos/Nethereum/tests/
Doc example attribute	src/Nethereum.Documentation/NethereumDocExampleAttribute.cs
Playground	http://playground.nethereum.com
Progress tracking	C:/Users/SuperDev/Documents/Repos/Nethereum.Documentation/docs/{section}/PROGRESS.md

---

CRITICAL: Sidebar Structure Standard

Every section in sidebars.ts MUST follow this consistent structure:

{
  type: 'category',
  label: 'Section Name',
  items: [
    'section/overview',                    // 1. Overview page (always first)
    {
      type: 'category',
      label: 'Guide Sub-Group Name',       // 2. Guide categories (grouped by learning progression)
      collapsed: false,                     //    First group expanded, rest collapsed
      items: [
        'section/guide-topic-a',           //    Ordered for learner journey, NOT alphabetically
        'section/guide-topic-b',
      ],
    },
    // ... more guide sub-groups as needed
    {
      type: 'category',
      label: 'Package Reference',          // 3. Package Reference (ALWAYS last, ALWAYS this label)
      items: [
        'section/nethereum-package-a',     //    Auto-generated from READMEs via sync-readmes.js
        'section/nethereum-package-b',
      ],
    },
  ],
}

Rules

1. Overview always first — {section}/overview is the entry point
2. Guides grouped by learning progression — NOT one flat list. Group into sub-categories that reflect a learner's journey:
   • Essentials / Getting Started — the first things a learner needs (collapsed: false)
   • Deep Dives / Advanced — topics they explore after mastering essentials
   • Specialized — encoding, transport, infrastructure topics
3. Guide ordering within groups follows the learning path: What does a learner need first? What builds on what? Example: Query Balance → Unit Conversion → Fee Estimation → Send ETH (you need to understand balances before sending, units before fees, fees before sending)
4. Package Reference always last — all nethereum-*.md pages go here. These are auto-generated from READMEs and serve as API reference, not learning material
5. code-generation and similar reference-style pages go in the Guides group closest to their topic, not at the top level
6. Sub-groups within Package Reference are OK for large sections (e.g., JSON-RPC Transport, Networking, Storage providers)

Guide Sub-Group Examples (by section)

Core Foundation:

• Essentials: Query Balance, Unit Conversion, Fee Estimation, Send Ether, Send Transactions, Query Blocks
• Transaction Deep Dives: Transaction Types, Hash, Recovery, Replacement, Pending, Decode
• Keys, Signing & Encoding: Keys & Accounts, Message Signing, ABI, Hex, Address Utils, RLP
• Transport & Streaming: RPC Transport, Real-Time Streaming

Signing & Key Management:

• Guides: EIP-712 Signing, HD Wallets, Keystore, Hardware Wallets, Cloud KMS

Smart Contracts:

• Guides: Smart Contract Interaction, Deploy a Contract, ERC-20 Tokens, Code Generation, Events, Multicall, Error Handling, Built-in Standards, CREATE2

DevChain:

• Guides: DevChain Quickstart

Overview Must Link to Guides

Every overview.md MUST include a guide table at the bottom listing all guides in the section, grouped by sub-category. This is how learners discover guides from the overview page. Format:

## Guides

### Sub-Group Name

| Guide | What You'll Learn |
|---|---|
| [Guide Title](guide-slug) | One-line description |

---

CRITICAL: Simple Path First Structure

Every guide MUST lead with the simplest web3.Eth.* approach before showing advanced options. The design philosophy is: web3.Eth.* is a complete simple path for every common task. A developer should read the first 30 seconds of any guide, copy the simple code, and have it work — fees, nonce, gas all handled automatically. Deeper APIs are there when needed but never required.

The :::tip The Simple Way Pattern

Every guide that involves a web3.Eth operation MUST open with a tip callout showing 2-5 lines of the simplest working code:

:::tip The Simple Way
\`\`\`csharp
var receipt = await web3.Eth.GetEtherTransferService()
    .TransferEtherAndWaitForReceiptAsync("0xRecipient", 1.11m);
\`\`\`
That's it. Fees, gas, nonce — all automatic.
:::

Rules for the tip:

• Maximum 5 lines of code (excluding var web3 = ... setup)
• Must be a complete, working call — not a fragment
• Must explicitly state what's automatic ("Fees, gas, nonce — all automatic")
• For read-only guides, state: "No gas, signing, or fees needed — these are read-only calls."

Section Labeling for Advanced Content

Advanced or optional sections MUST be clearly labeled so beginners know they can skip them:

• "## More Control: Explicit Fee Parameters" — not just "## EIP-1559 Fee Parameters"
• "## Advanced: Transfer Entire Balance" — not just "## Transfer Entire Balance"
• "## Advanced: Find All Owned NFTs via Transfer Logs" — not just "### Find All Tokens Owned"
• Add intro text: "The sections below are optional — use them only when you need to override the automatic behavior."

The web3.Eth Simple Path Map

The overview page for any section that uses web3.Eth MUST include a simple path table. The Core Foundation reference table:

Task	Simple Path
Get ETH balance	web3.Eth.GetBalance.SendRequestAsync(address)
Get ERC-20 balance	web3.Eth.ERC20.GetContractService(addr).BalanceOfQueryAsync(owner)
Get ERC-721 balance	web3.Eth.ERC721.GetContractService(addr).BalanceOfQueryAsync(owner)
Send ETH	web3.Eth.GetEtherTransferService().TransferEtherAndWaitForReceiptAsync(to, amount)
Send transaction	web3.Eth.TransactionManager.SendTransactionAndWaitForReceiptAsync(input)
Get block	web3.Eth.Blocks.GetBlockWithTransactionsByNumber.SendRequestAsync(num)
Get transaction	web3.Eth.Transactions.GetTransactionByHash.SendRequestAsync(hash)
Get receipt	web3.Eth.Transactions.GetTransactionReceipt.SendRequestAsync(hash)
Convert units	Web3.Convert.FromWei(value) / Web3.Convert.ToWei(value)
Resolve ENS	web3.Eth.GetEnsService().ResolveAddressAsync("vitalik.eth")
Multicall batch	web3.Eth.GetMultiQueryHandler()
Delegate EOA (EIP-7702)	web3.Eth.GetEIP7022AuthorisationService().AuthoriseRequestAndWaitForReceiptAsync(contract)
Check if smart account	web3.Eth.GetEIP7022AuthorisationService().IsDelegatedAccountAsync(address)
Get delegate contract	web3.Eth.GetEIP7022AuthorisationService().GetDelegatedAccountAddressAsync(address)
Revoke delegation	web3.Eth.GetEIP7022AuthorisationService().RemoveAuthorisationRequestAndWaitForReceiptAsync()

Key message after the table: "For every row above, Nethereum handles gas estimation, nonce management, EIP-1559 fee calculation, and transaction signing automatically. You only override when you need to."

Built-in Services to Surface

The overview must mention these built-in typed services — no ABI needed:

• web3.Eth.ERC20 — balances, transfers, allowances, metadata
• web3.Eth.ERC721 — NFT ownership, metadata, enumeration
• web3.Eth.ERC1155 — multi-token balances and batch operations
• web3.Eth.GetEIP7022AuthorisationService() — EIP-7702 delegation lifecycle (delegate, check, get delegate, revoke)
• EIP7022SponsorAuthorisationService — sponsored delegation (another account pays gas)

Fee Estimation Framing

The fee estimation guide MUST open with: "Fees are automatic. You probably don't need this guide." The structure should be:

1. "The Default: You Probably Don't Need This Guide" — show zero-config transfer
2. "When You Need More Control" — scenarios that justify reading further
3. Strategy comparison table FIRST (so they can pick), then details for each
4. Legacy mode last

Read-Only Query Callouts

Any guide that covers read-only operations (balance queries, block queries, transaction lookups) MUST note: "These are all read-only queries — no gas, no signing, no fees needed."

EIP-7702 Service Coverage

EIP-7702 is a first-class Nethereum feature with dedicated high-level services. The EIP-7702 guide and any overview referencing it MUST surface the FULL lifecycle:

• Delegate — AuthoriseRequestAndWaitForReceiptAsync(contract)
• Check if smart account — IsDelegatedAccountAsync(address)
• Get delegate contract — GetDelegatedAccountAddressAsync(address)
• Revoke delegation — RemoveAuthorisationRequestAndWaitForReceiptAsync()
• Sponsored delegation — EIP7022SponsorAuthorisationService (sponsor pays gas)
• Batch sponsorship — AuthoriseBatchSponsoredRequestAndWaitForReceiptAsync(keys, contract)
• Inline authorization — attach AuthorisationList to any FunctionMessage to delegate + execute in one transaction
• Gas calculation — AuthorisationGasCalculator.CalculateGasForAuthorisationDelegation() (automatic in transaction manager)
• Hardware wallet/KMS support — all external signers support Type 4 via IEthExternalSigner.SignAsync()

Guide Table Completeness

The overview guide tables MUST list EVERY guide in the section. During Core Foundation validation, the EIP-7702 guide (sidebar_position 13) was missing from the Transaction Deep Dives table — this is the exact kind of gap to catch. After creating or updating any guide, verify it appears in the overview tables.

---

CRITICAL: Guide Quality Standard

A guide is NOT a code dump with headers. Every guide must teach, not just show.

What makes a guide vs a code dump

Code dump (BAD):

## Encode a String
\`\`\`csharp
var encoded = RlpEncoder.EncodeElement(dogBytes);
\`\`\`
## Encode an Integer
\`\`\`csharp
var encoded = RlpEncoder.EncodeElement(valueBytes);
\`\`\`

Guide (GOOD):

## Why RLP?

RLP is how Ethereum serializes data for the wire — transactions, blocks, and
state trie nodes are all RLP-encoded before hashing or transmitting. You'll
encounter RLP when building raw transactions, verifying Merkle proofs, or
working with the state trie directly.

Most developers never call RLP directly — `Web3` handles it for you when
sending transactions. Use these APIs when you need to:
- Build raw signed transactions offline
- Verify block header proofs
- Decode data returned by `debug_traceTransaction`

## Encode Structured Data

RLP handles two things: byte arrays and lists of byte arrays. Everything
in Ethereum gets reduced to one of these.

\`\`\`csharp
// Encode a string — first convert to bytes, then RLP-wrap
string dog = "dog";
byte[] encoded = RlpEncoder.EncodeElement(dog.ToBytesForRLPEncoding());
\`\`\`

The encoded output is `0x83646f67` — the prefix `0x83` means "byte string
of length 3", followed by the UTF-8 bytes of "dog".

The Guide Quality Checklist

Every guide MUST have these elements. Score each guide against this list:

1. Opening context (2-3 sentences): What problem does this solve? When would a developer reach for this?
2. Prerequisites: What do you need before starting? (packages, accounts, running node, etc.)
3. Mental model: How does this concept work at a high level? Not implementation details — the "why" and "how it fits" into Ethereum/Nethereum.
4. Progressive examples: Start simple, build complexity. Each example builds on the previous one.
5. Guiding text between every code block (CRITICAL — no code dumps): Every code block MUST have at least 1-2 sentences BEFORE it explaining what we're about to do and why, and at least 1 sentence AFTER explaining the result, what to watch for, or how this connects to the next step. A guide that is just ## Header → code block → ## Header → code block is a code dump, not a guide. The text must teach — explain concepts, warn about gotchas, connect to the reader's mental model. All explanatory text must be factual and verifiable against actual Nethereum source code — never hallucinate API behavior, parameter names, or default values.
6. Real-world scenarios: Use realistic values and contexts, not just "hello world". Show addresses, token amounts, contract names that feel like real usage.
7. Decision guidance: When there are multiple approaches, explain when to use which. Tables are great for this.
8. Common mistakes/gotchas: What trips people up? What error will they see if they forget X?
9. What to do next: Connect this guide to related guides with context ("Now that you can sign transactions, you'll want to estimate gas fees to avoid overpaying.")
10. No orphan code: Every code block must be reachable from a real scenario. If code can't be motivated by a user story, it doesn't belong in a guide (put it in the README/API reference instead).

Guides Must Reflect a Learning Journey

Guides are NOT independent articles — they form a connected path through the section. A learner reads them in order and each guide builds on the previous one.

The Core Foundation section is the validated reference template. When validating any section, read the Core Foundation guides first to see the standard in action. Then apply the same patterns.

Journey requirements:

1. Next Steps must follow the learning sequence — the first link in "Next Steps" should be the NEXT guide in the sidebar order. Additional links can point to related topics, but the primary link guides the learner forward through the progression.

2. Prose must be helpful and factual, never hallucinated — every explanation must come from:

   • Verified source code behavior (e.g., "EIP-1559 is the default since version 4.3.1" — checked in TransactionManagerBase.cs)
   • Playground sample comments (verified working text)
   • Ethereum specification facts (e.g., "1 Gwei = 10^9 Wei")
   • Observable API behavior (e.g., "returns null if the transaction hasn't been mined yet")

   NEVER write commentary that sounds authoritative but isn't verifiable. If you're unsure about behavior, check the source code first.

3. Context flows between guides — early guides can mention concepts explored in later guides ("We'll cover fee estimation in detail in the Fee Estimation guide — for now, Nethereum handles it automatically"). Later guides can reference earlier ones ("As we saw in Query Balance, balances are returned in Wei").

4. sidebar_position values must match the learning order within each sub-group. Essentials: 1-6, Deep Dives: 7-12, Keys/Encoding: 13-18, Transport: 19-20 (for Core Foundation as example).

5. No standalone guides — every guide must have at least 2 links in Next Steps connecting it to other guides in the section. At least one link should point forward in the sequence.

Guide Opening Pattern (CRITICAL)

Every guide MUST open with 2-3 sentences that answer WHY and WHEN before any code appears. The opening establishes context for the learner and connects to what they already know from previous guides.

BAD opening (jumps straight to code):

# Query Blocks and Transactions

## Connect to Ethereum

\`\`\`csharp
var web3 = new Web3("https://mainnet.infura.io/v3/YOUR-PROJECT-ID");
\`\`\`

GOOD opening (establishes WHY and connects to journey):

# Query Blocks and Transactions

After sending transactions (as covered in [Transfer Ether](guide-send-eth) and
[Send Transactions](guide-send-transaction)), you'll want to inspect what happened
on-chain. This guide covers querying blocks, looking up transactions by hash,
reading receipts to check success/failure, and detecting whether an address is
a contract or a regular account.

Pattern examples from the validated Core Foundation guides: