docs: restructure navigation and refresh content

.github/workflows/docs-quality.yml

@@ -0,0 +1,50 @@
+name: Documentation quality
+
+on:
+  pull_request:
+    paths:
+      - "**/*.mdx"
+      - "**/*.md"
+      - "docs.json"
+      - "openapi/**"
+      - "examples/**"
+      - "scripts/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/docs-quality.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - "**/*.mdx"
+      - "**/*.md"
+      - "docs.json"
+      - "openapi/**"
+      - "examples/**"
+      - "scripts/**"
+      - "package.json"
+      - "package-lock.json"
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate documentation
+        run: npm run check

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.DS_Store
+.mintlify/
+dist/
+coverage/

.mintignore

@@ -0,0 +1 @@
+developer-guide/integrations/raas.mdx

.nvmrc

@@ -0,0 +1 @@
+22

IMPLEMENTATION_REPORT.md

@@ -0,0 +1,157 @@
+# Namespace documentation improvement report
+
+Date: 2026-07-14
+Repository: `namespace-docs`
+
+## Executive summary
+
+This update improves the documentation's technical accuracy, reader journeys, accessibility, editorial consistency, and contributor workflow. The documentation now has 78 published MDX pages, and every page has a matching navigation entry. Runnable TypeScript examples are pinned to supported SDK versions and checked in CI.
+
+No commit, push, or pull request was created.
+
+## Information architecture and navigation
+
+- Reorganized the Overview introduction so readers encounter Getting started, concepts, use cases, the ecosystem, and company context in a deliberate order.
+- Added Ecosystem and the RaaS guide to navigation instead of leaving them discoverable only by direct URL.
+- Added Troubleshooting to Developer Guide > Getting Started.
+- Consolidated seven duplicate, obsolete, or superseded pages:
+  - `/quickstart` → `/developer-guide/quickstart`
+  - `/overview/namespace-onchain-subnames` → `/developer-guide/architecture/onchain-subnames`
+  - `/overview/offchain-subnames` → `/overview/subnames#offchain-subnames`
+  - `/user-guide/overview` → `/getting-started`
+  - `/user-guide/app/wizard` → `/user-guide/app`
+  - `/user-guide/app/features-list` → `/user-guide/app`
+  - `/user-guide/app/widget` → `/user-guide/ens-widget`
+- Updated older redirect destinations that still pointed to the retired wizard, feature-list, or architecture pages.
+- Fixed the redirect for `/how-to-guides-and-demos`, whose destination did not start with `/`.
+- Standardized internal documentation links on root-relative routes without `.mdx` suffixes.
+
+## Reader journey and content changes
+
+- Rewrote `getting-started.mdx` around three reader intents: product integration, no-code onchain management, and offchain issuance.
+- Added a concise L1/L2/offchain comparison table covering cost, ownership, and starting workflow.
+- Rebuilt the Developer quickstart as an actual runnable offchain workflow instead of a directory of product cards.
+- Rewrote About Namespace to explain products and ENS context without repeating use-case lists or embedding changing traction numbers.
+- Rewrote the product-team page around product patterns, model selection, integration paths, and production planning.
+- Rewrote the SDK and API product page as a practical interface-selection guide.
+- Rebuilt the subname concepts page with a direct comparison of L1, L2, and offchain control models.
+- Added a troubleshooting guide for authentication, availability, record validation, mint eligibility, transaction simulation, resolution, RPC errors, and support requests.
+- Removed repeated use-case lists from overview pages and linked to one canonical Use cases page.
+
+## Technical documentation corrections
+
+### Offchain Manager
+
+- Added missing `await` calls to asynchronous examples.
+- Corrected `addAddressRecord`, `deleteAddressRecord`, `addTextRecord`, `deleteTextRecord`, `addDataRecord`, and `deleteDataRecord` examples to use the positional signatures exported by version 1.0.13.
+- Corrected `parentNames` from `string` to `string[]`.
+- Replaced incomplete addresses with valid example Ethereum addresses where compilation matters.
+- Removed a duplicate client-initialization block from the offchain tutorial.
+- Pinned tutorial installation commands to `@thenamespace/offchain-manager@1.0.13`.
+- Added explicit environment-variable validation and server-side credential guidance.
+
+### Mint Manager
+
+- Rebuilt the L1/L2 minting guide around the package API exported by version 1.1.1.
+- Fixed the incorrect `BASE_ID` import and validated the RPC URL and wallet private key before use.
+- Removed the duplicated Base address record.
+- Corrected mint records from object maps to the exported arrays of `{ key, value }` and `{ chain, value }`.
+- Corrected `expiryInYears: number` to a concrete numeric example.
+- Added both L1 and L2 availability examples.
+- Added eligibility, pricing, parameter generation, simulation, submission, and troubleshooting stages.
+- Documented the published v1.1.1 `cursomRpcUrls` spelling so readers are not given a configuration property rejected by the package type.
+- Pinned tutorial installation commands to `@thenamespace/mint-manager@1.1.1`.
+
+### API reference
+
+- Added descriptive frontmatter to all 15 OpenAPI-backed operation pages so every page has a useful search and SEO description.
+
+## Type-checked examples
+
+Added complete examples under `examples/`:
+
+- `examples/offchain-subnames.ts`
+- `examples/mint-subname.ts`
+- `examples/tsconfig.json`
+
+The examples compile in strict mode against the exact SDK and Viem versions pinned in `package.json`. CI runs `npm run check:examples` to catch future package and documentation drift.
+
+## Editorial refresh
+
+- Applied a repository-wide clarity, voice, specificity, and proof sweep.
+- Standardized `web3`, `GitHub`, `npm`, `app`, `offchain`, `onchain`, and lowercase `subname` in body copy.
+- Converted title-case and bolded headings to sentence case where touched.
+- Replaced promotional descriptions such as “easiest” and “production-ready” with concrete outcomes.
+- Removed or qualified unsupported claims such as “works everywhere,” “100% unruggable,” “no phishing,” and “fully resolvable across web3.”
+- Replaced copied traction figures with a link to the live Namespace statistics dashboard.
+- Removed unowned “coming soon” language.
+- Clarified that Mint Manager prepares signed parameters offchain while the ownership change occurs in an onchain transaction.
+- Improved weak and filename-based image alternative text with descriptions of the visual content.
+
+## Accessibility
+
+- Changed the primary color from `#16A34A` to `#15803D`.
+- Improved the primary-on-light contrast ratio from 3.30:1 to 5.02:1, meeting WCAG AA.
+- Verified that every checked image and video has alternative text.
+- Added a content check that rejects empty or filename-like image alternative text.
+
+## Contributor workflow
+
+Added:
+
+- `.nvmrc` pinned to Node.js 22.
+- `package.json` and `package-lock.json` with exact tool and SDK versions.
+- Local scripts for development, build validation, link checks, accessibility, content checks, and example compilation.
+- `.github/workflows/docs-quality.yml` to run the complete quality suite on relevant pushes and pull requests.
+- `CONTRIBUTING.md` with setup, authoring, example, and review instructions.
+- `STYLE_GUIDE.md` with voice, terminology, heading, code, link, claim, and freshness rules.
+- `templates/documentation-page.md` for new task-based guides.
+- `scripts/check-docs.mjs`, which checks:
+  - one-to-one navigation coverage;
+  - missing navigation files;
+  - frontmatter titles and descriptions;
+  - redirect formatting;
+  - root-relative internal links and local targets;
+  - empty headings;
+  - terminology errors;
+  - weak alternative text; and
+  - exact duplicate MDX pages.
+
+The README now uses the pinned local toolchain instead of a global Mintlify installation and documents the complete quality command.
+
+## Repository cleanup
+
+- Removed seven duplicate or obsolete MDX pages after adding redirects.
+- Removed 15 confirmed unreferenced image assets totaling 5,499,354 bytes, approximately 5.24 MiB.
+- The removed assets included duplicate `Frame1000002828` files, retired ENS Widget screenshots, unused starter screenshots, old logo copies, and superseded L2 diagrams.
+- Added `.gitignore` rules for dependencies, Mintlify working files, build output, coverage, and macOS metadata.
+
+## Validation results
+
+All required checks pass:
+
+| Check | Result |
+| --- | --- |
+| Mintlify build validation | Passed |
+| Mintlify broken-link check | Passed; no broken links found |
+| Mintlify accessibility check | Passed; WCAG AA contrast achieved and all media has alt text |
+| Custom content and navigation check | Passed for 78 pages and 78 navigation routes |
+| Strict TypeScript example compilation | Passed |
+| Git whitespace check | Passed after cleanup |
+| Production dependency audit | Passed; 0 production vulnerabilities |
+| Local preview smoke test | Passed with HTTP 200 for the home page, Getting started, Developer quickstart, Troubleshooting, and L1/L2 minting guide |
+
+## Non-blocking observations
+
+- Mintlify reports the primary color as a warning because it does not reach the stricter WCAG AAA threshold. It meets the requested WCAG AA threshold at 5.02:1.
+- The installed documentation toolchain contains 12 moderate advisories in development-only transitive dependencies. `npm audit --omit=dev` reports 0 production vulnerabilities. No force upgrade was applied because that could replace the pinned Mintlify toolchain with breaking versions.
+- Mintlify does not support the machine's global Node.js 25 runtime. The repository now pins Node.js 22, and validation is run with Node.js 22.
+- During hot reload, the Mintlify CLI intermittently logs an internal `transformAlgorithm` TypeError, but it continues serving the preview and all requested routes return HTTP 200. Strict build validation also passes.
+
+## Local preview
+
+The documentation was kept running during implementation at:
+
+`http://localhost:4323`
+
+No deployment or remote repository operation was performed.

