metamask-docs / rules

---
description: Workflow rules for contributors and reviewers covering sidebar updates, redirects, verification, and PR expectations.
alwaysApply: true
---

# Contributor workflow

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution process. The rules below highlight
the requirements that are most often missed.

## Sidebar updates

Every new documentation page must be added to the appropriate sidebar file:

| Product            | Sidebar file              |
| ------------------ | ------------------------- |
| MetaMask Connect   | `mm-connect-sidebar.js`   |
| Embedded Wallets   | `ew-sidebar.js`           |
| Smart Accounts Kit | `gator-sidebar.js`        |
| Agent Wallet       | `agent-wallet-sidebar.js` |
| Agent Wallet       | `agent-wallet-sidebar.js` |
| Snaps              | `snaps-sidebar.js`        |

Infura API and dashboard documentation is maintained in [docs.infura](https://github.com/INFURA/docs.infura), not in this repository. Link to `https://docs.infura.io/` from MetaMask docs when referencing Infura APIs or the Infura dashboard.

## Redirects

Every deleted, renamed, or moved page must have a redirect added in `vercel.json`. Docusaurus is
configured with `onBrokenLinks: 'throw'`, so broken internal links will fail the build.

Follow the trailing-slash rules in `vercel-redirects.mdc`: use a **slash-terminated `source`**
only (no duplicate no-slash entry), and a slash-terminated `destination` for normal paths.

## Factual accuracy

Do not state as fact any API behavior, parameter, or return value that you have not verified
against the codebase or published reference. If you are uncertain, add a review comment or
admonition noting the uncertainty. This rule applies to both human and AI-assisted contributions.

## Images

Place images in the product's designated asset folder:

- `metamask-connect/*/_assets/`
- `static/img/embedded-wallets/` (Embedded Wallets product images)
- `smart-accounts-kit/assets/`
- `snaps/assets/`
- `static/img/` (for site-wide assets)

## Update rule files for structural changes

When a change affects the structure, naming, or conventions of a product area, update the
corresponding `.cursor/rules/` file in the same PR. Examples of changes that require a rule update:

- Renaming a product or changing its branding (update the product rule file and `terminology.mdc`).
- Adding, removing, or renaming top-level content folders (update the product rule file and
  `content-types.mdc` if a new folder pattern is introduced).
- Changing the parameter documentation format in a reference section (update the product rule file
  and `content-types.mdc`).
- Moving image storage to a different directory (update `contributor-workflow.mdc` and the product
  rule file).
- Adding a new product area to the repository (create a new `product-*.mdc` rule file and add the
  product to the table in `contributor-workflow.mdc` and `AGENTS.md`).
- Changing sidebar file names or adding new sidebar files (update the sidebar table above and the
  product rule file).
- Introducing new shared partials or generated-content patterns (update the product rule file).

Keeping rule files current prevents stale guidance from producing incorrect contributions.

## CI linting

Pull requests run **`npm run format:check`** (Prettier against `.prettierrc` and `.prettierignore`). Run
**`npm run format`** locally to fix style before pushing. Generated Snaps API pages under
`snaps/reference/snaps-api/` are excluded from formatting in git (see `.prettierignore`).

After **`npm install`**, [Husky](https://typicode.github.io/husky/) installs a Git **`pre-commit`** hook
that runs [**`lint-staged`**](https://github.com/lint-staged/lint-staged) using the rules in
`package.json`. Staged files matching those patterns are auto-formatted with Prettier (and other
commands in `lint-staged`, such as ESLint on `src/`). Restage if the hook edits files. Hooks are
local only and are not required for CI to pass.

Pull requests are checked by a Vale-based linter
([docs-spelling-check](https://github.com/Consensys/github-actions/tree/main/docs-spelling-check))
that enforces Microsoft style, Consensys terminology, and spelling. Fix any linter warnings before
requesting review. If a warning is a false positive, add the term to the Vale vocabulary file rather
than rewriting valid technical language.

> **Warning:** Do not wire Vale into the Husky `pre-commit` hook (`lint-staged` in `package.json`).
> Vale is intentionally CI-only. It frequently reports false positives on valid technical content
> (for example, code identifiers like `wagmi-tab`, product names, and intentional ellipses) and lints
> the entire staged file rather than just your diff, so running it on commit blocks unrelated,
> pre-existing content and stalls otherwise-valid commits. Let the PR CI run Vale; contributors can
> still run it on demand with `npm run docs:ci`.

## Pull requests

- Summarize what changed and why in the PR description. Do not just list files.
- Link the related issue using `fixes #<number>` when applicable.
- Preview locally with `npm start` before requesting review.

## Cross-product links

See the **Links** section in `markdown-formatting.mdc`.