diff --git a/.claude/commands/agents.md b/.claude/commands/agents.md new file mode 100644 index 000000000..3046216b3 --- /dev/null +++ b/.claude/commands/agents.md @@ -0,0 +1,72 @@ +# Generate AGENTS.md + +Regenerate the AGENTS.md file with a compressed documentation index. + +## When to run + +Run this command when: +- Documentation files have been added, removed, or reorganized +- You want to update the docs index for AI agents + +## Steps + +1. **Check for changes** (only regenerate if docs changed): + ```bash + git diff --name-only HEAD -- docs/ + git diff --name-only master...HEAD -- docs/ + ``` + +2. **If docs changed or `$ARGUMENTS` includes `force`:** + Run the generator script: + ```bash + node scripts/generate-agents-md.js + ``` + +3. **Report the result:** + - Show the docs index size + - Show total file size + - List any new directories or significant changes + +## Arguments + +- No arguments: Only regenerate if docs/ files have changed +- `force`: Regenerate regardless of changes +- `status`: Show current AGENTS.md stats without regenerating: + - File size and last modified date + - Number of indexed paths (count lines starting with `|`) + - Check if AGENTS.md is stale (docs changed since last generation) + +## Output format + +### For regeneration: +``` +## AGENTS.md Generation + +### Changes detected +- 3 files modified in docs/ + +### Generated +- Docs index: 10.5 KB +- Total size: 14.2 KB +- Directories indexed: 120 + +### Next steps +- Review AGENTS.md if needed +- Commit with your other changes +``` + +### For status: +``` +## AGENTS.md Status + +### Current file +- Size: 14.2 KB +- Last modified: 2024-02-09 20:44 +- Indexed paths: 122 + +### Freshness +- [OK] Up to date (no docs changes since generation) + OR +- [STALE] 5 docs files changed since last generation + Run `/agents` to regenerate +``` diff --git a/.claude/commands/lint.md b/.claude/commands/lint.md new file mode 100644 index 000000000..86ad2f6a8 --- /dev/null +++ b/.claude/commands/lint.md @@ -0,0 +1,86 @@ +# Lint MDX Documentation + +Check MDX files for formatting, structure, and Mintlify component usage. + +Reference `mintlify-reference.md` for correct component syntax. + +## Scope + +**By default, only check changed files:** +1. Run `git diff --name-only HEAD` to get uncommitted changes +2. Run `git diff --name-only master...HEAD` to include committed changes on this branch +3. Filter to only `.mdx` files in `docs/` + +**If `$ARGUMENTS` is provided:** +- `all` — check all MDX files in `docs/` +- A specific path — check only that file/folder (e.g., `docs/api`) + +## Steps + +1. Determine which files to check (changed files, all, or specific path) +2. Check each file for the issues below +3. Report issues with file path and line number +4. Suggest fixes for each issue + +## Checks to perform + +### Frontmatter +- Every MDX file should have frontmatter with at least `title` and `description` +- Frontmatter must be valid YAML between `---` fences + +### Heading structure +- No skipped heading levels (e.g., h1 → h3) +- Only one h1 per page (or none if title is in frontmatter) + +### Code blocks +- All code blocks must specify a language (```javascript not just ```) +- Code inside `` blocks should have both language AND label (```javascript Node.js) + +### Mintlify components +Check for correct syntax on these components: + +**Callouts** — must be self-closing or have content: +- ``, ``, ``, ``, `` + +**Structural** — check for proper nesting: +- `` must contain `` children +- `` must contain `` children +- `` must contain `` children + +**Cards** — check required attributes: +- `` should have `title` and `href` +- `` should have `cols` attribute + +**API docs** — check required attributes: +- `` needs `path|body|query|header`, `type`, and ideally `required` or `default` +- `` needs `name` and `type` + +**Media**: +- Images should be wrapped in `` +- `` tags should have `alt` attributes + +### Common mistakes to flag +- Unclosed MDX components (e.g., `` without ``) +- Using HTML comments `` instead of MDX `{/* */}` +- Broken internal links (files that don't exist in docs/) +- Empty code blocks +- Components with typos (e.g., `` instead of ``) + +## Output format + +``` +## Lint Results + +### Files checked +- 3 changed files (use `/lint all` to check entire docs/) + +### ❌ Errors (must fix) +- `docs/getting-started.mdx:15` — Code block missing language specifier +- `docs/api/users.mdx:42` — Unclosed component + +### ⚠️ Warnings (should fix) +- `docs/guides/auth.mdx:8` — Image not wrapped in + +### ✅ Summary +- 3 files checked, 2 errors, 1 warning +``` diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..7c326864e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,125 @@ +# Base Docs Index +IMPORTANT: Prefer retrieval-led reasoning. Read relevant docs before generating code. +Base is an Ethereum L2 by Coinbase. Docs for: Base Chain, Smart Wallet, OnchainKit, MiniKit. +[Docs]|root:./docs +|base-account/basenames:basename-transfer,basenames-faq,basenames-onchainkit-tutorial,basenames-wagmi-tutorial +|base-account/contribute:contribute-to-base-account-docs,security-and-bug-bounty +|base-account/framework-integrations:cdp,rainbowkit,reown,thirdweb +|base-account/framework-integrations/privy:authentication,setup,spend-permissions,sub-accounts,wallet-actions +|base-account/framework-integrations/wagmi:base-pay,basenames,batch-transactions,other-use-cases,setup,sign-in-with-base,sub-accounts +|base-account/guides:accept-payments,accept-recurring-payments,authenticate-users,migration-guide,sign-and-verify-typed-data +|base-account/guides/tips:inspect-txn-simulation,popup-tips +|base-account/improve-ux:batch-transactions,magic-spend,spend-permissions,sub-accounts +|base-account/improve-ux/sponsor-gas:erc20-paymasters,paymasters +|base-account/more:base-gasless-campaign,telemetry +|base-account/more/troubleshooting/usage-details:gas-usage,popups,simulations,unsupported-calls,wallet-library-support +|base-account/overview:what-is-base-account +|base-account/quickstart:ai-tools-available-for-devs,mobile-integration,web-react,web +|base-account/reference/base-pay:charge,getOrCreateSubscriptionOwnerWallet,getPaymentStatus,getStatus,pay,prepareCharge,prepareRevoke,revoke,subscribe,subscriptions-overview +|base-account/reference/core:createBaseAccount,generateKeyPair,getCryptoKeyAccount,getKeypair,getProvider,sdk-utilities +|base-account/reference/core/capabilities:atomic,auxiliaryFunds,dataSuffix,datacallback,flowControl,overview,paymasterService,signInWithEthereum +|base-account/reference/core/provider-rpc-methods:coinbase_fetchPermission,coinbase_fetchPermissions,eth_accounts,eth_blockNumber,eth_chainId,eth_coinbase,eth_estimateGas,eth_feeHistory,eth_gasPrice,eth_getBalance,eth_getBlockByHash,eth_getBlockByNumber,eth_getBlockTransactionCountByHash,eth_getBlockTransactionCountByNumber,eth_getCode,eth_getLogs,eth_getProof,eth_getStorageAt,eth_getTransactionByBlockHashAndIndex,eth_getTransactionByBlockNumberAndIndex,eth_getTransactionByHash,eth_getTransactionCount,eth_getTransactionReceipt,eth_getUncleCountByBlockHash,eth_getUncleCountByBlockNumber,eth_requestAccounts,eth_sendRawTransaction,eth_sendTransaction,eth_signTypedData_v4,personal_sign,request-overview,sdk-overview,standard-rpc-methods,wallet_addEthereumChain,wallet_addSubAccount,wallet_connect,wallet_getCallsStatus,wallet_getCapabilities,wallet_getSubAccounts,wallet_sendCalls,wallet_switchEthereumChain,wallet_watchAsset,web3_clientVersion +|base-account/reference/onchain-contracts:basenames,smart-wallet,spend-permissions +|base-account/reference/prolink-utilities:createProlinkUrl,decodeProlink,encodeProlink +|base-account/reference/spend-permission-utilities:fetchPermission,fetchPermissions,getPermissionStatus,prepareRevokeCallData,prepareSpendCallData,requestRevoke,requestSpendPermission +|base-account/reference/ui-elements:base-pay-button,brand-guidelines,sign-in-with-base-button +|base-app/agents:building-quality-agents,chat-agents,deeplinks,getting-started,mini-apps-and-agents,quick-actions,transaction-trays,x402-agents +|base-app/introduction:beta-faq +|base-chain/builder-codes:app-developers,bridge-developers,builder-codes,wallet-developers +|base-chain/flashblocks:apps,docs,node-providers +|base-chain/network-information:base-contracts,block-building,bridges,configuration-changelog,diffs-ethereum-base,ecosystem-contracts,network-fees,transaction-finality,troubleshooting-transactions +|base-chain/node-operators:performance-tuning,run-a-base-node,snapshots,troubleshooting +|base-chain/quickstart:base-solana-bridge,bridge-token,connecting-to-base,deploy-on-base,why-base +|base-chain/security:avoid-malicious-flags,bug-bounty,report-vulnerability,security-council +|base-chain/tools:account-abstraction,base-products,block-explorers,cross-chain,data-indexers,network-faucets,node-providers,onboarding,onchain-registry-api,onramps,oracles,tokens-in-wallet +|cookbook:accept-crypto-payments,ai-assisted-documentation-reading,ai-powered-development-fundamentals,ai-prompting,base-app-coins,base-builder-mcp,converting-customizing-mini-apps,defi-your-app,essential-documentation-resources,go-gasless,introduction-to-mini-apps,launch-ai-agents,launch-tokens,mastering-ai-prompt-engineering,onboard-any-user,onchain-social,spend-permissions-ai-agent,successful-miniapps-in-tba,testing-onchain-apps +|cookbook/minikit:add-frame-metadata,add-minikit,build-your-mini-app-with-prompt,configure-environment,create-manifest,fork-and-customize,install,manifest-cli,test-and-deploy +|get-started:base-mentorship-program,base-services-hub,base,build-app,concepts,country-leads-and-ambassadors,deploy-smart-contracts,docs-llms,docs-mcp,get-funded,launch-token,prompt-library +|learn:exercise-contracts,welcome +|learn/address-and-payable:address-and-payable +|learn/advanced-functions:function-modifiers,function-visibility +|learn/arrays:arrays-exercise,arrays-in-solidity +|learn/contracts-and-basic-functions:basic-functions-exercise,basic-types,hello-world-step-by-step +|learn/control-structures:control-structures-exercise,control-structures +|learn/deployment-to-testnet:deployment-to-testnet-exercise,test-networks +|learn/error-triage:error-triage-exercise,error-triage +|learn/foundry:deploy-with-foundry,generate-random-numbers-contracts,setup-with-base,testing-smart-contracts,verify-contract-with-basescan +|learn/hardhat/hardhat-forking:hardhat-forking +|learn/hardhat/hardhat-tools-and-testing:analyzing-test-coverage,debugging-smart-contracts,deploy-with-hardhat,optimizing-gas-usage,overview,reducing-contract-size +|learn/imports:imports-exercise +|learn/inheritance:inheritance-exercise,multiple-inheritance +|learn/interfaces:contract-to-contract-interaction +|learn/introduction-to-ethereum:ethereum-applications,evm-diagram,gas-use-in-eth-transactions,guide-to-base +|learn/introduction-to-solidity:deployment-in-remix,introduction-to-remix,introduction-to-solidity-overview,solidity-overview +|learn/mappings:mappings-exercise +|learn/new-keyword:new-keyword-exercise +|learn/onchain-app-development:deploy-with-fleek +|learn/onchain-app-development/account-abstraction:account-abstraction-on-base-using-biconomy,account-abstraction-on-base-using-particle-network,account-abstraction-on-base-using-privy-and-the-base-paymaster,gasless-transactions-with-paymaster +|learn/onchain-app-development/cross-chain:bridge-tokens-with-layerzero,send-messages-and-tokens-from-base-chainlink +|learn/onchain-app-development/finance:access-real-time-asset-data-pyth-price-feeds,access-real-world-data-chainlink,build-a-smart-wallet-funding-app +|learn/onchain-app-development/frontend-setup:building-an-onchain-app,introduction-to-providers,overview,viem,wallet-connectors,web3 +|learn/onchain-app-development/reading-and-displaying-data:configuring-useReadContract,useAccount,useReadContract +|learn/onchain-app-development/writing-to-contracts:useSimulateContract,useWriteContract +|learn/onchain-concepts:building-onchain-ai,building-onchain-frontend-development,building-onchain-gas,building-onchain-identity,building-onchain-nodes,building-onchain-onramps,building-onchain-social-networks,building-onchain-wallets,continue-building-onchain,core-concepts,development-flow,understanding-the-onchain-tech-stack +|learn/solidity:anatomy,basic-types,deployment-in-remix,exercise-basics,hello-world,introduction-to-contracts,introduction-to-remix,introduction,overview,remix-guide,step-by-step,video-tutorial +|learn/storage:how-storage-works,storage-exercise +|learn/structs:structs-exercise +|learn/token-development/erc-/token:erc-721-exercise,erc-721-standard +|learn/token-development/intro-to-tokens:tokens-overview +|learn/token-development/minimal-tokens:minimal-tokens-exercise +|learn/token-development/nft-guides:complex-onchain-nfts,dynamic-nfts,signature-mint,simple-onchain-nfts,thirdweb-unreal-nft-items +|mini-apps/core-concepts:authentication,base-account,context,embeds-and-previews,manifest,navigation,notifications +|mini-apps/featured-guidelines:design-guidelines,notification-guidelines,overview,product-guidelines,technical-guidelines +|mini-apps/growth:build-viral-mini-apps,optimize-onboarding,rewards +|mini-apps/introduction:overview +|mini-apps/quality-and-publishing:overview,quality-bar,submission-guidelines +|mini-apps/quickstart:build-checklist,building-for-the-base-app,create-new-miniapp,migrate-existing-apps,template +|mini-apps/resources:design-resources,templates +|mini-apps/technical-guides:accept-payments,dynamic-embeds,neynar-notifications,sharing-and-social-graph,sign-manifest +|mini-apps/troubleshooting:base-app-compatibility,common-issues,error-handling,how-search-works,testing +|onchainkit:create-a-basename-profile-component,getting-started,installation,restricted,use-coinbase-smart-wallet-and-eoas +|onchainkit/api:build-deposit-to-morpho-tx,build-mint-transaction,build-swap-transaction,build-withdraw-from-morpho-tx,get-mint-details,get-portfolios,get-swap-quote,get-token-details,get-tokens,types +|onchainkit/buy:buy,types +|onchainkit/checkout:checkout,types +|onchainkit/config:is-base,is-ethereum,onchainkit-provider,supplemental-providers,types +|onchainkit/earn:earn,types +|onchainkit/fund:fetch-onramp-config,fetch-onramp-options,fetch-onramp-quote,fetch-onramp-transaction-status,fund-button,fund-card,get-onramp-buy-url,setup-onramp-event-listeners,types +|onchainkit/guides:ai-prompting-guide,build-onchain-apps,contribution,lifecycle-status,reporting-bug,tailwind,telemetry,themes,troubleshooting,use-basename-in-onchain-app,using-ai-powered-ides +|onchainkit/hooks:use-build-deposit-to-morpho-tx,use-build-withdraw-from-morpho-tx,use-earn-context,use-mint-details,use-morpho-vault,use-token-details +|onchainkit/identity:address,avatar,badge,get-address,get-attestations,get-avatar,get-avatars,get-name,get-names,identity-card,identity,name,socials,types,use-address,use-avatar,use-avatars,use-name,use-names +|onchainkit/installation:astro,nextjs,remix,vite +|onchainkit/latest/components/appchain:bridge +|onchainkit/latest/components/buy:buy +|onchainkit/latest/components/checkout:checkout +|onchainkit/latest/components/connected:connected +|onchainkit/latest/components/earn:earn +|onchainkit/latest/components/fund:fund-button,fund-card +|onchainkit/latest/components/identity:address,avatar,badge,identity-card,identity,name,socials +|onchainkit/latest/components/minikit:overview,provider-and-initialization +|onchainkit/latest/components/minikit/hooks:useAddFrame,useAuthenticate,useClose,useComposeCast,useMiniKit,useNotification,useOpenUrl,usePrimaryButton,useViewCast,useViewProfile +|onchainkit/latest/components/mint:nft-card,nft-mint-card +|onchainkit/latest/components/signature:signature +|onchainkit/latest/components/swap:swap-settings,swap +|onchainkit/latest/components/token:token-chip,token-image,token-row,token-search,token-select-dropdown +|onchainkit/latest/components/transaction:transaction +|onchainkit/latest/components/wallet:wallet-dropdown-basename,wallet-dropdown-disconnect,wallet-dropdown-fund-link,wallet-dropdown-link,wallet-island,wallet-modal,wallet +|onchainkit/latest/configuration:onchainkit-provider,themes,wagmi-viem-integration +|onchainkit/latest/getting-started:manual-installation,overview,quickstart-guide,troubleshooting +|onchainkit/latest/guides:ai-prompting-guide,contributing +|onchainkit/latest/hooks/earn:use-build-deposit-to-morpho-tx,use-build-withdraw-from-morpho-tx,use-earn-context,use-morpho-vault +|onchainkit/latest/hooks/identity:use-address,use-avatar,use-avatars,use-name,use-names +|onchainkit/latest/hooks/mint:use-mint-details,use-token-details +|onchainkit/latest/utilities/earn:build-deposit-to-morpho-tx,build-withdraw-from-morpho-tx +|onchainkit/latest/utilities/fund:fetch-onramp-config,fetch-onramp-options,fetch-onramp-quote,fetch-onramp-transaction-status,get-onramp-buy-url,setup-onramp-event-listeners +|onchainkit/latest/utilities/identity:get-address,get-attestations,get-avatar,get-avatars,get-name,get-names +|onchainkit/latest/utilities/token:format-amount +|onchainkit/latest/utilities/wallet:is-valid-aa-entrypoint,is-wallet-a-coinbase-smart-wallet +|onchainkit/mint:nft-card,nft-mint-card,types +|onchainkit/paymaster:erc20-paymaster,errors,gasless-transactions-with-paymaster,how-to-contribute,quickstart-guide,quickstart-headless,security,troubleshooting,welcome +|onchainkit/signature:signature,types +|onchainkit/swap:swap-settings,swap,types +|onchainkit/templates:onchain-commerce-app,onchain-nft-app,onchain-social-profile +|onchainkit/token:format-amount,token-chip,token-image,token-row,token-search,token-select-dropdown,types +|onchainkit/transaction:transaction,types +|onchainkit/wallet:is-valid-aa-entrypoint,is-wallet-a-coinbase-smart-wallet,types,wallet-dropdown-basename,wallet-dropdown-disconnect,wallet-dropdown-fund-link,wallet-dropdown-link,wallet-island,wallet-modal,wallet +|root:cookie-policy,privacy-policy,showcase,terms-of-service,tone_of_voice diff --git a/claude.md b/claude.md index 1b459c5c9..2e1f4f3a3 100644 --- a/claude.md +++ b/claude.md @@ -9,6 +9,7 @@ Technical documentation for Base (Ethereum L2). Built with Mintlify. | `mintlify dev` | Local dev server | | `/lint` | Lint MDX files and fix issues | | `/doc-feedback` | Review content quality | +| `/agents` | Generate AGENTS.md index for AI agents | ## Structure @@ -60,5 +61,6 @@ Edit `docs.json` to add/remove pages. Add redirects when removing pages. ## Before Committing 1. Run `/lint` and fix errors -2. Add redirects for removed pages -3. Verify links work +2. Run `/agents` if docs structure changed +3. Add redirects for removed pages +4. Verify links work diff --git a/scripts/generate-agents-md.js b/scripts/generate-agents-md.js new file mode 100755 index 000000000..4343ca125 --- /dev/null +++ b/scripts/generate-agents-md.js @@ -0,0 +1,93 @@ +#!/usr/bin/env node + +/** + * Generates a minified AGENTS.md with compact docs index + * Groups doc files by directory using pipe-delimited structure + * + * Usage: node scripts/generate-agents-md.js + */ + +const fs = require('fs'); +const path = require('path'); + +const CONFIG = { + docsDir: './docs', + outputFile: './AGENTS.md', + + skipFiles: [ + 'README.md', 'CHANGELOG.md', 'LICENSE.md', '.DS_Store', + 'docs.json', 'package-lock.json', 'llms.txt', 'llms-full.txt', + 'iframe-theme.js', 'style.css', 'instructions.md', 'writing.md', 'CLAUDE.md' + ], + + skipFilePatterns: [/-vid$/, /-video$/, /-sbs$/], + + skipDirs: [ + 'node_modules', '.git', 'dist', 'build', 'coverage', + '.next', 'images', 'videos', 'logo', 'openapi', '.claude', 'snippets' + ], + + extensions: ['.md', '.mdx'] +}; + +function scanDocs(dir, basePath = '') { + const index = {}; + + if (!fs.existsSync(dir)) return index; + + const entries = fs.readdirSync(dir, { withFileTypes: true }); + const files = []; + + for (const entry of entries) { + if (CONFIG.skipFiles.includes(entry.name) || entry.name.startsWith('.')) continue; + + const fullPath = path.join(dir, entry.name); + const relPath = basePath ? `${basePath}/${entry.name}` : entry.name; + + if (entry.isDirectory()) { + if (CONFIG.skipDirs.includes(entry.name)) continue; + Object.assign(index, scanDocs(fullPath, relPath)); + } else { + const ext = path.extname(entry.name).toLowerCase(); + if (CONFIG.extensions.includes(ext)) { + const baseName = entry.name.replace(/\.mdx?$/, ''); + if (!CONFIG.skipFilePatterns.some(p => p.test(baseName))) { + files.push(baseName); + } + } + } + } + + if (files.length > 0) { + const key = (basePath || 'root').replace(/\/?\d+-/g, '/').replace(/^\//, ''); + index[key] = files; + } + + return index; +} + +function generateMinified() { + const index = scanDocs(CONFIG.docsDir); + + // Build minified index lines + const lines = Object.entries(index) + .sort(([a], [b]) => a.localeCompare(b)) + .map(([dir, files]) => `|${dir}:${files.join(',')}`); + + // Minified output - minimal whitespace + const content = `# Base Docs Index +IMPORTANT: Prefer retrieval-led reasoning. Read relevant docs before generating code. +Base is an Ethereum L2 by Coinbase. Docs for: Base Chain, Smart Wallet, OnchainKit, MiniKit. +[Docs]|root:./docs +${lines.join('\n')} +`; + + fs.writeFileSync(CONFIG.outputFile, content); + + const size = Buffer.byteLength(content, 'utf8'); + console.log(`Generated: ${CONFIG.outputFile}`); + console.log(`Size: ${(size / 1024).toFixed(2)} KB`); + console.log(`Entries: ${lines.length} directories`); +} + +generateMinified();