README.md

@@ -1,31 +1,39 @@
-# Namespace Documentation
+# Namespace documentation
 
 This repository contains the documentation for [Namespace](https://namespace.ninja), a platform for ENS subname management and development tools.
 
-## Development
+## Local development
 
-Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview the documentation changes locally:
+The repository uses Node.js 22 and a pinned version of the Mintlify CLI. If you use `nvm`, select the correct Node.js version before installing dependencies:
 
+```bash
+nvm use
+npm ci
+npm run dev
 ```
-npm i -g mint
-mint dev
+
+Open the local URL printed by Mintlify. Changes to MDX files and `docs.json` reload automatically.
+
+## Quality checks
+
+Run the complete documentation test suite:
+
+```bash
+npm run check
 ```
 
-## Publishing Changes
+The suite validates the Mintlify build, checks links and accessibility, enforces repository content conventions, and type-checks the SDK examples.
 
-Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch.
+## Contributing
 
-## Pre-deployment Checklist
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before adding or moving pages. Writing and terminology conventions live in [STYLE_GUIDE.md](STYLE_GUIDE.md), and new guides should start from [the documentation page template](templates/documentation-page.md).
 
-### ✅ 1. Run Locally
-- [ ] Run `mint dev` and verify the site loads correctly
-- [ ] Test navigation links and assets
+## Publishing
 
-### ✅ 2. Check docs.json Configuration
-- [ ] Confirm navigation paths match file structure
-- [ ] Check new files are referenced in navigation
+The Mintlify GitHub App deploys changes from the default branch. Before merging a documentation change:
 
-### ✅ 3. Review Redirects
-- [ ] Check if existing redirects will be affected
-- [ ] Add redirects for moved/renamed pages
-- [ ] Test redirects locally
+- Preview it locally.
+- Run `npm run check`.
+- Confirm new pages appear in `docs.json` navigation.
+- Add redirects for moved or retired routes.
+- Review screenshots, alternative text, and external links.

STYLE_GUIDE.md

@@ -0,0 +1,82 @@
+# Namespace documentation style guide
+
+Use this guide for product, developer, API, and changelog documentation.
+
+## Voice
+
+- Be direct, practical, and calm.
+- Address the reader as “you.”
+- Lead with the outcome, then explain the steps.
+- Prefer concrete verbs: “create,” “check,” “mint,” and “resolve.”
+- Avoid promotional filler in technical instructions.
+
+## Terminology
+
+Use these forms consistently:
+
+| Preferred | Avoid |
+| --- | --- |
+| subname, subnames | Subname, Subnames in body copy |
+| offchain, onchain | Offchain, Onchain in body copy |
+| web3 | Web3, web 3 |
+| app | dApp, Dapp; use “decentralized app” when the distinction matters |
+| GitHub | Github |
+| npm | Npm |
+| mainnet, testnet | Mainnet, Testnet unless part of a proper name |
+| API key | API Key in body copy |
+
+Keep official product names capitalized: Namespace App, Offchain Manager, Mint Manager, Indexer Manager, ENS Components, ENS Widget, and Resolvio.
+
+## Headings and titles
+
+- Use sentence case: “Create an offchain subname,” not “Create an Offchain Subname.”
+- Use “How to,” not “How To.”
+- Do not add bold formatting inside headings.
+- Give every section a descriptive heading; do not use empty headings.
+
+## Page subtitles
+
+- Treat the frontmatter `description` as the subtitle below the page title.
+- Keep it to one short line, usually 5–10 words.
+- Use it to frame the page; do not repeat the first paragraph.
+- Put scope, mechanics, examples, and qualifications in the introduction.
+
+## Procedures
+
+- State the result in the introduction.
+- List prerequisites before the steps.
+- Use numbered steps for ordered work.
+- Put one action in each step.
+- Show expected output after commands when it helps readers verify progress.
+- End with next steps and troubleshooting links.
+
+## Code
+
+- Prefer TypeScript for SDK examples.
+- Use single quotes in TypeScript unless an existing project standard requires otherwise.
+- Await every Promise.
+- Validate required environment variables before use.
+- Use obvious placeholders such as `YOUR_NAMESPACE_API_KEY`; never use real credentials.
+- Pin major package versions in reproducible tutorials. Reference pages may show the currently supported version from `package.json`.
+- Keep examples in the docs aligned with the type-checked files in `examples/`.
+
+## Links and images
+
+- Use root-relative internal routes: `/developer-guide/quickstart`.
+- Do not include `.mdx` in links.
+- Use descriptive link text instead of “click here.”
+- Describe the useful information in image alternative text. Do not use a filename as alternative text.
+
+## Claims and evidence
+
+- Avoid absolute security claims such as “prevents phishing.” Say what a feature helps reduce.
+- Link technical protocol claims to primary sources.
+- Add an “as of” date to changing metrics, or link to a live dashboard instead of copying the number.
+- Do not use “leading,” “best,” or “industry-leading” without independent evidence.
+
+## Freshness
+
+- Review product pages every quarter.
+- Review SDK and API pages when packages or OpenAPI specifications change.
+- Review evergreen concepts at least annually.
+- Remove “coming soon” promises unless they have an owner and a planned release.