diff --git a/.vitepress/config/en.ts b/.vitepress/config/en.ts
index f27a936e6c7..56facb3dd3d 100644
--- a/.vitepress/config/en.ts
+++ b/.vitepress/config/en.ts
@@ -50,44 +50,54 @@ export const enConfig = defineLocaleConfig("root", {
           items: [
             { text: "Overview", link: "/docs/guide/usage/linter" },
             {
-              text: "Configuring Oxlint",
-              link: "/docs/guide/usage/linter/config",
-            },
-            {
-              text: "Type-Aware Linting",
-              link: "/docs/guide/usage/linter/type-aware",
-            },
-            {
-              text: "Nested Configs",
-              link: "/docs/guide/usage/linter/nested-config",
-            },
-            {
-              text: "Rules",
-              link: "/docs/guide/usage/linter/rules",
-            },
-            {
-              text: "Plugins",
-              link: "/docs/guide/usage/linter/plugins",
-            },
-            {
-              text: "JS Plugins",
-              link: "/docs/guide/usage/linter/js-plugins",
-            },
-            {
-              text: "Automatic Fixes",
-              link: "/docs/guide/usage/linter/automatic-fixes",
-            },
-            {
-              text: "CLI reference",
-              link: "/docs/guide/usage/linter/cli",
+              text: "Configure and integrate",
+              items: [
+                { text: "Quickstart", link: "/docs/guide/usage/linter/quickstart" },
+                { text: "Configuration", link: "/docs/guide/usage/linter/config" },
+                { text: "Editor setup", link: "/docs/guide/usage/linter/editors" },
+                { text: "CI & other setup", link: "/docs/guide/usage/linter/ci" },
+                {
+                  text: "Nested configs",
+                  link: "/docs/guide/usage/linter/nested-config",
+                },
+              ],
             },
             {
-              text: "Configuration file reference",
-              link: "/docs/guide/usage/linter/config-file-reference",
+              text: "Features",
+              items: [
+                { text: "Built-in plugins", link: "/docs/guide/usage/linter/plugins" },
+                { text: "Automatic fixes", link: "/docs/guide/usage/linter/automatic-fixes" },
+                { text: "Ignore files", link: "/docs/guide/usage/linter/ignore-files" },
+                {
+                  text: "Inline ignore comments",
+                  link: "/docs/guide/usage/linter/ignore-comments",
+                },
+                {
+                  text: "Multi-file analysis",
+                  link: "/docs/guide/usage/linter/multi-file-analysis",
+                },
+                { text: "Type-aware linting", link: "/docs/guide/usage/linter/type-aware" },
+                { text: "JS plugins", link: "/docs/guide/usage/linter/js-plugins" },
+              ],
             },
+            // {
+            // text: "Migration",
+            // items: [
+            // { text: "From ESLint", link: "/docs/guide/usage/linter/migrate-from-eslint" },
+            // { text: "From Biome", link: "/docs/guide/usage/linter/migrate-from-biome" },
+            // ],
+            // },
             {
-              text: "Versioning",
-              link: "/docs/guide/usage/linter/versioning",
+              text: "Reference",
+              items: [
+                { text: "Rules reference", link: "/docs/guide/usage/linter/rules" },
+                { text: "CLI reference", link: "/docs/guide/usage/linter/cli" },
+                {
+                  text: "Config file reference",
+                  link: "/docs/guide/usage/linter/config-file-reference",
+                },
+                { text: "Versioning", link: "/docs/guide/usage/linter/versioning" },
+              ],
             },
           ],
         },
diff --git a/src/docs/guide/usage/linter.md b/src/docs/guide/usage/linter.md
index b75dfe77b1e..d08cd4cb4fa 100644
--- a/src/docs/guide/usage/linter.md
+++ b/src/docs/guide/usage/linter.md
@@ -1,241 +1,145 @@
 ---
-title: Linter
+title: Oxlint
 outline: deep
 badges:
   - src: https://img.shields.io/npm/dw/oxlint
     alt: npm weekly downloads
 ---
 
-# Linter (oxlint)
+# Oxlint
 
 <AppBadgeList />
 
-Oxlint (`/oh-eks-lint/`) is designed to catch erroneous or useless code without requiring any configurations by default.
+Oxlint (`/oʊ-ɛks-lɪnt/`) is a high-performance linter for JavaScript and TypeScript built on the Oxc compiler stack.
 
-:::info
-At this stage, Oxlint can be used to fully replace ESLint in small to medium projects.
+## Built for scale
 
-For larger projects, our current advice is to turn off ESLint rules via
-[eslint-plugin-oxlint](https://www.npmjs.com/package/eslint-plugin-oxlint),
-and run Oxlint before ESLint in your local or CI setup for a quicker feedback loop.
+Oxlint is built for large repositories and CI environments. Its architecture removes structural bottlenecks that limit performance in ESLint.
 
-Oxlint now supports JS plugins with an ESLint-compatible API. JS plugins support is currently experimental but,
-once stabilized, users will be able to migrate fully to Oxlint, running any ESLint rules/plugins that Oxlint
-doesn't support natively as JS plugins.
-:::
+Our [benchmarks](https://github.com/oxc-project/bench-linter) show Oxlint is 50 to 100 times faster than ESLint.
 
-## Features
+## Correctness focused defaults
 
-- 50 - 100 times faster than ESLint, and scales with the number of CPU cores
-  ([benchmark](https://github.com/oxc-project/bench-javascript-linter)).
-- Over 600 rules with a growing list from `eslint`, `typescript`, `eslint-plugin-react`,
-  `eslint-plugin-jest`, `eslint-plugin-unicorn`, `eslint-plugin-jsx-a11y` and
-  [many more](https://github.com/oxc-project/oxc/issues/481).
-- Supports
-  - [type-aware rules](./linter/type-aware) (alpha)
-  - [`.oxlintrc.json` configuration file](./linter/config)
-  - [Nested configuration file](./linter/nested-config)
-  - [Comment disabling](./linter/config.html#configuring-rules-via-inline-configuration-comments)
-  - [Automatic Fixes](./linter/automatic-fixes)
-  - [JS plugins](./linter/js-plugins) (experimental)
-
-## Language Support
-
-- Supports:
-  - JavaScript and TypeScript by their extensions `js`, `mjs`, `cjs`, `jsx`, `ts`, `mts`, `cts`, and `tsx`.
-  - `<script>` content of `.vue`, `.astro`, and `.svelte` files.
-  - [type-aware rules](https://typescript-eslint.io/getting-started/typed-linting) defined by
-    `typescript-eslint` (alpha, requires `--type-aware` flag and `oxlint-tsgolint` package).
-- No support for:
-  - [stylistic rules](https://eslint.style)
-
-## Installation
-
-Run `oxlint` directly at the root of your repository:
-
-::: code-group
-
-```sh [npm]
-$ npx oxlint@latest
-```
+Oxlint is useful out of the box. By default, it prioritizes high signal correctness checks. These checks surface code that is incorrect, unsafe, or useless, so teams can adopt Oxlint without excessive noise.
 
-```sh [pnpm]
-$ pnpm dlx oxlint@latest
-```
+Additional rules can be enabled incrementally as requirements evolve.
 
-```sh [yarn]
-$ yarn dlx oxlint@latest
-```
+## A large and growing rule set
 
-```sh [bun]
-$ bunx oxlint@latest
-```
+Oxlint includes more than 645 rules, with coverage across the ecosystems most teams already use, including:
 
-```sh [deno]
-$ deno run npm:oxlint@latest
-```
+- ESLint core rules
+- TypeScript rules
+- Popular plugins such as React, Jest, Unicorn, and JSX a11y
+- Custom JS plugins compatible with the ESLint plugin ecosystem
 
-:::
+This breadth makes migration straightforward without sacrificing rule coverage.
 
-Or save it to your package.json:
+## Type-aware linting
 
-::: code-group
+Oxlint leverages the native Go port of the TypeScript compiler ([tsgo](https://github.com/microsoft/typescript-go)), providing full TypeScript compatibility and the same type system behavior you expect from TypeScript itself.
 
-```sh [npm]
-$ npm add -D oxlint
-```
+This enables mission critical checks that require types, such as detecting floating promises.
 
-```sh [pnpm]
-$ pnpm add -D oxlint
-```
+In contrast, [Biome’s approach](https://biomejs.dev/blog/biome-v2) is to implement its own type inference instead of relying on the TypeScript compiler, and they note coverage is still improving.
 
-```sh [yarn]
-$ yarn add -D oxlint
-```
+See: [Type aware linting](/docs/guide/usage/linter/type-aware.md)
 
-```sh [bun]
-$ bun add -D oxlint
-```
+## Multi-file analysis
 
-:::
+Oxlint supports multi-file analysis as a first-class capability.
 
-### Type-Aware Linting (Alpha)
+When enabled, Oxlint builds a project-wide module graph and shares parsing and resolution across rules. This improves checks that depend on cross-file imports and helps avoid the performance cliff often seen with [`import/no-cycle`](https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/no-cycle.md) in ESLint.
 
-Oxlint supports type-aware rules in alpha. To enable type-aware linting:
+See: [Multi-file analysis](/docs/guide/usage/linter/multi-file-analysis.md)
 
-1. Install the required dependency:
+## AI friendly diagnostics
 
-::: code-group
+Oxlint diagnostics are designed to be both human readable and machine actionable.
 
-```sh [npm]
-$ npm add -D oxlint-tsgolint@latest
-```
+In addition to clear messages, diagnostics include structured information such as precise spans and contextual data. This helps AI to understand issues and apply fixes reliably.
 
-```sh [pnpm]
-$ pnpm add -D oxlint-tsgolint@latest
-```
+## Reliability as a priority
 
-```sh [yarn]
-$ yarn add -D oxlint-tsgolint@latest
-```
-
-```sh [bun]
-$ bun add -D oxlint-tsgolint@latest
-```
+Oxlint is built for workflows where failures are not acceptable.
 
-:::
-
-2. Run oxlint with the `--type-aware` flag:
-
-::: code-group
-
-```sh [npm]
-$ npx oxlint --type-aware
-```
+Crashes are treated as top priority bugs.
+Performance regressions are treated as bugs.
 
-```sh [pnpm]
-$ pnpm oxlint --type-aware
-```
+Stability and throughput are always prioritized, especially for CI and large monorepos.
 
-```sh [yarn]
-$ yarn oxlint --type-aware
-```
+## Get started
 
-```sh [bun]
-$ bunx oxlint --type-aware
-```
+The recommended setup is to install Oxlint as a dev dependency and add scripts.
 
-```sh [deno]
-$ deno run oxlint --type-aware
+```sh
+pnpm add -D oxlint
 ```
 
-:::
-
-For more details and the list of supported type-aware rules,
-see the [Type-Aware Linting](./linter/type-aware.md#configuration).
-
-## Command-line Interface
-
-See [Command-line Interface](./linter/cli)
-
-## Configuration File
-
-See [Configuration File](./linter/config)
-
-## Migrate from eslint flat config
-
-If you have an existing `eslint.config.*` file, you can convert it to an `.oxlintrc.json` config with
-[oxlint-migrate](https://github.com/oxc-project/oxlint-migrate).
-
-## Integration
-
-### ESLint
-
-If you are looking for a way to use oxlint in projects that still need ESLint, you can use
-[eslint-plugin-oxlint](https://github.com/oxc-project/eslint-plugin-oxlint) to turn off ESLint rules
-that are already supported by oxlint. So you can enjoy the speed of oxlint while still using ESLint.
-
-### lint-staged
+Add scripts to `package.json`:
 
 ```json [package.json]
 {
-  "lint-staged": {
-    "**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue,astro,svelte}": "oxlint"
+  "scripts": {
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix"
   }
 }
 ```
 
-### VS Code Extension
-
-Download the official VS Code extension from:
+Next steps:
 
-- [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode)
-- [Open VSX Registry](https://open-vsx.org/extension/oxc/oxc-vscode)
+- [Quickstart](/docs/guide/usage/linter/quickstart)
+- [Configuration](/docs/guide/usage/linter/config)
+- [Setup editors](/docs/guide/usage/linter/editors)
+- [Setup CI](/docs/guide/usage/linter/ci)
 
-It is also compatible with other VS Code-based editors like Cursor.
+## Adoption paths
 
-### Zed Extension
+Choose the approach that fits your repository:
 
-https://zed.dev/extensions?query=oxc
+- **Replace ESLint (recommended for most projects).** Use Oxlint as your primary linter.
+- **Migrate incrementally (recommended for large repos).** Run Oxlint first, then run ESLint with overlapping rules disabled. This keeps CI fast while you migrate.
+  <!-- - See [Migrate from ESLint](/docs/guide/usage/linter/migrate-from-eslint) for guidance and tooling such as [`oxlint-migrate`](https://github.com/oxc-project/oxlint-migrate). -->
+  - Use tooling such as [`oxlint-migrate`](https://github.com/oxc-project/oxlint-migrate).
+  - Use [`eslint-plugin-oxlint`](https://www.npmjs.com/package/eslint-plugin-oxlint) to disable overlapping ESLint rules while running both.
 
-### Continuous Integration
+## What Oxlint supports
 
-Since `oxlint` only takes a few seconds to run, we recommend running `oxlint` before ESLint for faster feedback loops.
+Oxlint supports:
 
-#### GitHub Actions
+- JavaScript and TypeScript (`.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, `.cts`)
+- JSX and TSX (`.jsx`, `.tsx`)
+- Framework files (`.vue`, `.svelte`, `.astro`) by linting only their `<script>` blocks
 
-```yaml
-jobs:
-  oxlint:
-    name: Lint JS
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: npx --yes oxlint@0.0.0 --deny-warnings # change to the latest release
-```
-
-It is advised to pin the version, otherwise CI may fail after a new release.
+## Features
 
-### pre-commit
+- [Native plugins](/docs/guide/usage/linter/plugins) for broad rule coverage with 645+ built-in rules, without a large JavaScript dependency tree.
+- [Automatic fixes](/docs/guide/usage/linter/automatic-fixes) to apply safe changes quickly.
+- [Ignore files](/docs/guide/usage/linter/ignore-files) to control which paths are linted.
+- [Inline ignore comments](/docs/guide/usage/linter/ignore-comments) for ignoring rules within a file.
+- [Multi-file analysis](/docs/guide/usage/linter/multi-file-analysis) for rules that require project-wide context such as import analysis like [no-cycle](/docs/guide/usage/linter/rules/import/no-cycle.html).
+- [Type-aware linting](/docs/guide/usage/linter/type-aware) for rules that require TypeScript type information.
+- [JS plugins](/docs/guide/usage/linter/js-plugins) (**experimental**) for compatibility with existing ESLint plugins.
 
-```yaml [.pre-commit-hooks.yaml]
-repos:
-  - repo: https://github.com/oxc-project/mirrors-oxlint
-    rev: v0.0.0 # change to the latest version
-    hooks:
-      - id: oxlint
-        verbose: true
-```
+## Projects using Oxlint
 
-### Unplugin
+Oxlint is used in production by popular projects such as:
 
-https://www.npmjs.com/package/unplugin-oxlint
+- [preactjs/preact](https://github.com/preactjs/preact)
+- [date-fns/date-fns](https://github.com/date-fns/date-fns)
+- [outline/outline](https://github.com/outline/outline)
+- [PostHog/posthog](https://github.com/PostHog/posthog)
+- [actualbudget/actual](https://github.com/actualbudget/actual)
 
-### Vite plugin
+<!-- ## Migration -->
 
-https://www.npmjs.com/package/vite-plugin-oxlint
+<!-- - [Migrate from ESLint](/docs/guide/usage/linter/migrate-from-eslint) -->
+<!-- - [Migrate from Biome](/docs/guide/usage/linter/migrate-from-biome) -->
 
-## System Requirements
+## Reference
 
-- **Node.js**: >= 20.19.0 or >= 22.12.0
-- **Platforms**: darwin-arm64, darwin-x64, linux-arm64, linux-x64, win32-arm64, and win32-x64
+- [Rules reference](/docs/guide/usage/linter/rules)
+- [CLI reference](/docs/guide/usage/linter/cli)
+- [Config file reference](/docs/guide/usage/linter/config-file-reference)
+- [Versioning policy](/docs/guide/usage/linter/versioning)
diff --git a/src/docs/guide/usage/linter/automatic-fixes.md b/src/docs/guide/usage/linter/automatic-fixes.md
index 5bd1e023d1f..6398b01dd56 100644
--- a/src/docs/guide/usage/linter/automatic-fixes.md
+++ b/src/docs/guide/usage/linter/automatic-fixes.md
@@ -1,49 +1,68 @@
-# Automatic Fixes
+---
+title: Automatic fixes
+description: Apply safe, suggested, and dangerous fixes with Oxlint.
+---
 
-In some cases, Oxlint is able to automatically fix lint violations in your code.
-There are two categories of automatic fixes:
+# Automatic fixes
 
-- **Fixes**: These are changes that will not change your program's behavior. It
-  is generally safe to run them in a pre-lint hook.
-- **Suggestions**: Changes that may change your program's behavior or make a
-  change you may not want (e.g. removing `console.log`s). These should be
-  reviewed before being committed to your codebase.
+Oxlint can automatically fix some lint violations. Automatic fixes are not enabled by default. You choose when to apply them.
 
-```sh
-oxlint --fix                   # Safe fixes only
-oxlint --fix-suggestions       # Safe suggestions only
-oxlint --fix --fix-suggestions # Safe fixes and suggestions
+## Safe fixes
+
+Safe fixes are changes that do not alter program behavior.
+
+Apply safe fixes:
+
+```bash
+oxlint --fix
 ```
 
-You can find which rules are fixable from the [rules page](./rules.md).
+## Suggestions
 
-## Dangerous Fixes and Suggestions
+Suggestions are changes that may alter behavior or may not match your intent.
 
-Some fixes and suggestions are considered dangerous. Being more aggressive in
-nature, **these may produce invalid code and/or change the behavior of your
-program**. These are disabled by default and can be enabled with the
-`--fix-dangerously` flag. You should review each change carefully before
-committing it to your codebase.
+Apply suggestions:
+
+```bash
+oxlint --fix-suggestions
+```
 
-:::warning
-If you are using git, you should stage your changes before running any of the
-commands below using `git add -A`.
-:::
+## Dangerous fixes
 
-```sh
-# Safe and dangerous fixes only
+Dangerous fixes are aggressive changes that may break your code.
+
+Apply dangerous fixes:
+
+```bash
 oxlint --fix-dangerously
+```
+
+## Combining fix modes
 
-# Safe and dangerous suggestions only
-oxlint --fix-suggestions --fix-dangerously
+You can combine safe fixes and suggestions:
 
-# Applies all possible fixes and suggestions
+```bash
+oxlint --fix --fix-suggestions
+```
+
+You can also include dangerous fixes:
+
+```bash
 oxlint --fix --fix-suggestions --fix-dangerously
 ```
 
-## Pending Fixes
+## Rule support
+
+Not all rules provide fixes. Some rules support safe fixes, some provide suggestions, and some do not provide fixes yet.
+
+If a rule is missing a fixer, contributions are welcome.
 
-You may notice that some rules have a 🚧 next to their name. This indicate that
-they could be automatically fixed, but they are missing an auto-fixer
-implementation. You can help improve Oxlint by contributing an auto fixer for
-rules that need them.
+## Type aware linting and fixes
+
+Type aware linting requires building the project.
+
+You can apply safe fixes with type aware linting enabled:
+
+```bash
+oxlint --type-aware --fix
+```
diff --git a/src/docs/guide/usage/linter/ci.md b/src/docs/guide/usage/linter/ci.md
new file mode 100644
index 00000000000..08f38a69c06
--- /dev/null
+++ b/src/docs/guide/usage/linter/ci.md
@@ -0,0 +1,54 @@
+---
+title: CI setup
+description: Run Oxlint in CI.
+---
+
+# Setup CI
+
+## GitHub Actions
+
+Create `.github/workflows/oxlint.yml`:
+
+```yaml
+name: Lint
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  oxlint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: pnpm
+
+      - uses: pnpm/action-setup@v4
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint --deny-warnings # given package.json scripts "lint": "oxlint"
+```
+
+### pre-commit
+
+```yaml [.pre-commit-hooks.yaml]
+repos:
+  - repo: https://github.com/oxc-project/mirrors-oxlint
+    rev: v0.0.0 # change to the latest version
+    hooks:
+      - id: oxlint
+        verbose: true
+```
+
+### Unplugin
+
+https://www.npmjs.com/package/unplugin-oxlint
+
+### Vite plugin
+
+https://www.npmjs.com/package/vite-plugin-oxlint
diff --git a/src/docs/guide/usage/linter/config.md b/src/docs/guide/usage/linter/config.md
index ac590dffd25..df621dad28d 100644
--- a/src/docs/guide/usage/linter/config.md
+++ b/src/docs/guide/usage/linter/config.md
@@ -1,189 +1,214 @@
 ---
-editLink: false
+title: Configuration
+description: Configure Oxlint using a .oxlintrc.json file.
 ---
 
-# Configuring Oxlint
+# Configuration
 
-This is a general overview of how to configure Oxlint for linting your project. There are several ways of configuring Oxlint:
+Oxlint works out of the box, but most teams commit a configuration file to keep linting consistent across local runs, editors, and CI.
 
-1. **Configuration files**, which can be passed to Oxlint via the `--config` option.
-2. **Inline comments**, which can be used to enable/disable specific rules for a specific section of code.
-3. **CLI options**, which can be used to override configuration files or specify inputs and outputs. (See [command-line interface](./cli.md) for more information.)
+This page focuses on project configuration: rules, categories, plugins, overrides, and shared settings.
 
-This page will mostly cover how to use configuration files, as they are the primary way of configuring Oxlint, but also includes information on how to use inline comments and CLI options. In general, inline comments and command-line arguments take precedence over the configuration file.
+## Create a config file
+
+To generate a starter config in the current directory:
+
+```sh
+oxlint --init
+```
+
+Oxlint automatically looks for a `.oxlintrc.json` in the current working directory. You can also pass a config explicitly:
+
+```sh
+oxlint -c ./oxlintrc.json
+# or
+oxlint --config ./oxlintrc.json
+```
+
+Notes:
+
+- Only `.json` config files are supported, and configuration files support comments (JSONC).
+- The configuration format aims to be compatible with ESLint v8 (`eslintrc.json`).
+
+A minimal configuration looks like this:
+
+```jsonc [.oxlintrc.json]
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "categories": {
+    "correctness": "warn",
+  },
+  "rules": {
+    "eslint/no-unused-vars": "error",
+  },
+}
+```
 
 ## Configuration file format
 
-Configuration files for Oxlint are written in JSON, with support for comments (JSONC). Oxlint will automatically search for files named `.oxlintrc.json` and automatically use those. But you can name the file anything when you are using the `--config` CLI option.
+A configuration file is a JSON object. The most common top-level fields are:
 
-A configuration file is a JSON object with top-level properties that will change how Oxlint behaves. Some of the most important properties are:
+- `rules`: Enable or disable rules, set severity, and configure rule options.
+- `categories`: Enable groups of rules with similar intent.
+- `plugins`: Enable built-in plugins that provide additional rules.
+- `jsPlugins`: Configure JavaScript plugins (experimental).
+- `overrides`: Apply different configuration to different file patterns.
+- `extends`: Inherit configuration from other files.
+- `ignorePatterns`: Ignore additional files from the config file.
+- `env`: Enable predefined globals for common environments.
+- `globals`: Declare custom globals as read-only or writable.
+- `settings`: Plugin-wide configuration shared by multiple rules.
 
-- `rules`: Configures what lint rules are enabled or disabled, their severity, and any rule-specific options.
-- `plugins`: Extends the set of available rules with built-in plugins specific to certain frameworks or file types.
-- `categories`: Enables groups of lint rules which have similar behavior or purpose, such as stylistic rules or correctness rules.
-- `ignorePatterns`: Specifies file patterns to ignore when searching for lintable files.
-- `env`: Enables sets of global variables which are known to be predefined based on the environment.
-- `globals`: Declares individual global variables as predefined and read-only or writable, and also allows for global variables to be removed from the base set.
-- `settings`: Adds configuration for plugins that apply to several rules at once.
+For a complete list of fields, see the [Config file reference](/docs/guide/usage/linter/config-file-reference.html).
 
-## Configuring rules
+## Configure rules
 
-Rules can be configured in a configuration file using the `rules` property. Rules are declared using the plugin name and rule name as the key, and either a string severity level, or an array with the severity level as the first element and an object with rule-specific options as the second element.
+Rules are configured under `rules`.
 
-If a rule's name is unique, it can also be configured without specifying the plugin name. For example: `eslint/no-console` is the same rule as `no-console`.
+A rule value is either:
+
+- a severity (`"off"`, `"warn"`, `"error"`), or
+- an array of `[severity, options]`
+
+If a rule name is unique, you can configure it without a plugin prefix. For example, `no-console` is the same as `eslint/no-console`.
 
 ```jsonc
 {
   "rules": {
-    "no-alert": "error", // Emit an error message when a call to `alert()` is found
-    "oxc/approx-constant": "warn", // Show a warning when you write a number close to a known constant
-    "no-plusplus": "off", // Allow using the `++` and `--` operators
+    "no-alert": "error",
+    "oxc/approx-constant": "warn",
+    "no-plusplus": "off",
   },
 }
 ```
 
-The allowed severity levels are:
+### Severity values
+
+Oxlint accepts ESLint-style severities:
 
 - Allow rule: `"off"`, `0`, `"allow"`
 - Warning on rule: `"warn"`, `1`
 - Error on rule: `"error"`, `2`, `"deny"`
 
-To configure a rule with rule-specific options, use an array with the severity level as the first element, and an object with the rule-specific options as the second element. For example:
+### Rule options
+
+To configure rule options, use an array:
 
 ```jsonc
 {
   "rules": {
-    // Generally error on `x++`, but allow it be used in a for-loop, like `for (let x = 0; x < 10; x++)`
     "no-plusplus": ["error", { "allowForLoopAfterthoughts": true }],
   },
 }
 ```
 
-All of the available rules can be found on the [rules reference](./rules.md) page.
+All available rules are listed in the [Rules reference](/docs/guide/usage/linter/rules).
+
+### Override severity from the CLI
 
-### Configuring rules via the command-line
+For quick experiments, you can adjust severity from the command line using:
 
-In the command-line, you can change the severity of a lint rule to allow, warn, or deny, using the `-A` (`--allow`), `-W` (`--warn`), and `-D` (`--deny`) options, respectively:
+- `-A` / `--allow`
+- `-W` / `--warn`
+- `-D` / `--deny`
+
+Arguments are applied from left to right:
 
 ```sh
 oxlint -D no-alert -W oxc/approx-constant -A no-plusplus
 ```
 
-### Configuring rules via inline configuration comments
-
-Rules can also be enabled or disabled for specific sections of code using inline comments. Comments can be line comments (`//`) or block comments (`/* */`), and must start with a specific directive. These directives are:
-
-- `oxlint-disable`: Disable one or more rules until the end of the file, or it is re-enabled with another comment
-
-  ```javascript
-  // Disable oxlint for the rest of the file
-  /* oxlint-disable */
-
-  // Disable the `no-console` rule in this file
-  /* oxlint-disable no-console */
-
-  // Disable multiple rules in this file
-  /* oxlint-disable no-console, no-alert */
-  ```
-
-- `oxlint-enable`: Enable one or more rules until the end of the file, or it is disabled with another comment
-
-  ```javascript
-  // Enable the `no-console` rule in this file
-  /* oxlint-enable no-console */
-
-  // Enable multiple rules in this file
-  /* oxlint-enable no-console, no-alert */
-  ```
-
-- `oxlint-disable-line`: Disable one or more rules on the current line
-
-  ```javascript
-  console.log("Hello, world!"); // oxlint-disable-line no-console
-  // Disable multiple rules on this line
-  console.log(x++); // oxlint-disable-line no-console, no-plusplus
-  ```
-
-- `oxlint-enable-line`: Enable one or more rules on the current line
-- `oxlint-disable-next-line`: Disable one or more rules on the line following the comment, then re-enable it
-
-  ```javascript
-  // oxlint-disable-next-line no-console
-  console.log("Hello, world!"); // allowed because of the previous comment
-  console.log(x++); // not allowed because the previous comment only applied to the previous line
+## Enable groups of rules with categories
 
-  // oxlint-disable-next-line no-console, no-plusplus
-  console.log("Hello, world!"); // allowed
-  ```
+Categories let you enable or disable sets of rules with similar intent. By default, Oxlint enables rules in the `correctness` category.
 
-- `oxlint-enable-next-line`: Enable one or more rules on the line following the comment, then re-enable it
-
-Oxlint does not support modifying the configuration of a lint rule through inline comments. If you need to change the configuration of a rule, you should use a configuration file instead. Oxlint also supports all of the following directives with `oxlint` replaced with `eslint` for compatibility with ESLint, such as `/* eslint-disable */` or `// eslint-disable-next-line`. We recommend preferring `oxlint-*`, and using `eslint-*` only for rules that Oxlint doesn't support yet.
-
-### Enabling groups of rules (categories)
-
-Each lint rule belongs to a category, which describes the general purpose or behavior of the rule. By default, `oxlint` enables all rules in the `correctness` category. Categories can be enabled with the `category` property in a configuration file.
+Configure categories using `categories`:
 
 ```jsonc
 {
-  // Enable all rules in the `correctness` and `suspicious` categories
   "categories": {
     "correctness": "error",
     "suspicious": "warn",
+    "pedantic": "off",
   },
 }
 ```
 
-The available categories are:
+Available categories include:
 
-- `correctness`: Rules to lint code that is definitely wrong or useless
-- `suspicious`: Rules to lint code that is likely to be wrong or useless
-- `pedantic`: Rules which are extra strict or might have false positives
-- `perf`: Rules that aim to improve the performance of code
-- `style`: Rules that help maintain a consistent style or enforce idiomatic syntax
-- `restriction`: Rules that ban specific patterns, syntax, or features and should be enabled on a case-by-case basis
-- `nursery`: Rules that are in development, may change significantly, or contain false positives
+- `correctness`: Code that is definitely wrong or useless
+- `suspicious`: Code that is likely to be wrong or useless
+- `pedantic`: Extra strict rules that may have false positives
+- `perf`: Rules that aim to improve runtime performance
+- `style`: Idiomatic and consistent style rules
+- `restriction`: Rules that ban specific patterns or features
+- `nursery`: Rules under development that may change
 
-Categories can also be enabled or disabled in the command line using the same `-A` (allow), `-W` (warn) and `-D` (deny) options used to configure rules:
+You can also change categories from the CLI with the same `-A`, `-W`, and `-D` options:
 
 ```sh
-# Enable all correctness and suspicious rules
-oxlint -D correctness -D pedantic
+oxlint -D correctness -D suspicious
 ```
 
-### Configuring plugins
+## Configure plugins
 
-Plugins are used to extend the set of available rules with built-in plugins specific to certain frameworks or file types. By default, Oxlint enables several plugins which are useful to most codebases.
+Plugins extend the set of available rules.
 
-Plugins can be enabled with the `plugins` property in a configuration file. The value of the `plugins` property is an array of plugin names, and it overwrites the default set of plugins. For example:
+Oxlint supports many popular plugins natively in Rust. This provides broad rule coverage without a large JavaScript dependency tree. See [Native Plugins](/docs/guide/usage/linter/plugins).
+
+Configure plugins using `plugins`. Setting `plugins` overwrites the default plugin set, so the array should include everything you want enabled:
 
 ```jsonc
 {
-  // Enable all of these plugins (which are enabled by default):
   "plugins": ["unicorn", "typescript", "oxc"],
 }
 ```
 
-Default plugins can be disabled by setting an empty array as the value of the `plugins` property. For example:
+To disable all default plugins:
 
 ```jsonc
 {
-  // Disable all default plugins
   "plugins": [],
 }
 ```
 
-For more details, see the [plugins](./plugins.md) page.
+For plugin details and CLI flags such as `--import-plugin`, see [Native Plugins](/docs/guide/usage/linter/plugins).
+
+## Configure JS plugins (experimental)
 
-### Overriding rule configurations
+Oxlint also supports JavaScript plugins via `jsPlugins`. This is intended for compatibility and advanced integrations.
 
-Rule configurations can be changed depending on the file path, and this is done using the `overrides` property in a configuration file. The value of the `overrides` property is an array of objects, each with the following supported properties:
+Notes:
 
-- `files`: A glob pattern to match file paths against
-- `rules`: A rules configuration object (same as the top-level `rules` property)
-- `env`: An `env` configuration object (same as the top-level `env` property)
-- `plugins`: A `plugins` configuration object (same as the top-level `plugins` property), except plugins will append to the top-level `plugins` property instead of overwriting it
-- `globals`: A `globals` configuration object (same as the top-level `globals` property)
+- JS plugins are experimental and not subject to semver.
+- JS plugins are not supported in the language server at present.
+
+JS plugins can be declared as strings or as objects with an alias:
+
+```jsonc
+{
+  "jsPlugins": [{ "name": "my-eslint-react", "specifier": "eslint-plugin-react" }],
+}
+```
+
+Some plugin names are reserved because they are implemented natively in Rust (for example `react`, `unicorn`, `typescript`, `oxc`, `import`, `jest`, `vitest`, `jsx-a11y`, `nextjs`). If you need the JavaScript version of a reserved plugin, give it a custom `name` to avoid conflicts.
+
+For details, see [JS plugins](/docs/guide/usage/linter/js-plugins).
+
+## Apply configuration by file pattern
+
+Use `overrides` to apply different configuration to different files, such as tests, scripts, or TypeScript-only paths.
+
+`overrides` is an array of objects. Each override can include:
+
+- `files`: glob patterns
+- `rules`: rule configuration (same shape as top-level `rules`)
+- `env`: environment configuration (same shape as top-level `env`)
+- `globals`: globals configuration (same shape as top-level `globals`)
+- `plugins`: optionally change what plugins are enabled for this override
+- `jsPlugins`: JS plugins for this override (experimental)
+
+Example:
 
 ```jsonc
 {
@@ -194,12 +219,10 @@ Rule configurations can be changed depending on the file path, and this is done
     {
       "files": ["scripts/*.js"],
       "rules": {
-        // Allow `console.*` calls in scripts
         "no-console": "off",
       },
     },
     {
-      // Enable TypeScript-specific rules for TypeScript files
       "files": ["**/*.{ts,tsx}"],
       "plugins": ["typescript"],
       "rules": {
@@ -207,7 +230,6 @@ Rule configurations can be changed depending on the file path, and this is done
       },
     },
     {
-      // Enable Jest rules for tests
       "files": ["**/test/**"],
       "plugins": ["jest"],
       "env": {
@@ -221,51 +243,71 @@ Rule configurations can be changed depending on the file path, and this is done
 }
 ```
 
-## Specifying files to process
+## Extend shared configs
 
-The primary way of specifying files to process is by passing a file path as an argument to the `oxlint` command. By default, files in the current directory and below will be processed. Additionally, `oxlint` will automatically lint all files that have one of the following extensions:
+Use `extends` to inherit from other configuration files.
 
-- `.js`
-- `.jsx`
-- `.mjs`
-- `.cjs`
-- `.ts`
-- `.tsx`
-- `.mts`
-- `.cts`
-- `.astro` _\*_
-- `.svelte` _\*_
-- `.vue` _\*_
+Paths in `extends` are resolved relative to the configuration file that declares `extends`. Configs are merged from first to last, with later entries overriding earlier ones.
 
-_\*Note: Supports only the `<script>` content, ignores the rest. For Astro, both the frontmatter and component script are linted._
+```jsonc
+{
+  "extends": ["./configs/base.json", "./configs/frontend.json"],
+}
+```
+
+## Configure environments and globals
+
+Use `env` to enable predefined globals for common environments such as browser or node.
 
-### Ignoring files
+Use `globals` to declare project-specific globals, mark them writable or readonly, or disable a global that would otherwise be present.
 
-#### Files automatically ignored by Oxlint
+```jsonc
+{
+  "env": {
+    "es6": true,
+  },
+  "globals": {
+    "MY_GLOBAL": "readonly",
+    "Promise": "off",
+  },
+}
+```
 
-By default, Oxlint automatically ignores the following:
+`globals` accepts:
 
-- **`.git` directories**: Always skipped to avoid linting version control metadata
-- **Minified files**: Files containing `.min.`, `-min.`, or `_min.` in their names (e.g., `bundle.min.js`, `vendor-min.js`)
-- **Files in `.gitignore`**: Respected even without a Git repository. Note that global `.gitignore` files are NOT respected.
-- **Files in `.eslintignore`**: By default, Oxlint reads the `.eslintignore` file in your project root
+- `"readonly"` or `"readable"` or `false`
+- `"writable"` or `"writeable"` or `true`
+- `"off"` to disable a global
 
-**Note**: Hidden files (files starting with `.`) are NOT automatically ignored by Oxlint.
+## Plugin settings
 
-#### Custom ignore patterns
+Use `settings` for plugin-wide configuration shared by multiple rules.
 
-You can ignore additional patterns of files by configuring the `ignorePatterns` property in a configuration file. The value of the `ignorePatterns` property is an array of file patterns (globs), which are resolved relative to the location of the configuration file.
+Example (monorepo + React + jsx-a11y):
 
 ```jsonc
 {
-  "ignorePatterns": ["vendor", "test/snapshots/**", "test.js"],
+  "settings": {
+    "next": {
+      "rootDir": "apps/dashboard/",
+    },
+    "react": {
+      "linkComponents": [{ "name": "Link", "linkAttribute": "to" }],
+    },
+    "jsx-a11y": {
+      "components": {
+        "Link": "a",
+        "Button": "button",
+      },
+    },
+  },
 }
 ```
 
-#### Disabling file ignoring
-
-To disable all automatic file ignoring (including `.gitignore` and `.eslintignore`), use the `--no-ignore` command-line flag. You can also specify a custom ignore file with `--ignore-path` or add additional patterns with `--ignore-pattern`. See the [CLI documentation](./cli.md) for more details.
-
-### .eslintignore
+## Next steps
 
-Oxlint works with existing [.eslintignore](https://eslint.org/docs/latest/use/configure/ignore#the-eslintignore-file) files.
+- [Ignore files](/docs/guide/usage/linter/ignore-files): Ignore files and patterns, `.gitignore` and `.eslintignore` workflows, and symlink behavior.
+- [Inline ignore comments](/docs/guide/usage/linter/ignore-comments): Inline suppressions and scoped exceptions.
+- [Nested configs](/docs/guide/usage/linter/nested-config): Monorepos and per-package configuration.
+- [Config file reference](/docs/guide/usage/linter/config-file-reference.html): Full schema and field documentation.
+- [CLI reference](/docs/guide/usage/linter/cli.html): Complete list of flags and output formats.
diff --git a/src/docs/guide/usage/linter/editors.md b/src/docs/guide/usage/linter/editors.md
new file mode 100644
index 00000000000..e156b73eb47
--- /dev/null
+++ b/src/docs/guide/usage/linter/editors.md
@@ -0,0 +1,112 @@
+---
+outline: 2
+---
+
+# Setup editors
+
+Oxlint editor extensions start the language server with `oxlint --lsp` from your **project installation**, so `oxlint` must be installed in the project.
+
+See [Quickstart](./quickstart) to install and run Oxlint from the command line.
+
+## Supported editors
+
+- [VS Code](#vs-code)
+- [Zed](#zed)
+- [JetBrains](#jetbrains)
+- [coc.nvim](#cocnvim)
+- [Other editors](#other-editors)
+
+## VS Code
+
+### Install
+
+Download the official Oxc VS Code extension from:
+
+- [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode)
+- [Open VSX Registry](https://open-vsx.org/extension/oxc/oxc-vscode)
+
+The extension is also compatible with other VS Code-based editors, including Cursor.
+
+### Use (recommended setup for teams)
+
+1. Recommend the extension in your repository so contributors install the same tooling.
+
+Create `.vscode/extensions.json`:
+
+```json
+{
+  "recommendations": ["oxc.oxc-vscode"]
+}
+```
+
+2. Enable fix on save (optional).
+
+Add to `.vscode/settings.json`:
+
+```jsonc
+{
+  "editor.codeActionsOnSave": {
+    "source.fixAll.oxc": true,
+  },
+}
+```
+
+### Usage and configuration reference
+
+- [https://github.com/oxc-project/oxc/tree/main/editors/vscode](https://github.com/oxc-project/oxc/tree/main/editors/vscode)
+
+## Zed
+
+### Install
+
+- [Oxc Zed Extension](https://zed.dev/extensions/oxc)
+
+### Use
+
+Configure the extension in Zed’s `settings.json` (workspace or user settings), then open your project as a folder/workspace.
+
+### Usage and configuration reference
+
+- [https://github.com/oxc-project/oxc-zed](https://github.com/oxc-project/oxc-zed)
+
+---
+
+## JetBrains
+
+IntelliJ IDEA and WebStorm
+
+### Install
+
+- [Oxc in JetBrains Marketplace](https://plugins.jetbrains.com/plugin/27061-oxc)
+
+### Use
+
+Install the plugin, restart the IDE, and open your repository as a project.
+
+### Usage and configuration reference
+
+- [https://github.com/oxc-project/oxc-intellij-plugin](https://github.com/oxc-project/oxc-intellij-plugin)
+
+## coc.nvim
+
+### Install
+
+```vim
+:CocInstall coc-oxc
+```
+
+### Usage and configuration reference
+
+- [https://github.com/oxc-project/coc-oxc](https://github.com/oxc-project/coc-oxc)
+
+## Other editors
+
+If your editor supports custom LSP configuration (Neovim LSP, Emacs, Helix, Sublime LSP, etc.), configure it to launch:
+
+```bash
+oxlint --lsp
+```
+
+### Reference (language server implementation and issues)
+
+- [https://github.com/oxc-project/oxc/tree/main/crates/oxc_language_server](https://github.com/oxc-project/oxc/tree/main/crates/oxc_language_server)
diff --git a/src/docs/guide/usage/linter/ignore-comments.md b/src/docs/guide/usage/linter/ignore-comments.md
new file mode 100644
index 00000000000..7aa34c0b457
--- /dev/null
+++ b/src/docs/guide/usage/linter/ignore-comments.md
@@ -0,0 +1,102 @@
+---
+title: Inline ignore comments
+description: Disable specific rules inline using Oxlint ignore comments
+---
+
+# Inline ignore comments
+
+Ignore comments provide an escape hatch for exceptional cases where a rule is correct in general but needs to be suppressed in a small, well scoped section of code. Inline comments override configuration files.
+
+Oxlint supports line comments (`//`) and block comments (`/* */`). Comments must start with one of the keywords below.
+
+## oxlint-disable
+
+Disable one or more rules until the end of the file, or until they are re enabled.
+
+```js
+// Disable Oxlint for the rest of the file
+/* oxlint-disable */
+
+// Disable a single rule in this file
+/* oxlint-disable no-console */
+
+// Disable multiple rules in this file
+/* oxlint-disable no-console, no-alert */
+```
+
+## oxlint-enable
+
+Enable one or more rules until the end of the file, or until they are disabled again.
+
+```js
+/* oxlint-enable no-console */
+
+/* oxlint-enable no-console, no-alert */
+```
+
+## oxlint-disable-line
+
+Disable one or more rules on the current line.
+
+```js
+console.log("Hello, world!"); // oxlint-disable-line no-console
+
+console.log(x++); // oxlint-disable-line no-console, no-plusplus
+```
+
+## oxlint-enable-line
+
+Enable one or more rules on the current line.
+
+```js
+// oxlint-enable-line no-console
+```
+
+## oxlint-disable-next-line
+
+Disable one or more rules on the line following the comment, then re enable them automatically.
+
+```js
+// oxlint-disable-next-line no-console
+console.log("Hello, world!"); // allowed because of the previous comment
+console.log(x++); // not allowed because the previous comment only applied to the previous line
+
+// oxlint-disable-next-line no-console, no-plusplus
+console.log("Hello, world!"); // allowed
+```
+
+## oxlint-enable-next-line
+
+Enable one or more rules on the line following the comment, then re enable automatically.
+
+```js
+// oxlint-enable-next-line no-console
+```
+
+## ESLint compatibility
+
+For compatibility with existing ESLint codebases, the same keywords are supported with `oxlint` replaced by `eslint`, such as `/* eslint-disable */` and `// eslint-disable-next-line`.
+
+The `oxlint-*` form is recommended. The `eslint-*` form is useful during migration for rules that Oxlint does not support yet.
+
+## Rule options cannot be changed inline
+
+Ignore comments can enable or disable rules, but they cannot change rule options. Rule options belong in configuration files.
+
+## Report unused ignore comments
+
+Reporting unused ignore comments is disabled by default. When enabled, Oxlint reports comments such as `// oxlint-disable-line` when no diagnostics would have been reported on that line.
+
+Enable reporting:
+
+```bash
+oxlint --report-unused-disable-directives
+```
+
+Specify the severity:
+
+```bash
+oxlint --report-unused-disable-directives-severity error
+```
+
+Only one of these options can be used at a time.
diff --git a/src/docs/guide/usage/linter/ignore-files.md b/src/docs/guide/usage/linter/ignore-files.md
new file mode 100644
index 00000000000..4179e1b8a0d
--- /dev/null
+++ b/src/docs/guide/usage/linter/ignore-files.md
@@ -0,0 +1,77 @@
+---
+title: Ignores
+description: Control which files Oxlint lints.
+---
+
+# Ignore files
+
+Large repositories contain files that should not be linted, such as build output, vendored code, snapshots, or generated artifacts. Oxlint provides a predictable ignore model that works well in monorepos and CI.
+
+## Default ignores
+
+Oxlint automatically ignores:
+
+- `.git` directories
+- Minified files containing `.min.`, `-min.`, or `_min.` in the file name
+- Files matched by `.gitignore` (global gitignore files are not respected)
+
+Hidden files are not automatically ignored.
+
+## `ignorePatterns`
+
+The recommended approach is to define ignores in `.oxlintrc.json` using `ignorePatterns`. This keeps ignores close to the configuration they belong to and works naturally with nested configs.
+
+Patterns are resolved relative to the configuration file.
+
+```jsonc
+{
+  "ignorePatterns": ["dist/**", "coverage/**", "vendor/**", "test/snapshots/**"],
+}
+```
+
+In monorepos, nested configs can ignore package specific output without affecting the rest of the repository.
+
+## .oxlintignore
+
+For repositories that prefer an ignore file, use `.oxlintignore`. The syntax is compatible with `.gitignore`, including comments and negation patterns.
+
+Oxlint also supports `.eslintignore` for compatibility with existing ESLint setups. Existing `.eslintignore` files can remain in place during migration. New projects should prefer `ignorePatterns` in `.oxlintrc.json`.
+
+## Ignore from the command line
+
+CLI flags are useful for one off changes in CI or local debugging.
+
+Use a custom ignore file:
+
+```bash
+oxlint --ignore-path path/to/ignorefile
+```
+
+Add additional ignore patterns:
+
+```bash
+oxlint --ignore-pattern 'dist/**' --ignore-pattern 'coverage/**'
+```
+
+Quote patterns to avoid shell glob expansion.
+
+## Unignoring files
+
+Ignore files support negation patterns, which allow a directory to be ignored while keeping specific files.
+
+To ignore everything under `build/` except one file, ignore the contents rather than the directory itself:
+
+```text [.oxlintignore]
+build/**/*
+!build/keep.js
+```
+
+This keeps traversal possible while still ignoring almost everything.
+
+## Disable ignoring
+
+To disable all ignore behavior, including ignore files and CLI ignore options, use `--no-ignore`:
+
+```bash
+oxlint --no-ignore
+```
diff --git a/src/docs/guide/usage/linter/multi-file-analysis.md b/src/docs/guide/usage/linter/multi-file-analysis.md
new file mode 100644
index 00000000000..aa56c693e90
--- /dev/null
+++ b/src/docs/guide/usage/linter/multi-file-analysis.md
@@ -0,0 +1,46 @@
+---
+title: Multi-file analysis
+description: Project-wide linting for import cycles and cross-file issues
+---
+
+# Multi-file analysis
+
+Multi-file analysis allows rules to use project-wide information, such as the module dependency graph, instead of analyzing each file in isolation.
+
+## Performance and architecture
+
+ESLint evaluates rules per file and does not provide a built-in project graph. Plugins such as
+[`eslint-plugin-import`](https://github.com/import-js/eslint-plugin-import) must rebuild module resolution and the module graph outside of ESLint’s core, and projects report `import/no-cycle` taking tens of seconds to over a minute on large repositories.
+
+Oxlint implements multi-file analysis in the core engine. It lints files and builds the module graph in parallel, shares parsing and resolution across rules, and typically completes comparable `import/no-cycle` checks in a few seconds.
+
+## Enable the import plugin
+
+To use multi-file analysis, you must enable the `import` plugin and configure at
+least one `import/*` rule.
+
+## Detect cycles with `import/no-cycle`
+
+Enable
+[`import/no-cycle`](/docs/guide/usage/linter/rules/import/no-cycle.html)
+to detect circular dependencies.
+
+Import cycles:
+
+- obscure dependency direction
+- make refactors harder
+- can cause imported values to be `undefined` due to evaluation order
+
+```json [.oxlintrc.json]
+{
+  "plugins": ["import"],
+  "rules": {
+    "import/no-cycle": ["error", { "maxDepth": 3 }]
+  }
+}
+```
+
+## TypeScript path aliases
+
+When running `import/*` rules, Oxlint automatically discovers `tsconfig.json`
+to resolve TypeScript path aliases such as `compilerOptions.paths`.
diff --git a/src/docs/guide/usage/linter/nested-config.md b/src/docs/guide/usage/linter/nested-config.md
index c94218517d1..fb3cd8564de 100644
--- a/src/docs/guide/usage/linter/nested-config.md
+++ b/src/docs/guide/usage/linter/nested-config.md
@@ -1,12 +1,21 @@
 ---
-editLink: false
+title: Nested configuration files
+description: Use multiple .oxlintrc.json files to apply different Oxlint settings to different parts of a repository.
 ---
 
 # Nested configuration files
 
-It is possible to have multiple configuration files within the same project. Oxlint will automatically detect the presence of these files and use them in addition to the top-level configuration file. Config files must be named `.oxlintrc.json` for nested configuration to work.
+Oxlint can use multiple configuration files in the same repository. It automatically detects configuration files named `.oxlintrc.json` and applies them based on where files live in the directory tree.
 
-For example, consider the following project structure:
+This is useful in monorepos where packages need their own settings, while still keeping a shared baseline.
+
+If you only need to exclude files or folders, use [Ignores](./ignore-files) instead.
+
+## How it works
+
+For each file being linted, Oxlint uses the nearest `.oxlintrc.json` relative to that file.
+
+Given the following structure:
 
 ```
 my-project/
@@ -21,36 +30,78 @@ my-project/
     └── index.js
 ```
 
-Oxlint will always use the nearest configuration file to the file currently being processed and use that for linting. In the example above, that means:
+Configuration resolution works as follows:
+
+- `src/index.js` uses `my-project/.oxlintrc.json`
+- `package1/index.js` uses `my-project/package1/.oxlintrc.json`
+- `package2/index.js` uses `my-project/package2/.oxlintrc.json`
+
+## What to expect
+
+Configuration files are not automatically merged. A config in a child directory does not affect the parent config.
+
+Command line options override configuration files, regardless of whether they come from a parent or child directory.
+
+Passing `--config` disables nested config lookup and applies a single configuration file.
+
+## Monorepo pattern: share a base config with extends
+
+In a monorepo, you often want one shared baseline at the root, and small package specific adjustments.
+
+You do this by keeping a root `.oxlintrc.json`, then having package configs extend it.
+
+`my-project/.oxlintrc.json`
+
+```json
+{
+  "rules": {
+    "no-debugger": "error"
+  }
+}
+```
+
+`my-project/package1/.oxlintrc.json`
 
-- `src/index.js` will be linted using `my-project/.oxlintrc.json`
-- `package1/index.js` will be linted using `my-project/package1/.oxlintrc.json`
-- `package2/index.js` will be linted using `my-project/package2/.oxlintrc.json`
+```json
+{
+  "extends": ["../.oxlintrc.json"],
+  "rules": {
+    "no-console": "off"
+  }
+}
+```
 
-Configuration files are not automatically merged, and the configuration in a child configuration file will not affect the parent configuration. However, options passed in the command-line will override any configuration file, regardless of whether it is in the parent or child directory. In addition, using the `--config` option to specify a single file for configuration will disable the use of nested configuration files.
+This keeps the shared baseline in one place and makes package configs small and focused.
 
 ## Extending configuration files
 
-Files can use configuration from other files by using the `extends` property in a configuration file. The value of the `extends` property is an array of file paths to other configuration files, which are resolved relative to the location of the configuration file. Files may be called anything and do not need to be called `.oxlintrc.json`, but still need to be valid JSON configuration files.
+A config can reuse settings from other files using `extends`. The value is an array of file paths, resolved relative to the config file that declares them.
+
+Extended files can have any name. They do not need to be named `.oxlintrc.json`, as long as they are valid JSON configuration files.
+
+Example:
 
 ```jsonc
 // oxlint-typescript.json
 {
   "plugins": ["typescript"],
   "rules": {
-    "typescript/no-explicit-any": "error"
-  }
+    "typescript/no-explicit-any": "error",
+  },
 }
+```
+
+```jsonc
 // .oxlintrc.json
 {
   "extends": ["oxlint-typescript.json"],
   "rules": {
-    "no-unused-vars": "warn"
-  }
+    "no-unused-vars": "warn",
+  },
 }
 ```
 
-Not all properties can be extended, but the following properties are supported:
+Only some properties can be extended. The supported properties are:
 
 - `rules`
 - `plugins`
diff --git a/src/docs/guide/usage/linter/plugins.md b/src/docs/guide/usage/linter/plugins.md
index 2e0e5efca48..70fa8fb842b 100644
--- a/src/docs/guide/usage/linter/plugins.md
+++ b/src/docs/guide/usage/linter/plugins.md
@@ -1,33 +1,47 @@
-# Plugins
+---
+title: Built-in Plugins
+description: Enable built in plugin rule sets and extend Oxlint with ESLint compatible JavaScript plugins.
+---
 
-Oxlint supports several of the most popular ESLint plugins out of the box with
-most rules in `recommended` configs already implemented.
+# Built-in Plugins
 
-Oxlint also supports [plugins written in JS](/docs/guide/usage/linter/js-plugins.html).
+Oxlint includes built in implementations of many popular ESLint plugin rule sets. Most rules in the `recommended` configs are already implemented, so you can get useful results without extra setup.
 
-## Enabling Plugins
+Oxlint also supports plugins written in JavaScript with an ESLint compatible API. See [JS Plugins](./js-plugins.md).
 
-You can enable plugins using the `--<plugin-name>-plugin` CLI flag. For example,
-to enable `eslint-plugin-import`, run
+## What a plugin means in Oxlint
 
-```sh
+A plugin is a named group of rules. Enabling a plugin makes its rules available, and category flags control which rules are enabled and at what severity.
+
+If you are migrating from ESLint, plugins map to the ecosystems you already know, such as import, react, jsx a11y, jest, unicorn, and more.
+
+## Enable a plugin
+
+### Enable with the CLI
+
+Enable a plugin using a `--<plugin-name>-plugin` flag.
+
+Example, enable the import plugin:
+
+```bash
 oxlint --import-plugin
 ```
 
-Once enabled, rules in categories you have enabled will automatically be turned
-on. For example,
+Once enabled, category flags determine what is turned on.
+
+Example, enable import plugin rules in the correctness category as errors and suspicious as warnings:
 
-```sh
+```bash
 oxlint --import-plugin -D correctness -W suspicious
 ```
 
-From the import plugin, this will enable all `correctness` rules as errors and `suspicious` rules as warnings, plus the rules from the base rule set. Note that `correctness` rules are turned on by default.
+Correctness rules are enabled by default.
 
-### Enabling plugins in a configuration file
+Tip: run `oxlint --help` to see the full list of plugin flags.
 
-You can also enable plugins in a configuration file by adding the `plugins`
-field. For example, to enable `eslint-plugin-import`, add the following to your
-`.oxlintrc.json` file:
+### Enable in a config file
+
+You can also enable plugins in `.oxlintrc.json` using the `plugins` field:
 
 ```json
 {
@@ -35,28 +49,23 @@ field. For example, to enable `eslint-plugin-import`, add the following to your
 }
 ```
 
-> [!NOTE]
-> Setting the `plugins` field will **overwrite** the base set of plugins. The plugins array should reflect all of the plugins you want to use.
+Setting `plugins` overwrites the default plugin set. The list should include every plugin you want enabled.
+
+## Disable default plugins
 
-## Disabling Plugins
+Several plugins are enabled by default. You can disable a default plugin with `--disable-<plugin-name>-plugin`.
 
-Several plugins are enabled by default, and are listed below. You can disable
-them with the `--disable-<plugin-name>-plugin` flag. For example, to disable
-`eslint-plugin-unicorn`, run:
+Example, disable unicorn:
 
-```sh
+```bash
 oxlint --disable-unicorn-plugin
 ```
 
-Only default plugins support being disabled, as other plugins can be omitted simply by not enabling them.
+Only default plugins support being disabled. Non default plugins can simply be omitted.
 
-:::info
-run `oxlint --help` to see a full list of flags to enable or disable plugins.
-:::
+### Disable default plugins in a config file
 
-### Disabling plugins in a configuration file
-
-You can also disable default plugins in a configuration file by simply adding an empty array to the `plugins` field.
+To disable all default plugins in a config file, set `plugins` to an empty array:
 
 ```json
 {
@@ -64,35 +73,34 @@ You can also disable default plugins in a configuration file by simply adding an
 }
 ```
 
-This configuration will disable all default plugins and only use the base set of rules.
-
-## Supported Plugins
-
-:::info
-You can also find this information on the [`linter product
-plan`](https://github.com/oxc-project/oxc/issues/481) issue on GitHub.
-:::
-
-| Plugin Name  | Default? | Issue                                                                                                            | Notes                                                                                                                                                                            |
-| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `eslint`     | ✅       | [#479](https://github.com/oxc-project/oxc/issues/479)                                                            | Rules from [`eslint`](https://eslint.org/docs/latest/rules/) (core)                                                                                                              |
-| `typescript` | ✅       | [#2180](https://github.com/oxc-project/oxc/issues/2180)                                                          | TypeScript-specific rules from [`@typescript-eslint`](https://typescript-eslint.io/rules/). Type-aware rules are supported in alpha (use `--type-aware` flag).                   |
-| `unicorn`    | ✅       | [#684](https://github.com/oxc-project/oxc/issues/684)                                                            | Rules from [`eslint-plugin-unicorn`](https://github.com/sindresorhus/eslint-plugin-unicorn)                                                                                      |
-| `react`      |          | [#1022](https://github.com/oxc-project/oxc/issues/1022), [#2174](https://github.com/oxc-project/oxc/issues/2174) | Rules from [`eslint-plugin-react`](https://www.npmjs.com/package/eslint-plugin-react) and [`eslint-plugin-react-hooks`](https://www.npmjs.com/package/eslint-plugin-react-hooks) |
-| `react-perf` |          | [#2041](https://github.com/oxc-project/oxc/issues/2041)                                                          | Rules from [`eslint-plugin-react-perf`](https://github.com/cvazac/eslint-plugin-react-perf)                                                                                      |
-| `nextjs`     |          | [#1929](https://github.com/oxc-project/oxc/issues/1929)                                                          | Rules from [`eslint-plugin-next`](https://nextjs.org/docs/pages/building-your-application/configuring/eslint#eslint-plugin)                                                      |
-| `oxc`        | ✅       | N/A                                                                                                              | Custom oxc-specific rules, as well as some rules ported from [deepscan](https://deepscan.io/)                                                                                    |
-| `import`     |          | [#1117](https://github.com/oxc-project/oxc/issues/1117)                                                          | Rules from [`eslint-plugin-import`](https://github.com/import-js/eslint-plugin-import)                                                                                           |
-| `jsdoc`      |          | [#1170](https://github.com/oxc-project/oxc/issues/1170)                                                          | Rules from [`eslint-plugin-jsdoc`](https://github.com/gajus/eslint-plugin-jsdoc)                                                                                                 |
-| `jsx-a11y`   |          | [#1141](https://github.com/oxc-project/oxc/issues/1141)                                                          | Rules from [`eslint-plugin-jsx-a11y`](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)                                                                                      |
-| `node`       |          | [#493](https://github.com/oxc-project/oxc/issues/493)                                                            | Rules from [`eslint-plugin-n`](https://github.com/eslint-community/eslint-plugin-n)                                                                                              |
-| `promise`    |          | [#4655](https://github.com/oxc-project/oxc/issues/4655)                                                          | Rules from [`eslint-plugin-promise`](https://github.com/eslint-community/eslint-plugin-promise)                                                                                  |
-| `jest`       |          | [#492](https://github.com/oxc-project/oxc/issues/492)                                                            | Rules from [`eslint-plugin-jest`](https://github.com/jest-community/eslint-plugin-jest)                                                                                          |
-| `vitest`     |          | [#4656](https://github.com/oxc-project/oxc/issues/4656)                                                          | Rules from [`eslint-plugin-vitest`](https://github.com/vitest-dev/eslint-plugin-vitest)                                                                                          |
-| `vue`        |          | [#11440](https://github.com/oxc-project/oxc/issues/11440)                                                        | Rules from [`eslint-plugin-vue`](https://github.com/vuejs/eslint-plugin-vue) that work with `<script>` tags                                                                      |
-
-## Adding New Plugins
-
-We do not plan to add more Rust-based plugins due to supporting nearly all ESLint plugins [through JS plugins](https://oxc.rs/docs/guide/usage/linter/js-plugins.html#using-js-plugins).
-However, contributions that add rules to existing plugins are **highly encouraged**.
-If you think a rule or plugin would benefit from being written in rust, please open a discussion first, before making a pull request.
+This disables all default plugins and uses only the base rule set.
+
+## Supported plugins
+
+This table lists the built in plugins and where they come from.
+
+| Plugin name  | Default | Source                                                                                                                   |
+| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `eslint`     | Yes     | ESLint core rules                                                                                                        |
+| `typescript` | Yes     | TypeScript rules from the typescript eslint ecosystem. Type aware rules are available in alpha using the type aware mode |
+| `unicorn`    | Yes     | eslint plugin unicorn                                                                                                    |
+| `react`      | No      | eslint plugin react and eslint plugin react hooks                                                                        |
+| `react-perf` | No      | eslint plugin react perf                                                                                                 |
+| `nextjs`     | No      | eslint plugin next                                                                                                       |
+| `oxc`        | Yes     | Oxc specific rules and selected rules ported from deepscan                                                               |
+| `import`     | No      | eslint plugin import                                                                                                     |
+| `jsdoc`      | No      | eslint plugin jsdoc                                                                                                      |
+| `jsx-a11y`   | No      | eslint plugin jsx a11y                                                                                                   |
+| `node`       | No      | eslint plugin n                                                                                                          |
+| `promise`    | No      | eslint plugin promise                                                                                                    |
+| `jest`       | No      | eslint plugin jest                                                                                                       |
+| `vitest`     | No      | eslint plugin vitest                                                                                                     |
+| `vue`        | No      | eslint plugin vue rules that work with script tags                                                                       |
+
+For the current status of rule coverage, see the linter [product plan issue](https://github.com/oxc-project/oxc/issues/481).
+
+## Adding new plugins
+
+Oxlint focuses on supporting the ecosystem through built in plugins and ESLint compatible JavaScript plugins. Contributions that add rules to existing built in plugins are encouraged.
+
+If you think a rule set should be implemented as a built in plugin, open a discussion first.
diff --git a/src/docs/guide/usage/linter/quickstart.md b/src/docs/guide/usage/linter/quickstart.md
new file mode 100644
index 00000000000..cfdbfbd5263
--- /dev/null
+++ b/src/docs/guide/usage/linter/quickstart.md
@@ -0,0 +1,186 @@
+---
+title: Quickstart
+description: Install Oxlint and learn the common workflows.
+---
+
+# Quickstart
+
+This page shows the recommended setup for Oxlint and the most common workflows, with copy-paste commands.
+
+## Install
+
+Install Oxlint as a dev dependency:
+
+```sh
+pnpm add -D oxlint
+```
+
+Add lint commands to `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix"
+  }
+}
+```
+
+Run it:
+
+```sh
+pnpm run lint
+```
+
+Apply fixes:
+
+```sh
+pnpm run lint:fix
+```
+
+## Usage
+
+For the complete list of options, see the [CLI reference](/docs/guide/usage/linter/cli.html).
+
+```sh
+oxlint [OPTIONS] [PATH]...
+```
+
+If `PATH` is omitted, Oxlint lints the current working directory.
+
+## Common workflows
+
+### Pre-commit with [lint-staged](https://github.com/lint-staged/lint-staged)
+
+```json
+{
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,mjs,cjs}": "pnpm run lint"
+  }
+}
+```
+
+### Create a config file
+
+Initialize the `.oxlintrc.json` config with default values:
+
+```sh
+oxlint --init
+```
+
+Use a config file explicitly:
+
+```sh
+oxlint -c ./oxlintrc.json
+# or
+oxlint --config ./oxlintrc.json
+```
+
+### Fix problems
+
+Apply safe fixes:
+
+```sh
+oxlint --fix
+```
+
+Apply suggestions (may change program behavior):
+
+```sh
+oxlint --fix-suggestions
+```
+
+Apply dangerous fixes and suggestions:
+
+```sh
+oxlint --fix-dangerously
+```
+
+See [Automatic fixes](/docs/guide/usage/linter/automatic-fixes) for guidance on when to use each mode.
+
+### Ignore files
+
+Use an ignore file:
+
+```sh
+oxlint --ignore-path .oxlintignore
+```
+
+Add ignore patterns from the command line:
+
+```sh
+oxlint --ignore-pattern "dist/**" --ignore-pattern "*.min.js"
+```
+
+Disable ignore handling:
+
+```sh
+oxlint --no-ignore
+```
+
+Follow symlinks (Oxlint ignores symlinks by default):
+
+```sh
+oxlint --symlinks
+```
+
+See [Ignore files](/docs/guide/usage/linter/ignore-files).
+
+### Fail CI reliably
+
+Only report errors:
+
+```sh
+oxlint --quiet
+```
+
+Fail if any warnings are found:
+
+```sh
+oxlint --deny-warnings
+```
+
+Fail if warnings exceed a threshold:
+
+```sh
+oxlint --max-warnings 0
+```
+
+See [CI setup](/docs/guide/usage/linter/ci).
+
+### Use machine-readable output
+
+Select an output format:
+
+```sh
+oxlint -f json
+```
+
+Available formats include: `default`, `json`, `unix`, `checkstyle`, `github`, `stylish`.
+
+### Inspect the effective configuration
+
+Print the configuration that would be used for a file:
+
+```sh
+oxlint --print-config path/to/file.ts
+```
+
+### List available rules
+
+List registered rules:
+
+```sh
+oxlint --rules
+```
+
+The full list is in the [Rules reference](/docs/guide/usage/linter/rules).
+
+## Next steps
+
+- Configure rules, plugins, and ignores: [Configuration](/docs/guide/usage/linter/config)
+- [Setup editors](/docs/guide/usage/linter/editors)
+- [Setup CI](/docs/guide/usage/linter/ci)
+- Learn advanced features: [Multi-file analysis](/docs/guide/usage/linter/multi-file-analysis), [Type-aware linting](/docs/guide/usage/linter/type-aware), [JS plugins](/docs/guide/usage/linter/js-plugins)
+<!-- - Migrate: [From ESLint](/docs/guide/usage/linter/migrate-from-eslint), [From Biome](/docs/guide/usage/linter/migrate-from-biome) -->
+- [CLI reference](/docs/guide/usage/linter/cli)
diff --git a/src/docs/guide/usage/linter/type-aware.md b/src/docs/guide/usage/linter/type-aware.md
index f65353b75bd..abba342bf7d 100644
--- a/src/docs/guide/usage/linter/type-aware.md
+++ b/src/docs/guide/usage/linter/type-aware.md
@@ -1,9 +1,28 @@
+---
+title: Type-Aware Linting
+description: Linting with type information.
+---
+
 # Type-Aware Linting
 
-Read our [technical preview announcement](/blog/2025-08-17-oxlint-type-aware) and [alpha announcement](/blog/2025-12-08-type-aware-alpha) for background details, and the rationale for the architecture we have chosen for type-aware linting.
+Type-aware linting enables rules that rely on TypeScript’s type system, such as detecting unhandled promises or unsafe assignments. In Oxlint, type-aware linting is provided by [`tsgolint`](https://github.com/oxc-project/tsgolint) and integrated into the Oxlint CLI and configuration system.
+
+This feature is currently **alpha**. Rule coverage, performance, and compatibility continue to improve.
+
+## Overview
+
+Oxlint separates responsibilities between two components:
+
+- **Oxlint (Rust)**
+  Handles file traversal, ignore logic, configuration, non-type-aware rules, and reporting.
+
+- **tsgolint (Go)**
+  Builds TypeScript programs using [`typescript-go`](https://github.com/microsoft/typescript-go) and executes type-aware rules, returning structured diagnostics to Oxlint.
 
 ## Installation
 
+Type-aware linting requires an additional dependency:
+
 ::: code-group
 
 ```sh [npm]
@@ -24,89 +43,118 @@ bun add -D oxlint-tsgolint@latest
 
 :::
 
-Run `oxlint` with `--type-aware`
+## Running type-aware linting
+
+Enable type-aware linting with the `--type-aware` flag:
 
 ```bash
 oxlint --type-aware
 ```
 
-## Unimplemented Rules
-
-See https://github.com/oxc-project/tsgolint/issues/104
-
-## Supported Rules
-
-List of supported rules:
-
-- [typescript/await-thenable](/docs/guide/usage/linter/rules/typescript/await-thenable)
-- [typescript/no-array-delete](/docs/guide/usage/linter/rules/typescript/no-array-delete)
-- [typescript/no-base-to-string](/docs/guide/usage/linter/rules/typescript/no-base-to-string)
-- [typescript/no-confusing-void-expression](/docs/guide/usage/linter/rules/typescript/no-confusing-void-expression)
-- [typescript/no-deprecated](/docs/guide/usage/linter/rules/typescript/no-deprecated)
-- [typescript/no-duplicate-type-constituents](/docs/guide/usage/linter/rules/typescript/no-duplicate-type-constituents)
-- [typescript/no-floating-promises](/docs/guide/usage/linter/rules/typescript/no-floating-promises)
-- [typescript/no-for-in-array](/docs/guide/usage/linter/rules/typescript/no-for-in-array)
-- [typescript/no-implied-eval](/docs/guide/usage/linter/rules/typescript/no-implied-eval)
-- [typescript/no-meaningless-void-operator](/docs/guide/usage/linter/rules/typescript/no-meaningless-void-operator)
-- [typescript/no-misused-promises](/docs/guide/usage/linter/rules/typescript/no-misused-promises)
-- [typescript/no-misused-spread](/docs/guide/usage/linter/rules/typescript/no-misused-spread)
-- [typescript/no-mixed-enums](/docs/guide/usage/linter/rules/typescript/no-mixed-enums)
-- [typescript/no-redundant-type-constituents](/docs/guide/usage/linter/rules/typescript/no-redundant-type-constituents)
-- [typescript/no-unnecessary-boolean-literal-compare](/docs/guide/usage/linter/rules/typescript/no-unnecessary-boolean-literal-compare)
-- [typescript/no-unnecessary-template-expression](/docs/guide/usage/linter/rules/typescript/no-unnecessary-template-expression)
-- [typescript/no-unnecessary-type-arguments](/docs/guide/usage/linter/rules/typescript/no-unnecessary-type-arguments)
-- [typescript/no-unnecessary-type-assertion](/docs/guide/usage/linter/rules/typescript/no-unnecessary-type-assertion)
-- [typescript/no-unsafe-argument](/docs/guide/usage/linter/rules/typescript/no-unsafe-argument)
-- [typescript/no-unsafe-assignment](/docs/guide/usage/linter/rules/typescript/no-unsafe-assignment)
-- [typescript/no-unsafe-call](/docs/guide/usage/linter/rules/typescript/no-unsafe-call)
-- [typescript/no-unsafe-enum-comparison](/docs/guide/usage/linter/rules/typescript/no-unsafe-enum-comparison)
-- [typescript/no-unsafe-member-access](/docs/guide/usage/linter/rules/typescript/no-unsafe-member-access)
-- [typescript/no-unsafe-return](/docs/guide/usage/linter/rules/typescript/no-unsafe-return)
-- [typescript/no-unsafe-type-assertion](/docs/guide/usage/linter/rules/typescript/no-unsafe-type-assertion)
-- [typescript/no-unsafe-unary-minus](/docs/guide/usage/linter/rules/typescript/no-unsafe-unary-minus)
-- [typescript/non-nullable-type-assertion-style](/docs/guide/usage/linter/rules/typescript/non-nullable-type-assertion-style)
-- [typescript/only-throw-error](/docs/guide/usage/linter/rules/typescript/only-throw-error)
-- [typescript/prefer-includes](/docs/guide/usage/linter/rules/typescript/prefer-includes)
-- [typescript/prefer-nullish-coalescing](/docs/guide/usage/linter/rules/typescript/prefer-nullish-coalescing)
-- [typescript/prefer-promise-reject-errors](/docs/guide/usage/linter/rules/typescript/prefer-promise-reject-errors)
-- [typescript/prefer-reduce-type-parameter](/docs/guide/usage/linter/rules/typescript/prefer-reduce-type-parameter)
-- [typescript/prefer-return-this-type](/docs/guide/usage/linter/rules/typescript/prefer-return-this-type)
-- [typescript/promise-function-async](/docs/guide/usage/linter/rules/typescript/promise-function-async)
-- [typescript/related-getter-setter-pairs](/docs/guide/usage/linter/rules/typescript/related-getter-setter-pairs)
-- [typescript/require-array-sort-compare](/docs/guide/usage/linter/rules/typescript/require-array-sort-compare)
-- [typescript/require-await](/docs/guide/usage/linter/rules/typescript/require-await)
-- [typescript/restrict-plus-operands](/docs/guide/usage/linter/rules/typescript/restrict-plus-operands)
-- [typescript/restrict-template-expressions](/docs/guide/usage/linter/rules/typescript/restrict-template-expressions)
-- [typescript/return-await](/docs/guide/usage/linter/rules/typescript/return-await)
-- [typescript/strict-boolean-expressions](/docs/guide/usage/linter/rules/typescript/strict-boolean-expressions)
-- [typescript/switch-exhaustiveness-check](/docs/guide/usage/linter/rules/typescript/switch-exhaustiveness-check)
-- [typescript/unbound-method](/docs/guide/usage/linter/rules/typescript/unbound-method)
-- [typescript/use-unknown-in-catch-callback-variable](/docs/guide/usage/linter/rules/typescript/use-unknown-in-catch-callback-variable)
-
-## Troubleshooting
-
-### Debugging Unexpected Errors
-
-If you encounter unexpected errors or rules not triggering when expected, types may not be resolving correctly. Run with `--type-check` to verify that all imports are being resolved:
+When enabled, Oxlint runs standard rules and type-aware rules in the `typescript/*` namespace.
+
+Type-aware linting is opt-in and does not run unless the flag is provided.
+
+### Monorepos and build outputs
+
+Type-aware linting requires resolved type information.
+
+In monorepos:
+
+- Build dependent packages so `.d.ts` files are available
+- Ensure dependencies are installed before running
+
+```bash
+pnpm install
+pnpm -r build
+oxlint --type-aware
+```
+
+### Type checking diagnostics
+
+Enable type checking to report TypeScript errors alongside lint results:
 
 ```bash
 oxlint --type-aware --type-check
 ```
 
-This will report TypeScript errors alongside lint diagnostics, helping identify missing or unresolved types.
+This mode can replace a separate `tsc --noEmit` step in CI:
 
-**Common causes of unresolved types:**
+```bash
+# before
+tsc --noEmit
+oxlint
 
-- **Monorepo with bundler (tsdown, tsup, etc.)**: Pre-build dependent packages so their types are available. For example, if package `A` depends on package `B`, build `B` first so its `.d.ts` files exist.
-- **Missing dependencies**: Ensure all dependencies are installed (`npm install` / `pnpm install`)
+# after
+oxlint --type-aware --type-check
+```
+
+## Configuring type-aware rules
+
+Type-aware rules are configured like other Oxlint rules.
 
-### Debugging Slow Performance
+```json
+{
+  "plugins": ["typescript"],
+  "rules": {
+    "typescript/no-floating-promises": "error",
+    "typescript/no-unsafe-assignment": "warn"
+  }
+}
+```
+
+Rules support the same options as their `typescript-eslint` equivalents.
 
-If type-aware linting is running slower than expected:
+```json
+{
+  "plugins": ["typescript"],
+  "rules": {
+    "typescript/no-floating-promises": ["error", { "ignoreVoid": true }]
+  }
+}
+```
 
-1. **Update to the latest versions** of both `oxlint` and `oxlint-tsgolint`
+## Disable comments
 
-2. **Enable debug logging** to see detailed timing information:
+Type-aware rules support inline disable comments:
+
+```ts
+// oxlint-disable-next-line typescript/no-floating-promises
+doSomethingAsync();
+```
+
+Report unused disable comments with:
+
+```bash
+oxlint --type-aware --report-unused-disable-directives
+```
+
+## TypeScript compatibility
+
+Type-aware linting is powered by `typescript-go`.
+
+- TypeScript **7.0+** is required
+- Some legacy `tsconfig` options are not supported
+- Invalid options are reported when `--type-check` is enabled
+
+## Stability notes
+
+Type-aware linting is **alpha**:
+
+- Rule coverage is incomplete
+- Very large codebases may encounter high memory usage
+- Performance continues to improve
+
+## Performance and debugging
+
+If type-aware linting is slow or uses excessive memory:
+
+1. Update both tools:
+
+- `oxlint`
+- `oxlint-tsgolint`
+
+2. Enable debug logging:
 
 ```bash
 OXC_LOG=debug oxlint --type-aware
@@ -139,33 +187,7 @@ Finished in 16.4s on 259 files with 161 rules using 12 threads.
   - Look for programs with an unusually high number of source files (e.g., `Program created with 26140 source files`). This may indicate misconfigured tsconfig `includes`/`excludes` pulling in unnecessary files like `node_modules`.
   - Each file path logged indicates when that file is being linted. Large time gaps between files may indicate expensive type resolution for certain files.
 
-## TypeScript Compatibility
-
-tsgolint is based on [typescript-go](https://github.com/microsoft/typescript-go) (Microsoft's TypeScript v7.0 rewrite in Go), not the original TypeScript compiler written in TypeScript.
-
-**Key implications:**
-
-- Only TypeScript 7.0+ features are supported
-- Pre-7.0 syntax and features (like `baseUrl` in `tsconfig.json`) are not supported
-- If you're using deprecated features that were deprecated in TypeScript 6.0 or removed in TypeScript 7.0, you'll need to migrate your codebase first
-
-For help migrating deprecated tsconfig options, see the [TypeScript migration guide](https://github.com/microsoft/TypeScript/issues/62508#issuecomment-3348649259).
-
-## Architecture
-
-Type-aware linting in Oxlint uses a unique two-binary architecture:
-
-```
-oxlint CLI (Rust)
-  ├─ Handles file traversal, ignore logic, and diagnostics
-  ├─ Runs non-type-aware rules and custom JS plugins
-  ├─ Passes paths and configuration to tsgolint
-  └─ Formats and displays results
-
-tsgolint (Go)
-  ├─ Uses typescript-go directly for type checking
-  ├─ Executes type-aware rules
-  └─ Returns structured diagnostics
-```
+## Next steps
 
-This design keeps Oxlint's core fast while leveraging TypeScript's type system through typescript-go. The frontend-backend separation means `oxlint` controls the user experience while `tsgolint` handles the heavy lifting of type analysis.
+- Check [implemented rules](https://github.com/oxc-project/tsgolint/tree/main?tab=readme-ov-file#implemented-rules)
+- Report issues to [https://github.com/oxc-project/tsgolint](https://github.com/oxc-project/tsgolint)
diff --git a/src/docs/guide/usage/linter/versioning.md b/src/docs/guide/usage/linter/versioning.md
index 2595f7526f9..fa63b6ded4c 100644
--- a/src/docs/guide/usage/linter/versioning.md
+++ b/src/docs/guide/usage/linter/versioning.md
@@ -2,7 +2,7 @@
 editLink: false
 ---
 
-# Versioning
+# Versioning policy
 
 Oxlint follows semantic versioning, with the goal of providing clarity and predictability as you upgrade.