Update template and guidance

.cursor/rules/content-types.mdc

@@ -0,0 +1,72 @@
+---
+description: Maps folder conventions to Diataxis content types so AI tools produce the right structure for each doc category.
+globs: ["**/*.md", "**/*.mdx"]
+alwaysApply: false
+---
+
+# Content types (Diataxis)
+
+> **Note for this repository:** `docs-template` itself is a guide and template site — its content
+> is organized by task (`contribute/`, `create/`, `configure/`) rather than by Diataxis type.
+> The conventions below do **not** apply to files in this repo.
+> They are recommended for any **product documentation site** created using this template.
+
+The [Diataxis framework](https://diataxis.fr/) organizes documentation by function. In a product
+docs site, the folder a file lives in determines the content type and structure expectations.
+
+## Folder-to-type mapping
+
+### `concepts/` - Explanation
+
+- Explain **why** something exists and **how** it works at a high level.
+- Provide context: design decisions, historical reasons, trade-offs, and alternatives.
+- Make connections to other parts of the system or to broader industry concepts.
+- Do not include step-by-step instructions. Link to related guides or quickstarts instead.
+- Keep explanation closely bounded. Do not let instructions or reference details creep in.
+
+### `how-to/` - How-to
+
+- Goal-oriented steps that help the reader achieve a specific outcome.
+- Title the page with the goal (for example, "Configure rate limits"), not a generic label.
+- State the goal in the first sentence or heading.
+- List prerequisites before the first step.
+- Number the steps. Each step should contain one action.
+- Assume the reader has basic knowledge of the product.
+- Omit the unnecessary. Practical usability matters more than completeness.
+- Do not digress into explanations or teaching. Link to concept pages instead.
+
+### `get-started/` - Onboarding
+
+`get-started/` pages are onboarding essentials: installation, system requirements, connecting
+to services, and initial configuration.
+
+Choose structure based on the topic (how-to steps, short explanation, or reference-style facts)
+and match conventions of neighboring pages in the same `get-started/` section.
+
+### `reference/` - Reference
+
+- Precise, complete, structured descriptions of APIs, CLI options, methods, and parameters.
+- Describe and only describe. Be austere, neutral, and factual.
+- Match the format used in surrounding reference pages.
+- Mirror the structure of the API or code itself (for example, one section per method or endpoint).
+- Include short usage examples to illustrate parameters and return values.
+- Keep explanatory prose to the minimum needed to use the API correctly.
+- Do not include tutorials or extended how-to steps.
+
+### `tutorials/` - Tutorial
+
+- Learning-oriented, reproducible, end-to-end walkthrough.
+- State what the reader will build or accomplish at the very start.
+- Do not assume the reader has prior knowledge of the subject or tools.
+- Deliver visible results early and often. Each step should produce output the reader can verify.
+- Show expected output (for example, "You should see `Connected`").
+- Ruthlessly minimize explanation. Keep the focus on doing, not theory. Link to concept pages for
+  deeper understanding.
+- Ignore options and alternatives. Guide the reader along a single path to a successful conclusion.
+- Provide a complete working configuration or code sample.
+- Aspire to perfect reliability. Test every step.
+
+## Frontmatter
+
+For required and optional documentation frontmatter (`description`, `keywords`, `sidebar_label`,
+`title` vs duplicate H1), see **Frontmatter** in `markdown-formatting.mdc`.

.cursor/rules/contributor-workflow.mdc

@@ -0,0 +1,70 @@
+---
+description: Workflow rules for contributors and reviewers covering sidebar updates, redirects, verification, and PR expectations.
+alwaysApply: true
+---
+
+# Contributor workflow
+
+See [Submit a contribution](/contribute/submit-a-contribution) for the full contribution process.
+The rules below highlight the requirements that are most often missed.
+
+## Sidebar updates
+
+Sidebars are configured in `sidebars.js`. New pages may be autogenerated from the filesystem or
+require a manual entry, depending on the sidebar configuration used by this site.
+
+To control ordering and labels, use `_category_.json` files in directories and
+`sidebar_position` / `sidebar_label` in page frontmatter.
+
+## 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.
+
+## 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 appropriate asset folder for this product. Reference them with relative paths
+from the documentation page.
+
+## Update rule files for structural changes
+
+When a change affects the structure, naming, or conventions of a documentation 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 `content-types.mdc` if a new
+  folder pattern is introduced).
+- Changing the parameter documentation format in a reference section (update `content-types.mdc`).
+- Moving image storage to a different directory (update `contributor-workflow.mdc`).
+- Introducing new shared partials or generated-content patterns (document in the relevant rule file).
+
+Keeping rule files current prevents stale guidance from producing incorrect contributions.
+
+## CI linting
+
+Pull requests are checked by a Vale-based linter 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.
+
+Additional CI checks:
+
+- **Prettier** - run `npm run format` locally before pushing.
+- **Link check** - validates internal and external links.
+- **Build** - the Docusaurus build must pass (`onBrokenLinks: 'throw'`).
+
+## 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-area links
+
+See the **Links** section in `markdown-formatting.mdc`.

