base · soheimam · Jan 8, 2026 · Jan 21, 2026 · Jan 21, 2026 · Jan 21, 2026
diff --git a/.claude/skills/doc-feedback.md b/.claude/skills/doc-feedback.md
@@ -0,0 +1,42 @@
+---
+name: reviewing-documentation
+description: Reviews documentation for quality, consistency, and style guide adherence. Use when reviewing changed docs or before publishing new content.
+---
+
+# Documentation Feedback
+
+## Workflow
+
+1. **Get files to review**
+   ```bash
+   git diff --name-only HEAD -- '*.mdx'
+   git diff --name-only master...HEAD -- '*.mdx'
+   ```
+   If `$ARGUMENTS` provided, review that path instead.
+
+2. **Run linter first**
+   ```bash
+   node scripts/lint-mdx.js $ARGUMENTS
+   ```
+
+3. **Review against style guide** — See [content-instructions.md](../../content-instructions.md)
+
+4. **Provide feedback** per file:
+   - What's working well
+   - Specific suggestions with line references
+   - Linter issues (if any)
+
+5. **Offer to fix** issues if requested
+
+## Review checklist
+
+```
+Review Progress:
+- [ ] Terminology consistent
+- [ ] Code examples complete and runnable
+- [ ] No placeholder values (foo, bar, example.com)
+- [ ] Headings descriptive and keyword-rich
+- [ ] Content scannable (headings, lists, white space)
+- [ ] Active voice, second person
+- [ ] Troubleshooting included where appropriate
+```
diff --git a/.claude/skills/lint.md b/.claude/skills/lint.md
@@ -0,0 +1,25 @@
+---
+name: linting-mdx
+description: Runs deterministic MDX linter and helps fix formatting, structure, and Mintlify component issues. Use when checking documentation quality or before committing changes.
+---
+
+# Lint MDX
+
+Run the linter:
+
+```bash
+node scripts/lint-mdx.js $ARGUMENTS
+```
+
+Arguments: (none) = changed files, `all` = everything, or specify a path.
+
+## Workflow
+
+1. Run linter, present results
+2. If errors found, offer to fix them
+3. Prioritize errors over warnings
+
+## References
+
+- [mintlify-reference.md](../../mintlify-reference.md) — component syntax
+- [content-instructions.md](../../content-instructions.md) — writing guidelines
diff --git a/claude.md b/claude.md
@@ -0,0 +1,64 @@
+# Base Documentation
+
+Technical documentation for Base (Ethereum L2). Built with Mintlify.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `mintlify dev` | Local dev server |
+| `/lint` | Lint MDX files and fix issues |
+| `/doc-feedback` | Review content quality |
+
+## Structure
+
+```
+docs/
+├── get-started/      # Intro, quickstarts
+├── base-chain/       # Network, nodes, tools
+├── base-account/     # Smart Wallet SDK
+├── base-app/         # Agent development
+├── mini-apps/        # MiniKit guides
+├── onchainkit/       # React components (versioned)
+├── cookbook/         # Tutorials
+├── learn/            # Solidity, Ethereum basics
+├── images/           # Assets by topic
+├── snippets/         # Reusable MDX components
+└── docs.json         # Navigation config
+```
+
+## Content Rules
+
+**Frontmatter** (required):
+```yaml
+---
+title: "Keyword-rich title"
+description: "Value description"
+---
+```
+
+**Writing**: American English, sentence case headings, second person ("you"), active voice.
+
+**Code blocks**: Always specify language. Add filename or title. Use `highlight={}` for emphasis.
+
+**Components**: See [mintlify-reference.md](mintlify-reference.md) for syntax.
+
+**Images**: Wrap in `<Frame>`, include `alt` attribute.
+
+## Navigation
+
+Edit `docs.json` to add/remove pages. Add redirects when removing pages.
+
+## References
+
+| File | Purpose |
+|------|---------|
+| [content-instructions.md](content-instructions.md) | Writing guidelines |
+| [mintlify-reference.md](mintlify-reference.md) | Component syntax |
+| [scripts/README.md](scripts/README.md) | Linter usage |
+
+## Before Committing
+
+1. Run `/lint` and fix errors
+2. Add redirects for removed pages
+3. Verify links work
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
diff --git a/docs/base-chain/network-information/block-building.mdx b/docs/base-chain/network-information/block-building.mdx
@@ -24,11 +24,11 @@ See the [Configuration Changelog](/base-chain/network-information/configuration-
 Currently, blocks are built using [op-rbuilder](https://github.com/flashbots/op-rbuilder) and priority fee auctions occur
 every 200ms. There are two changes from the vanilla ordering to be aware of:
 
-##### Timing
+#### Timing
 
 Flashblocks are built every 200ms, each ordering a portion of the block. Unlike the current system where later-arriving transactions with higher priority fees can be placed at the top of the block, Flashblocks creates a time-based constraint. Once a Flashblock is built and broadcast, its transaction ordering is locked even if a transaction with a higher priority fee arrives later, it cannot be included in earlier, already built Flashblocks.
 
-##### High Gas Limits
+#### High Gas Limits
 
 If your app creates transactions with large gas limits, we recommend monitoring to detect any changes in inclusion latency. Transactions with gas limits over 1/10 of the current block gas limit (currently 14 million gas), face additional constraints:
 

diff --git a/docs/base-chain/network-information/transaction-finality.mdx b/docs/base-chain/network-information/transaction-finality.mdx
@@ -19,7 +19,9 @@ This describes finality for transactions on Base except withdrawal transactions
 
 For transactions on Base, finality is not a single time to wait for. Instead, there are 4 stages in time that each provide increasing security guarantees.
 
+<Frame>
 ![Diagram of transaction finality stages on Base](/images/transaction-finality/base-tx-finality.jpg)
+</Frame>
 
 <Steps>
 <Step title="Flashblock Inclusion: ~200ms" titleSize="h3">

diff --git a/docs/learn/hardhat/etherscan/etherscan-sbs.mdx b/docs/learn/hardhat/etherscan/etherscan-sbs.mdx
@@ -24,7 +24,9 @@ By the end of this lesson, you should be able to:
 
 [Etherscan](https://etherscan.io) is a popular Blockchain explorer that works for several different networks. In it, you can explore the state and activity of a particular network.
 
+<Frame>
 ![Etherscan](/images/learn/etherscan/etherscan-user-interface.png)
+</Frame>
 
 You can explore:
 
@@ -35,7 +37,9 @@ You can explore:
 
 For instance, the following shows the details of a Block:
 
+<Frame>
 ![Block](/images/learn/etherscan/blocks.png)
+</Frame>
 
 Where you see information such as:
 
@@ -56,7 +60,9 @@ One of the things you can do with Etherscan is interact with already-deployed co
 
 For example, if you want to read information from a famous contract such as [BAYC](https://etherscan.io/token/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d), you can simply go to Etherscan and explore the contract:
 
+<Frame>
 ![BAYC](/images/learn/etherscan/bayc.png)
+</Frame>
 
 You are able to see information such as:
 
@@ -68,33 +74,43 @@ You are able to see information such as:
 
 In the **Contract** tab, you can see the full source code of BAYC:
 
+<Frame>
 ![BAYC Verified](/images/learn/etherscan/bayc-verified.png)
+</Frame>
 
 For a developer, verifying contracts is important since it gives transparency to your users. However, there are some risks because this means that bad actors can see the full source code and can try to exploit it.
 
 In order to read the state of the BAYC, you can go to the main menu and select the option **Read Contract**:
 
+<Frame>
 ![BAYC Read](/images/learn/etherscan/bayc-read.png)
+</Frame>
 
 After you select that option, you are able to see all of the read functions of the contract.
 
 You can also query who is the owner of the BAYC with id 150:
 
+<Frame>
 ![BAYC Query](/images/learn/etherscan/bayc-query.png)
+</Frame>
 
 ## Writing data to smart contracts using Etherscan
 
 In a similar fashion, you can read data from smart contracts using Etherscan. It is also possible to write data.
 
 To write data, go to the **Write Contract** tab:
 
+<Frame>
 ![Write Contract](/images/learn/etherscan/bayc-write.png)
+</Frame>
 
 From there, connect your wallet by clicking the **Connect with web3** button.
 
 After you connect, the following UI appears:
 
+<Frame>
 ![Write BAYC Connected](/images/learn/etherscan/bayc-write-connected.png)
+</Frame>
 
 You can then call the functions you wish to write to.
 

diff --git a/docs/learn/hardhat/hardhat-deploy/hardhat-deploy-sbs.mdx b/docs/learn/hardhat/hardhat-deploy/hardhat-deploy-sbs.mdx
@@ -235,7 +235,9 @@ npx hardhat deploy --network base_sepolia
 
 After you run the command, a deployments folder appears with a newly-created deployment for `base_sepolia`:
 
+<Frame>
 ![New deployment](/images/learn/hardhat-deploying/new-deploy.png)
+</Frame>
 
 If you want to deploy to another network, change the network name as follows:
 

diff --git a/docs/learn/hardhat/hardhat-forking/hardhat-forking.mdx b/docs/learn/hardhat/hardhat-forking/hardhat-forking.mdx
@@ -145,7 +145,9 @@ describe('BalanceReader tests', () => {
 
 In this example, the [USDC address](https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48) is used and since USDC is an ERC-20 token, you can explore the token holders of that particular token directly in Etherscan:
 
+<Frame>
 ![Hardhat forking](/images/learn/hardhat-forking/hardhat-forking.png)
+</Frame>
 
 Or, visit https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48#balances, where you can see, at the time or writing, Arbitrum ONE Gateway is the top token holder.
 

diff --git a/docs/learn/hardhat/hardhat-testing/hardhat-testing-sbs.mdx b/docs/learn/hardhat/hardhat-testing/hardhat-testing-sbs.mdx
@@ -165,7 +165,9 @@ it('should get the unlockTime value', async () => {
 
 Notice how autocomplete appears after entering `lockInstance`:
 
+<Frame>
 ![Auto complete](/images/learn/hardhat-testing/autocomplete-unlockTime.png)
+</Frame>
 
 You can simply run `npx hardhat test` and then get:
 

diff --git a/docs/learn/hardhat/hardhat-tools-and-testing/analyzing-test-coverage.mdx b/docs/learn/hardhat/hardhat-tools-and-testing/analyzing-test-coverage.mdx
@@ -176,7 +176,9 @@ All files   |      100 |    83.33 |      100 |      100 |                |
 
 Which then gives you a report of the test coverage of your test suite. Notice there is a new folder called `coverage`, which was generated by the `solidity-coverage` plugin. Inside the `coverage` folder there is a `index.html` file. Open it in a browser, you'll see a report similar to the following:
 
+<Frame>
 ![Coverage report](/images/hardhat-test-coverage/coverage-report.png)
+</Frame>
 
 ## Increasing test coverage