.cursor/rules/editorial-voice.mdc

@@ -0,0 +1,68 @@
+---
+description: Editorial voice and tone rules aligned with the Microsoft Writing Style Guide and Consensys documentation standards.
+globs: ["**/*.md", "**/*.mdx"]
+alwaysApply: false
+---
+
+# Editorial voice
+
+Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
+and the [Consensys documentation style guide](https://docs-template.consensys.net/contribute/style-guide).
+The rules below are the most actionable subset for AI-assisted editing.
+
+## Voice and tone
+
+- Use active voice and present tense.
+- Write in second person. Address the reader as "you."
+- Use contractions naturally ("it's," "don't"). Be informal but not sloppy.
+- Refer to the reader's deployment or setup as "your [thing]" (not "the [thing]" or "the user's
+  [thing]").
+- Refer to the reader as "you" (not "the developer," "the user," or "users").
+
+## Clarity
+
+- Get to the point in the first sentence of every section. Does it answer "what," "why," and "when"?
+- Use short, simple sentences. Remove nonessential or redundant words.
+- Break up three or more paragraphs with subheadings, lists, tables, code samples, or admonitions.
+- Write for developers and operators who want to accomplish a task or learn a skill, not for
+  marketing purposes.
+
+## Sentence construction
+
+- Lead with what's most important. Front-load keywords for scanning.
+- Start sentences with a verb when possible. Edit out "you can" and "there is/are" phrasing.
+- Use the Oxford (serial) comma in lists of three or more items (for example, "Android, iOS, and
+  Windows").
+- Do not start sentences with "So," "Basically," or "Actually."
+
+## Lists
+
+- Include at least two items but, if possible, no more than seven.
+- Keep items short enough that the reader can see two or three at a glance. A couple of short
+  paragraphs per item is acceptable, but don't exceed that length often.
+- Make all items consistent in structure (for example, each item is a noun or a phrase that starts
+  with a verb).
+
+## Punctuation and formatting
+
+- Do not use em dashes or en dashes. Use commas, parentheses, semicolons, or rephrase the sentence.
+- Use only one space after periods, question marks, and colons.
+- Use sentence case for all headings and titles. Never use title case.
+- Do not end headings, subheadings, or UI titles with periods.
+- Use backticks for inline code, file names, and URLs referenced in prose.
+- Use bold for UI element names (buttons, menu items, field labels).
+
+## Developer content
+
+- List prerequisites before the first step. Suggest good practices (for example, "secure private
+  keys," "protect RPC endpoints in production").
+- Write code samples that are readable, can be copied and pasted, and work as expected. Do not
+  include shell prompts (for example, `user@host $`) in code blocks.
+- Use angle-bracket placeholders for user-supplied values (for example, `<YOUR_API_KEY>`).
+
+## What to avoid
+
+- No marketing language, superlatives, or promotional tone ("best-in-class," "powerful," "seamless").
+- No slang, figures of speech, or culturally specific idioms.
+- No run-on sentences.
+- No jargon without definition. If a term must be used, define it on first use.

.cursor/rules/markdown-formatting.mdc

@@ -0,0 +1,72 @@
+---
+description: Markdown formatting conventions for Consensys documentation sites built with Docusaurus.
+globs: ["**/*.md", "**/*.mdx"]
+alwaysApply: false
+---
+
+# Markdown formatting
+
+Follow the [Consensys Markdown formatting guide](https://docs-template.consensys.net/contribute/format-markdown)
+for full details. The rules below cover the most common conventions.
+
+## Line length and sentence breaks
+
+- Wrap lines at roughly 80 columns (per the project `.editorconfig` and `.prettierrc`).
+- Start each new sentence on a new line, even if the previous line is short. This makes diffs
+  easier to review.
+
+## Links
+
+- Use relative file paths for links within the same documentation area (for example,
+  `./concepts/overview.md`).
+- Use absolute URL paths for cross-product or cross-area links (for example,
+  `/other-product/how-to/configure`).
+- Use descriptive link text. Do not use "click here" or bare URLs.
+
+## Code blocks
+
+- Always specify the language on fenced code blocks (` ```javascript `, ` ```bash `, etc.).
+- Indent code with two spaces, not four.
+- Write code samples that can be copied, pasted, and run as-is. Do not include shell prompts
+  (for example, `user@host $`) or trailing comments that break execution.
+- Use angle-bracket placeholders for values the reader must supply
+  (for example, `<YOUR_API_KEY>`).
+
+## Tabs
+
+- Use Docusaurus `<Tabs>` and `<TabItem>` components to display parallel content such as
+  command-line syntax or configuration in different formats.
+- Import `Tabs` and `TabItem` from `@theme/Tabs` and `@theme/TabItem` at the top of the file.
+
+## Admonitions
+
+- Use Docusaurus admonitions: `:::note`, `:::tip`, `:::caution`, `:::warning`, `:::info`, and `:::danger`.
+- Add a custom title on the same line only when it helps scanning (for example,
+  `:::caution important`).
+- For deprecated features or content, use `:::warning Deprecated`.
+  State that the feature or content is deprecated and will be removed in a future release.
+- Do not nest admonitions.
+
+## Tables
+
+- Align table columns in the source Markdown for readability.
+- Use a tool like [Markdown Table Formatter](https://markdowntable.com/) if needed.
+
+## Frontmatter
+
+- Required: `description` (one sentence for SEO and previews).
+- Recommended: `keywords` (array).
+- `sidebar_label`: optional. Use sparingly; only when the default sidebar text (usually from the
+  page title) would be too long or wordy for the navigation. Omit when the default is fine.
+- If the frontmatter contains a `title` field, do not add a separate top-level `# Heading` to
+  avoid a duplicate H1.
+
+## File and folder names
+
+- Use lowercase letters and dashes only (for example, `configure-api.md`, not
+  `configureAPI.md`).
+
+## Diagrams
+
+- Use [Mermaid](https://mermaid.js.org/) for diagrams where possible. Enable
+  `@docusaurus/theme-mermaid` in `docusaurus.config.js` if it is not already active.

.cursor/rules/terminology.mdc

@@ -0,0 +1,37 @@
+---
+description: Required spelling and casing for product names, industry terms, and standards referenced across this documentation site.
+globs: ["**/*.md", "**/*.mdx"]
+alwaysApply: false
+---
+
+# Terminology
+
+Use the following terms consistently. The left column is the required form. Do not use the variants
+listed on the right unless they appear in code, URLs, or direct quotations from a specification.
+
+## General Consensys terms
+
+| Required term | Do not use                                    |
+|---------------|-----------------------------------------------|
+| Consensys     | ConsenSys, consensys                          |
+| MetaMask      | Metamask, metamask                            |
+| dapp          | DApp, Dapp, dApp, decentralized application   |
+| smart contract | smartcontract, smart-contract               |
+| web3          | Web3, WEB3 (capitalize only at sentence start)|
+| JSON-RPC      | json-rpc, Json-RPC, JSONRPC                   |
+| onchain / offchain | on-chain, off-chain                     |
+
+## Product-specific terms
+
+<!-- TODO: Add product-specific terminology for this site. -->
+<!-- Follow the pattern: Required term | Do not use                  -->
+
+## Standards and specifications
+
+When introducing a standard for the first time on a page, spell out the full name with the
+identifier in parentheses. Use the short form on subsequent references.
+
+Examples:
+
+- First use: "Ethereum Improvement Proposal 1559 (EIP-1559)"
+- Subsequent: "EIP-1559"