diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..9f5ad42
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-wasip2
+          components: clippy, rustfmt
+
+      - uses: Swatinem/rust-cache@v2
+
+      - run: cargo fmt -- --check
+      - run: cargo test --lib
+      - run: cargo clippy --target wasm32-wasip2 -- -D warnings
+      - run: cargo build --target wasm32-wasip2
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..d4db23c
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,347 @@
+# Changelog
+
+This document records shipped project history reconstructed from the local Git
+tags, plus an `[Unreleased]` section for work merged since the last tag. Dates
+are tag or commit dates. The v0.1.0 tag was restored retroactively on the last
+commit that still declared version 0.1.0.
+
+For future plans, see [docs/ROADMAP.md](docs/ROADMAP.md).
+
+## [Unreleased]
+
+### Added
+
+- Added Vim text objects for MLIR, TableGen, and PDLL: function and comment
+  objects in all three, and class objects where the grammar has a matching
+  construct. The mapping follows each grammar's node shapes.
+- Added `docs/VIM_MODE.md` documenting the per-language mapping and the
+  motion-depth limit that applies in MLIR.
+
+### Changed
+
+- Renamed the extension to `mlir-tablegen` and the crate to
+  `zed_mlir_tablegen`, taking over the existing registry entry rather than
+  publishing a second one under the old id.
+- Corrected the `repository` metadata to `felixtensor/mlir-tablegen`. It had
+  been pointed at the `zed-extensions` transfer target ahead of a transfer that
+  did not happen, leaving the published link unresolvable.
+- Updated the MLIR grammar to tree-sitter-mlir v0.2.0. The READMEs now link the
+  parser's own corpus documentation instead of restating its file and dialect
+  counts, which went stale on every parser update.
+- Reorganized the documentation: the language server and remote development
+  guides returned to `docs/`, and the code of conduct and maintainer guide were
+  removed.
+- Documented installing from Zed's extension gallery as the normal path. The
+  dev-extension steps remain, now scoped to running a local checkout.
+- Streamlined the issue forms and pull request template around the grammar,
+  language-server, and other split.
+- Aligned comment and formatting conventions across every query file, with
+  byte-identical captures over the parsers' example files.
+- Refreshed the Cargo lockfile.
+
+### Fixed
+
+- Fixed PDLL to scope a bare `.` as `@punctuation.delimiter`, matching TableGen,
+  and to color the `.` inside `op<ns.name>` as part of the operation name.
+
+## [v0.6.2] - 2026-07-19
+
+### Added
+
+- Added highlighting for MLIR builtin `token` types, pretty-dialect bare
+  identifiers, affine identifiers, LLVM function clauses, and dynamic
+  dimension markers.
+- Added English and Chinese README screenshots for out-of-tree dialect syntax
+  and injected C++ highlighting.
+
+### Changed
+
+- Updated the MLIR grammar to tree-sitter-mlir v0.1.10 and the PDLL grammar to
+  tree-sitter-pdll v0.1.1.
+- Reworked the roadmap around concrete query, grammar-pin, and current-Zed
+  compatibility follow-ups, while moving LLVM- or Zed-gated ideas out of the
+  executable plan.
+- Updated the documented MLIR example corpus baseline to 566 files.
+
+### Improved
+
+- Aligned MLIR completion-label colors with source highlighting for builtin
+  attribute introducers.
+- Refined PDLL highlighting for escapes, pattern metadata, user-defined type
+  constraints, parameters, operation attribute keys, and call targets.
+
+### Fixed
+
+- Fixed MLIR highlighting roles for builtin literal introducers,
+  `func.func` visibility, and affine dimensions and symbols.
+- Fixed PDLL identifiers that fell back to generic variable coloring after the
+  v0.1.1 grammar update.
+
+## [v0.6.1] - 2026-06-23
+
+### Added
+
+- Added rich completion labels for the MLIR and PDLL language servers,
+  classifying values, blocks, dialects, aliases, operations, builtin types,
+  attributes, constraints, and include paths by their LSP kind and detail.
+- Added unit tests for the completion-label classification helpers.
+- Documented MLIR syntax highlighting inside C++ raw string literals.
+
+### Changed
+
+- Migrated `extension.toml` language-server metadata to the `languages = [...]`
+  field; the deprecated singular `language` field is no longer used.
+- Bumped the MLIR grammar revision to align with tree-sitter-mlir v0.1.3 and
+  v0.1.6.
+- Added `publish = false` and the Apache-2.0 WITH LLVM-exception license to
+  `Cargo.toml` to match the repository `LICENSE` file.
+- Added `cargo test --lib` to the CI workflow.
+
+### Improved
+
+- Improved MLIR highlighting coverage for new parser nodes and anonymous tokens
+  introduced by the grammar updates.
+- Improved MLIR and TableGen highlight capture names to match Zed's documented
+  highlight set.
+- Improved PDLL constraint classification by base name instead of a hardcoded
+  prefix list.
+
+### Fixed
+
+- Fixed language-server binary resolution to probe `PATH` per worktree instead
+  of reusing a shared cache across worktrees.
+- Fixed coloring for prefix-stripped MLIR attribute and type aliases in
+  completions.
+
+## [v0.6.0] - 2026-06-02
+
+### Added
+
+- Added TableGen symbol outline navigation for stable named records and useful
+  top-level declarations.
+- Added SSH remote development documentation.
+
+### Changed
+
+- Updated the TableGen grammar revision for merged object-name support.
+- Updated the PDLL grammar revision to the parser-aligned tree-sitter-pdll
+  commit.
+- Tightened PDLL word-character handling to match the updated lexer while
+  keeping dotted operation names selectable.
+
+### Improved
+
+- Improved MLIR highlighting for source locations.
+- Improved TableGen outline labels for computed object names.
+- Improved PDLL highlighting for the new `op_name` and `negated_call_expr`
+  parser nodes.
+
+### Fixed
+
+- Fixed TableGen outline truncation for paste, bang-operator, suffix, and
+  code-fragment object-name expressions.
+- Fixed PDLL outline captures to include only named top-level declarations.
+- Removed stale PDLL inline type-constraint highlight assumptions after the
+  parser update.
+
+## [v0.5.3] - 2026-05-20
+
+### Added
+
+- Added bilingual README documentation and refreshed developer-install notes.
+- Added the project changelog and refreshed the v0.6 roadmap.
+
+### Changed
+
+- Updated the MLIR and TableGen grammar revisions used by the extension.
+- Simplified language-server settings parsing.
+
+### Improved
+
+- Improved MLIR highlighting for string escapes and dimension separators.
+- Improved TableGen highlighting for ODS fields, definition names, and LHS-only
+  declaration / binding captures.
+- Restricted TableGen `<>` indentation to constructs that commonly span
+  multiple lines.
+
+### Fixed
+
+- Fixed CI to build the published WebAssembly target.
+- Fixed TableGen C++ injection coverage for renamed and shared declaration
+  fields.
+- Fixed language-server startup behavior by inheriting the user's shell
+  environment and logging invalid settings.
+
+## [v0.5.2] - 2026-05-07
+
+### Added
+
+- Switched TableGen support to the maintained
+  [`felixtensor/tree-sitter-tablegen`](https://github.com/felixtensor/tree-sitter-tablegen)
+  grammar.
+- Added TableGen C++ injection for ODS code-carrying fields, with injection
+  restricted to known code fields instead of arbitrary descriptions or strings.
+- Added TableGen string escape highlighting.
+
+### Changed
+
+- Render TableGen `[{ ... }]` code literals as string-like source regions
+  instead of generic embedded content.
+- Highlight TableGen `$name` uniformly as `@variable.special`.
+
+### Fixed
+
+- Removed an invalid anonymous-node match from the TableGen queries.
+
+## [v0.5.1] - 2026-04-24
+
+### Added
+
+- Added structured LSP settings and extra include directory support for
+  TableGen and PDLL language servers.
+- Added auto-detection for `tablegen_compile_commands.yml` and
+  `pdll_compile_commands.yml` in common build directories.
+- Added GitHub Actions CI for build verification.
+- Added C++ injection inside PDLL native `[{ ... }]` code blocks.
+
+### Changed
+
+- Refactored language-server integration into dedicated server modules.
+- Unified server configuration handling across MLIR, PDLL, and TableGen.
+- Renamed the repository to `zed-mlir-suite` and updated extension metadata.
+- Reorganized README onboarding and configuration documentation.
+- Replaced manually played README videos with optimized auto-playing GIFs.
+
+### Improved
+
+- Refined MLIR highlighting for dictionary attribute keys, composite builtin
+  type nodes, affine keywords/operators, and indentation behavior.
+- Added comments documenting Zed's last-match-wins query behavior where it
+  affects MLIR highlighting rules.
+
+## [v0.5.0] - 2026-04-21
+
+### Added
+
+- Wired up all three upstream LLVM language servers:
+  `mlir-lsp-server`, `mlir-pdll-lsp-server`, and `tblgen-lsp-server`.
+- Added per-server binary path resolution and argument passthrough through
+  Zed LSP settings.
+- Added LSP setup documentation, screenshots, and the first roadmap document.
+
+### Changed
+
+- Rebranded the extension from `MLIR` to `MLIR Suite`.
+- Changed the extension id to `mlir-suite`.
+- Cleaned up `extension.toml` grammar and language-server metadata.
+- Hosted demo media through GitHub user attachments.
+
+### Fixed
+
+- Rewrote TableGen indentation using generic bracket-pair matching.
+
+## [v0.4.0] - 2026-04-20
+
+### Added
+
+- Added initial PDLL language support, including grammar registration,
+  highlights, indentation, bracket matching, and symbol outline.
+- Added README feedback and contribution guidance.
+
+### Improved
+
+- Ordered PDLL highlights for Zed's last-match-wins query semantics.
+- Improved PDLL builtin type constraint highlighting.
+- Improved TableGen highlighting for member access and `let` item fields.
+
+### Fixed
+
+- Reordered MLIR `dense_resource` bare id highlighting to preserve the intended
+  fallback behavior.
+
+## [v0.3.1] - 2026-04-16
+
+### Added
+
+- Added MLIR highlighting support for `public` visibility.
+- Added MLIR module `attributes` highlighting.
+
+### Changed
+
+- Updated README content to reflect current features and dev-install workflow.
+- Aligned MLIR module highlighting with the latest grammar/query behavior.
+
+## [v0.3.0] - 2026-04-13
+
+### Added
+
+- Added TableGen (`.td`) language support.
+- Added TableGen grammar registration, language configuration, highlighting,
+  indentation, and bracket matching.
+
+### Fixed
+
+- Fixed the TableGen `block_comment` configuration.
+
+## [v0.2.1] - 2026-04-02
+
+### Added
+
+- Added MLIR indentation support.
+- Added MLIR symbol outline support.
+
+### Improved
+
+- Expanded and refined MLIR syntax highlighting to better match the intended
+  TextMate-style scopes.
+- Improved `dense_resource` highlighting and bumped the MLIR grammar revision.
+
+### Fixed
+
+- Fixed an issue that prevented the MLIR language from loading.
+
+## [v0.2.0] - 2026-03-31
+
+### Changed
+
+- Bumped the extension and crate version to 0.2.0.
+- Synced the MLIR grammar revision with the latest `tree-sitter-mlir` changes
+  available at the time.
+- Updated MLIR language configuration for Zed compatibility, including
+  `line_comments`, word characters, autoclose behavior, and quote exclusions in
+  comments / strings.
+- Simplified MLIR syntax highlighting after the grammar update.
+
+### Fixed
+
+- Fixed installation failures and version metadata issues.
+
+## [v0.1.0] - 2026-03-12
+
+### Added
+
+- Added the initial Rust-based Zed extension structure.
+- Added MLIR language registration, grammar metadata, syntax highlighting, and
+  bracket matching.
+- Added the initial README, license, Cargo manifest, and extension metadata.
+
+### Changed
+
+- Switched the MLIR grammar source to
+  [`felixtensor/tree-sitter-mlir`](https://github.com/felixtensor/tree-sitter-mlir)
+  before the first tagged baseline.
+
+[Unreleased]: https://github.com/felixtensor/mlir-tablegen/compare/v0.6.2...HEAD
+[v0.6.2]: https://github.com/felixtensor/mlir-tablegen/compare/v0.6.1...v0.6.2
+[v0.6.1]: https://github.com/felixtensor/mlir-tablegen/compare/v0.6.0...v0.6.1
+[v0.6.0]: https://github.com/felixtensor/mlir-tablegen/compare/v0.5.3...v0.6.0
+[v0.5.3]: https://github.com/felixtensor/mlir-tablegen/compare/v0.5.2...v0.5.3
+[v0.5.2]: https://github.com/felixtensor/mlir-tablegen/compare/v0.5.1...v0.5.2
+[v0.5.1]: https://github.com/felixtensor/mlir-tablegen/compare/v0.5.0...v0.5.1
+[v0.5.0]: https://github.com/felixtensor/mlir-tablegen/compare/v0.4.0...v0.5.0
+[v0.4.0]: https://github.com/felixtensor/mlir-tablegen/compare/v0.3.1...v0.4.0
+[v0.3.1]: https://github.com/felixtensor/mlir-tablegen/compare/v0.3.0...v0.3.1
+[v0.3.0]: https://github.com/felixtensor/mlir-tablegen/compare/v0.2.1...v0.3.0
+[v0.2.1]: https://github.com/felixtensor/mlir-tablegen/compare/v0.2.0...v0.2.1
+[v0.2.0]: https://github.com/felixtensor/mlir-tablegen/compare/v0.1.0...v0.2.0
+[v0.1.0]: https://github.com/felixtensor/mlir-tablegen/releases/tag/v0.1.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..7726676
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,191 @@
+# Contributing to Zed MLIR
+
+Thank you for helping improve MLIR, TableGen, and PDLL support in Zed.
+Contributions may include Rust extension code, Tree-sitter queries, language
+configuration, tests, documentation, and updates to pinned parser revisions.
+
+## Before you start
+
+Use this repository as the first stop for bugs, feature requests, and setup
+questions. You do not need to determine whether a highlighting or editing
+problem comes from a parser, a query, Zed, or another dependency before
+reporting it. Provide the smallest useful reproducer and the maintainer will
+triage the responsible layer.
+
+Search the [existing issues](https://github.com/felixtensor/mlir-tablegen/issues)
+and the [roadmap](docs/ROADMAP.md) before opening a report. Use the Bug, Feature,
+or Question form so the report contains the information needed for triage.
+
+This repository is the right place to report problems with:
+
+- MLIR, TableGen, or PDLL parsing, highlighting, and editing behavior;
+- standalone and injected-language support;
+- symbol outlines and completion-label styling;
+- LLVM language-server discovery, startup, settings, and SSH remote behavior;
+- installing it from the extension gallery or as a Zed dev extension;
+- project documentation, tests, CI, and packaging.
+
+A confirmed general Zed problem may be redirected to
+[zed-industries/zed](https://github.com/zed-industries/zed/issues). LLVM server
+behavior reproducible outside Zed may be redirected to
+[llvm/llvm-project](https://github.com/llvm/llvm-project/issues). Uncertain cases
+should remain here until the responsible layer is understood.
+
+For substantial new capabilities, especially work that depends on a new Zed
+extension API or LLVM language-server behavior, open a feature request before
+investing in an implementation. Focused bug fixes and documentation corrections
+may go directly to a pull request.
+
+## Development setup
+
+Install Rust through [rustup](https://rustup.rs) and add the WebAssembly target
+used by Zed extensions:
+
+```bash
+rustup target add wasm32-wasip2
+```
+
+Run the same Rust checks as CI for source, query, configuration, dependency, and
+release changes:
+
+```bash
+cargo fmt -- --check
+cargo test --lib
+cargo clippy --target wasm32-wasip2 -- -D warnings
+cargo build --target wasm32-wasip2
+```
+
+Documentation-only changes may report these checks as not applicable.
+
+Install the checkout through **zed: install dev extension** before testing
+user-visible behavior. LLVM language-server binaries are only required when a
+change affects LSP integration.
+
+## Keep changes focused
+
+- Keep each pull request to one coherent change.
+- Do not combine unrelated formatting, dependency, grammar-pin, or version
+  changes with a focused fix.
+- Do not update unrelated grammar pins in the same pull request.
+- Do not commit files ignored by `.gitignore`, including `grammars/`, `target/`,
+  `.zed/`, `tmp/`, logs, generated grammar Wasm files, or `extension.wasm`.
+- Update `Cargo.lock` when dependency changes are necessary.
+- The maintainer updates `CHANGELOG.md` during release preparation. Do not edit a
+  published changelog section unless correcting its historical record.
+
+## Code and query standards
+
+### Rust
+
+- Keep code formatted with `rustfmt` and free of Clippy warnings.
+- Prefer focused, deterministic helpers that can be covered by unit tests.
+- Use the Zed extension API and `Worktree` facilities for platform, environment,
+  path, and process behavior instead of assuming access to the host environment.
+- Preserve documented settings precedence and compatibility unless a breaking
+  change is intentional and documented.
+- Avoid new dependencies when the extension API or standard library is
+  sufficient.
+
+### Tree-sitter queries and language configuration
+
+- Inspect the concrete syntax tree before changing a query. Parser structure and
+  visual classification are separate concerns.
+- Match only nodes and fields available in the exact grammar commit pinned by
+  `extension.toml`.
+- Preserve the query file's precedence conventions: broad fallbacks must not
+  override more specific captures.
+- Use Zed's documented capture names and verify captures or ranges, not only the
+  color produced by one theme.
+- Keep context-specific visual heuristics in this repository's queries rather
+  than adding parser nodes solely to encode a preferred color.
+- Treat auto-closing configuration and `brackets.scm` matching as separate
+  behaviors and test them separately.
+- Add positive and negative examples for injections so ordinary strings or code
+  fields are not over-injected.
+
+### Documentation
+
+- Update the English documentation and identify corresponding Chinese sections
+  that need synchronization. Update both when you can validate the translation;
+  otherwise the maintainer will coordinate the Chinese update.
+- Summarize user-visible impact in the pull request rather than editing the
+  changelog directly.
+
+## Validation by change type
+
+Select the checks that apply and describe any important environment that was
+unavailable. The pull request template intentionally asks for only the checks
+actually performed; use the guidance below for affected areas.
+
+### Parser, highlighting, and query changes
+
+- Include a minimal source example and, when available, the relevant syntax-tree
+  fragment or `ERROR` / `MISSING` node.
+- Test a realistic LLVM/MLIR source in addition to the minimal example.
+- Check every affected query against the exact pinned grammar revision.
+- For MLIR, test standalone `.mlir` and C++ `R"mlir(...)mlir"` when the change
+  can affect injected content.
+- For PDLL and TableGen C++ injections, test host-language captures, delimiters,
+  injected C++ content, and a negative example that must not be injected.
+- Test with a stock Zed theme when the report might be theme-specific.
+
+When updating a grammar pin:
+
+1. Reference the parser issue, pull request, release, or commit when one exists.
+2. Use a public commit that Zed can fetch.
+3. Describe relevant node or field changes.
+4. Review every query consumer for that language: `highlights.scm`,
+   `injections.scm`, `outline.scm`, `indents.scm`, and `brackets.scm` where
+   present.
+5. Load or compile affected queries against the exact new pin.
+6. Re-test the original issue reproducer.
+
+The repository does not yet have an automated CI gate that compiles every query
+against every pinned grammar. Until that roadmap item is implemented, describe
+the dev-extension and representative-file checks performed for grammar pins and
+query changes.
+
+### Editing and navigation changes
+
+- Exercise auto-close behavior by typing the opening token.
+- Exercise bracket matching independently, including nested pairs.
+- Check indentation on opening, nested, empty, and closing constructs.
+- Check outlines for named and anonymous declarations, top-level and nested
+  constructs, duplicate entries, and truncated labels.
+
+### LSP and completion changes
+
+- Identify the LLVM server and version or commit used for testing.
+- State whether the executable came from `binary.path`, `settings.path`, or
+  `$PATH`.
+- Include relevant `binary.arguments`, `compilation_database`, and `extra_dirs`
+  settings.
+- Distinguish extension startup/configuration behavior from server responses that
+  reproduce outside Zed.
+- For remote changes, state whether paths, binaries, settings, and logs came from
+  the local or SSH remote machine.
+- For completion-label changes, include the server's label, kind, and detail and
+  run the focused Rust unit tests.
+
+## Pull requests
+
+Keep each pull request focused on one coherent change. The description should:
+
+1. Explain the user-visible problem or maintenance goal.
+2. Describe the solution, ownership boundary, and important tradeoffs when
+   relevant.
+3. Link related issues with `Fixes #<number>` when applicable.
+4. Reference parser, Zed, or LLVM work when it is relevant and already exists.
+5. List only the validation performed and the relevant versions, grammar commits,
+   platforms, and local or SSH environments.
+6. Include a minimal source sample, screenshot, syntax-tree fragment, or log
+   excerpt when it makes the result easier to review.
+
+For documentation-only changes, `N/A — documentation-only` is sufficient in the
+Validation section. Do not fill unrelated validation categories merely to
+complete the template.
+
+## License
+
+By contributing, you agree that your contribution is licensed under the
+[Apache License 2.0 with LLVM Exceptions](LICENSE) used by this repository.
diff --git a/README.md b/README.md
index 3cb5134..321aad7 100644
--- a/README.md
+++ b/README.md
@@ -1,229 +1,142 @@
 # Zed MLIR
 
-[MLIR](https://mlir.llvm.org) (`.mlir`), [TableGen](https://llvm.org/docs/TableGen/)
-(`.td`), and [PDLL](https://mlir.llvm.org/docs/PDLL/) (`.pdll`) support for the
-[Zed](https://zed.dev) editor.
+[![EN](https://img.shields.io/badge/lang-EN-blue?style=flat-square)](README.md)
+[![中文](https://img.shields.io/badge/lang-中文-lightgrey?style=flat-square)](docs/README_ZH.md)
 
-## Development
+[![CI](https://img.shields.io/github/actions/workflow/status/felixtensor/mlir-tablegen/ci.yml?style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/felixtensor/mlir-tablegen/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/github/v/tag/felixtensor/mlir-tablegen?style=flat-square&logo=github&label=version)](https://github.com/felixtensor/mlir-tablegen/tags)
+[![License](https://img.shields.io/badge/license-Apache%202.0%20with%20LLVM%20Exceptions-blue?style=flat-square&logo=apache&logoColor=white)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/felixtensor/mlir-tablegen?style=flat-square&logo=github)](https://github.com/felixtensor/mlir-tablegen/stargazers)
 
-To develop this extension, see the [Developing Extensions](https://zed.dev/docs/extensions/developing-extensions) section of the Zed docs.
+[MLIR](https://mlir.llvm.org), [TableGen](https://llvm.org/docs/TableGen/), and [PDLL](https://mlir.llvm.org/docs/PDLL/) support for the [Zed](https://zed.dev) editor.
 
-## Highlighting
+## Features
 
-Custom and out-of-tree dialects need no configuration: any `dialect.op` form is
-recognized, so a project's own dialects behave like upstream ones. MLIR embedded
-in C++ raw strings is highlighted as MLIR wherever Zed's bundled C++ grammar
-injects `raw_string_content` by delimiter, as in `R"mlir(…)mlir"`.
+- **Tree-sitter grammars** for MLIR (`.mlir`), TableGen (`.td`), and PDLL (`.pdll`) — the pinned MLIR parser parses a [curated corpus of official MLIR test files](https://github.com/felixtensor/tree-sitter-mlir/blob/main/examples/README.md) without `ERROR` nodes; this extension's Zed queries provide highlighting on top of those syntax trees.
+- **MLIR inside C++ raw strings** — when Zed's bundled C++ grammar injects `raw_string_content` by delimiter, MLIR inside `R"mlir(…)mlir"` strings is highlighted using this extension's MLIR grammar.
+- **First-class custom dialect support** — user-defined or out-of-tree `dialect.op` forms are recognized and highlighted correctly, so your project's own dialects just work.
+- **Symbol outline** — navigate symbols in MLIR, TableGen, and PDLL from the outline panel.
+- **Language Server integration** for all three upstream LLVM servers:
+  - `mlir-lsp-server` for `.mlir`
+  - `mlir-pdll-lsp-server` for `.pdll`
+  - `tblgen-lsp-server` for `.td`
+- **Rich completion labels** — completion items from the MLIR and PDLL language servers are classified by their LSP kind and detail, so values, blocks, dialects, operations, types, attributes, constraints, and include paths are colored consistently.
+- **Editing ergonomics** — bracket matching, auto-close pairs, and indentation tuned for each language.
+- **Vim text objects** — function and comment objects in all three languages, class objects where the grammar has a matching construct, and the motions built on them.
 
-## Language Servers
+## Prerequisites
 
-The extension integrates the three language servers from the LLVM project:
-`mlir-lsp-server` for `.mlir`, `mlir-pdll-lsp-server` for `.pdll`, and
-`tblgen-lsp-server` for `.td`. They are optional — Tree-sitter highlighting,
-symbol outlines, bracket matching, indentation, and Vim text objects work
-without them.
+- [Zed](https://zed.dev/download) editor
+- (Optional) LLVM language servers for LSP features — see [Language Support](#language-support).
 
-Completion items from the MLIR and PDLL servers are classified by their LSP kind
-and detail, so values, blocks, dialects, operations, types, attributes,
-constraints, and include paths are colored consistently.
+## Installation
 
-### Server Capabilities
+Open the extension gallery with `Cmd+Shift+X` on macOS or `Ctrl+Shift+X` on Linux/Windows — or **Zed > Extensions** from the menu bar — then search for **MLIR** and click **Install**. Nothing else is required: no Rust toolchain, and no LLVM binaries.
 
-The available LSP features depend on the server and LLVM version. The following
-matrix reflects
-[`llvm/llvm-project@06bf4bfff830`](https://github.com/llvm/llvm-project/commit/06bf4bfff830).
-This extension does not pin or bundle LLVM, so capabilities may differ in other
-LLVM builds.
+### Install as a dev extension
 
-| LSP capability | MLIR | PDLL | TableGen |
-|---|:---:|:---:|:---:|
-| Completion | ✅ | ✅ | ➖ |
-| Diagnostics | ✅ | ✅ | ✅ |
-| Signature help | ➖ | ✅ | ➖ |
-| Definition | ✅ | ✅ | ✅ |
-| References | ✅ | ✅ | ✅ |
-| Document links | ➖ | ✅ | ✅ |
-| Hover | ✅ | ✅ | ✅ |
-| Document symbols | ⚠️ | ✅ | ➖ |
-| Inlay hints | ➖ | ✅ | ➖ |
-| Code actions | ✅ | ➖ | ➖ |
-| Semantic tokens | ➖ | ➖ | ➖ |
-| Formatting | ➖ | ➖ | ➖ |
+To run a local checkout instead — to try an unreleased change, or to work on the extension itself — clone the repository:
 
-*Key: ✅ Supported · ⚠️ Conditional · ➖ Not supported.*
+```bash
+git clone https://github.com/felixtensor/mlir-tablegen.git
+```
+
+Then open the command palette (`Cmd+Shift+P` on macOS, `Ctrl+Shift+P` on Linux/Windows) and run **`zed: install dev extension`**, selecting the cloned directory. Zed compiles the extension to WebAssembly on install, so this path needs a stable Rust toolchain from [rustup](https://rustup.rs). The first build fetches dependencies and may take a minute or two; **`zed: open log`** has the details if it fails.
 
-Diagnostics use the standard `textDocument/publishDiagnostics` notification,
-which is not advertised in the initialization capability object. MLIR document
-symbols require the client to advertise hierarchical document symbols.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, and the Zed docs on [Developing Extensions](https://zed.dev/docs/extensions/developing-extensions) for how extensions are structured.
 
-### Disable the Servers
+## Language Support
 
-If the LLVM language servers are not installed, disable LSP for these languages
-to prevent Zed from trying to initialize them:
+### Core editing
+
+No LLVM binaries are required. To keep Tree-sitter highlighting, symbol outlines, bracket matching, indentation, and Vim text objects without LSP features, disable language servers in your user settings or project `.zed/settings.json`:
 
 ```jsonc
 {
   "languages": {
-    "MLIR": {
-      "enable_language_server": false
-    },
-    "PDLL": {
-      "enable_language_server": false
-    },
-    "TableGen": {
-      "enable_language_server": false
-    }
+    "MLIR": { "enable_language_server": false },
+    "PDLL": { "enable_language_server": false },
+    "TableGen": { "enable_language_server": false }
   }
 }
 ```
 
-Add this to your user `settings.json` or a project's `.zed/settings.json`. See
-Zed's documentation for
-[enabling or disabling language servers](https://zed.dev/docs/configuring-languages#enabling-or-disabling-language-servers).
+See [Language Server Setup](docs/LANGUAGE_SERVER.md#disable-lsp) for details.
 
-### Build the Servers
+### LSP code intelligence
 
-The three servers live in the `llvm-project` monorepo under `mlir/tools/`.
-Follow the [official MLIR Getting Started guide](https://mlir.llvm.org/getting_started/)
-to build them. A typical Unix-like flow is:
+Install `mlir-lsp-server`, `mlir-pdll-lsp-server`, and `tblgen-lsp-server` to enable the LSP features supported by each language. Configure each server's binary path in Zed; alternatively, make the containing directory available on the worktree's `$PATH`. See [Language Server Setup](docs/LANGUAGE_SERVER.md#configure-lsp) for the capability matrix, build instructions, settings, and [SSH remote development](docs/REMOTE_DEVELOPMENT.md).
 
-```bash
-git clone https://github.com/llvm/llvm-project.git
-mkdir llvm-project/build && cd llvm-project/build
+### Vim mode
 
-cmake -G Ninja ../llvm \
-  -DLLVM_ENABLE_PROJECTS=mlir \
-  -DLLVM_TARGETS_TO_BUILD="Native" \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DLLVM_ENABLE_ASSERTIONS=ON
+In Vim mode, `af` / `if` and `ac` / `ic` select functions and classes, `gc` takes the surrounding run of comments, and `]m` moves between functions:
 
-cmake --build . --target mlir-lsp-server mlir-pdll-lsp-server tblgen-lsp-server
-```
+| Language | Function (`af` / `if`, `]m`) | Class (`ac` / `ic`) |
+| --- | --- | --- |
+| MLIR | `func.func`, `llvm.func` | `module`, `builtin.module` |
+| PDLL | top-level `Pattern`, `Constraint`, `Rewrite` | — |
+| TableGen | named `def`, `defm` | `class`, `multiclass` |
 
-After a successful build, the binaries are in `llvm-project/build/bin/`.
-Configure each server's binary path directly in Zed. Alternatively, make that
-directory available on the worktree's `$PATH`.
+See [Vim Mode](docs/VIM_MODE.md) for how each mapping follows the grammar's node shapes, and for the motion-depth limit in MLIR.
 
-If `mlir` is listed in `LLVM_ENABLE_PROJECTS` and you build the default `all`
-target, the three servers are produced with the rest of MLIR and do not need a
-separate build command.
+## Screenshots
 
-### Configure Zed
+### Out-of-Tree Dialect Highlighting
 
-Configure each server under `lsp.<server-id>` in Zed's `settings.json`. The
-executable is resolved in this order: `binary.path`, then `settings.path`, then
-the worktree's `$PATH`.
+![Out-of-Tree Dialect Highlighting](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/downstream-triton.png)
 
-| Field | Type | Applies to | Description |
-|---|---|---|---|
-| `path` | `string` | All | Path to the server binary |
-| `compilation_database` | `string` | TableGen, PDLL | Path to the compilation-database YAML |
-| `extra_dirs` | `string[]` | TableGen, PDLL | Extra include directories |
-| `log` | `string` | All | Log verbosity: `"error"`, `"info"`, or `"verbose"` |
-| `pretty` | `bool` | All | Pretty-print JSON output |
+### MLIR in C++ Raw Strings
 
-All fields are optional. When `compilation_database` is unset and
-`binary.arguments` does not already contain the corresponding database flag,
-the extension searches the worktree's `build/` and `out/` directories for the
-TableGen or PDLL compilation database.
+![MLIR in C++ Raw Strings](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/cpp-inject-mlir.png)
 
-Zed's native `binary.path`, `binary.arguments`, and `binary.env` fields are also
-supported. `binary.path` selects the executable, `binary.arguments` supplies
-launch arguments, and `binary.env` overrides matching environment variables.
+### Go to Definition
 
-```jsonc
-{
-  "lsp": {
-    "mlir-lsp-server": {
-      "settings": {
-        "path": "/path/to/mlir-lsp-server",
-        "log": "verbose"
-      }
-    },
-    "tblgen-lsp-server": {
-      "settings": {
-        "path": "/path/to/tblgen-lsp-server",
-        "compilation_database": "/path/to/build/tablegen_compile_commands.yml",
-        "extra_dirs": [
-          "/path/to/llvm-project/llvm/include",
-          "/path/to/llvm-project/mlir/include"
-        ]
-      }
-    },
-    "mlir-pdll-lsp-server": {
-      "settings": {
-        "path": "/path/to/mlir-pdll-lsp-server",
-        "compilation_database": "/path/to/build/pdll_compile_commands.yml",
-        "extra_dirs": [
-          "/path/to/llvm-project/mlir/include"
-        ]
-      }
-    }
-  }
-}
-```
+![Go to Definition](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/go-to-definition.gif)
 
-After changing a server's launch settings, open the command palette and run
-`zed: restart language server`.
+### Find References
 
-### SSH Remote Development
+![Find References](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/find-references.gif)
 
-When a project is opened over SSH, the source code, language servers, tasks, and
-terminals run on the remote server; the local machine only runs the Zed UI. See
-Zed's [remote development documentation](https://zed.dev/docs/remote-development#zed-settings)
-for the full model.
+### Hover / Signature
 
-Zed keeps the settings scopes separate, and editing one does not update another.
-`zed: open settings file` edits the local UI machine, `zed: open server settings`
-edits the remote server, and `zed: open project settings file` (or
-`.zed/settings.json`) applies to everyone opening that project. Configure the
-language-server binaries in the **remote server settings**, not the local
-settings file: if Zed runs on Windows but the project is opened on a Linux
-server, the `path` value must be a Linux path on the remote server.
+![Hover / Signature](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/hover.gif)
 
-```jsonc
-{
-  "lsp": {
-    "mlir-lsp-server": {
-      "settings": {
-        "path": "/home/you/llvm-project/build/bin/mlir-lsp-server"
-      }
-    },
-    "tblgen-lsp-server": {
-      "settings": {
-        "path": "/home/you/llvm-project/build/bin/tblgen-lsp-server"
-      }
-    },
-    "mlir-pdll-lsp-server": {
-      "settings": {
-        "path": "/home/you/llvm-project/build/bin/mlir-pdll-lsp-server"
-      }
-    }
-  }
-}
-```
+### Completion
 
-The same rule applies to the other path-like settings: `compilation_database`
-must point to a file visible to the machine running the language server,
-`extra_dirs` must point to include directories visible to that same machine, and
-the auto-detected `build/` and `out/` compilation databases are searched relative
-to the worktree. Never put host-specific absolute paths — `C:\...` from a Windows
-UI host, or `/Applications/...` and Homebrew paths from a macOS UI host — into a
-project `.zed/settings.json` used by a Linux SSH workspace; the remote server
-cannot execute them.
+![Completion](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/completion.gif)
 
-## Vim Text Objects
+### Diagnostics
 
-| Language | Function (`af` / `if`, `]m`) | Class (`ac` / `ic`) |
-| --- | --- | --- |
-| MLIR | `func.func`, `llvm.func` | `module`, `builtin.module` |
-| PDLL | top-level `Pattern`, `Constraint`, `Rewrite` | — |
-| TableGen | named `def`, `defm` | `class`, `multiclass` |
+![Diagnostics](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/diagnostics.gif)
+
+### Symbol Outline
+
+![Symbol Outline](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/outline.gif)
+
+## Acknowledgements
+
+This extension builds on:
+
+- [MLIR](https://mlir.llvm.org) — the multi-level intermediate representation framework from the LLVM project.
+- [tree-sitter-mlir](https://github.com/felixtensor/tree-sitter-mlir) — Tree-sitter grammar for MLIR.
+- [tree-sitter-tablegen](https://github.com/felixtensor/tree-sitter-tablegen) — Tree-sitter grammar for TableGen.
+- [tree-sitter-pdll](https://github.com/felixtensor/tree-sitter-pdll) — Tree-sitter grammar for PDLL.
+- The three LSP servers (`mlir-lsp-server`, `mlir-pdll-lsp-server`, `tblgen-lsp-server`) are part of the [LLVM project](https://github.com/llvm/llvm-project).
+
+The out-of-tree dialect screenshot uses a TritonGPU test file from [Triton](https://github.com/triton-lang/triton).
+
+For MLIR tooling in other editors, see:
+
+- [vscode-mlir](https://github.com/llvm/vscode-mlir) — official VS Code extension for MLIR, PDLL, and TableGen.
+- [mlir-mode](https://github.com/llvm/llvm-project/tree/main/mlir/utils/emacs) — Emacs major mode and LSP client, shipped in the LLVM monorepo.
+
+## Feedback & Contributions
+
+Development priorities are tracked in the [roadmap](docs/ROADMAP.md). See [CONTRIBUTING.md](CONTRIBUTING.md) for issue reporting, development, and validation guidance.
+
+- Use the [issue chooser](https://github.com/felixtensor/mlir-tablegen/issues/new/choose) to report a bug, request a feature, or ask a setup question.
+- Follow the [pull request guidance](CONTRIBUTING.md#pull-requests) when submitting a change.
 
-`gc` takes the surrounding run of comments in all three. Anonymous TableGen
-records and PDLL's inline `Constraint` / `Rewrite` helpers are skipped in favor
-of the declaration enclosing them.
+## License
 
-Zed bounds how deep the motions search but not the text objects. In MLIR that
-bound falls inside an explicit `module { ... }`, so `]]` stops on the module and
-`]m` has nothing to visit, while `af` and `ac` keep working at any depth.
+Apache License 2.0 with LLVM Exceptions.
diff --git a/docs/LANGUAGE_SERVER.md b/docs/LANGUAGE_SERVER.md
new file mode 100644
index 0000000..21df23a
--- /dev/null
+++ b/docs/LANGUAGE_SERVER.md
@@ -0,0 +1,174 @@
+# Language Server Setup
+
+This extension integrates the three language servers provided by LLVM:
+
+| Language | Server ID |
+|---|---|
+| MLIR | `mlir-lsp-server` |
+| PDLL | `mlir-pdll-lsp-server` |
+| TableGen | `tblgen-lsp-server` |
+
+The available LSP features depend on the server and LLVM version. The servers
+are optional; Tree-sitter highlighting, symbol outlines, bracket matching,
+indentation, and [Vim text objects](VIM_MODE.md) work without them.
+
+## Server Capabilities
+
+The following matrix reflects
+[`llvm/llvm-project@06bf4bfff830`](https://github.com/llvm/llvm-project/commit/06bf4bfff830).
+This extension does not pin or bundle LLVM, so capabilities may differ in other
+LLVM builds.
+
+| LSP capability | MLIR | PDLL | TableGen |
+|---|:---:|:---:|:---:|
+| Completion | ✅ | ✅ | ➖ |
+| Diagnostics | ✅ | ✅ | ✅ |
+| Signature help | ➖ | ✅ | ➖ |
+| Definition | ✅ | ✅ | ✅ |
+| References | ✅ | ✅ | ✅ |
+| Document links | ➖ | ✅ | ✅ |
+| Hover | ✅ | ✅ | ✅ |
+| Document symbols | ⚠️ | ✅ | ➖ |
+| Inlay hints | ➖ | ✅ | ➖ |
+| Code actions | ✅ | ➖ | ➖ |
+| Semantic tokens | ➖ | ➖ | ➖ |
+| Formatting | ➖ | ➖ | ➖ |
+
+*Key: ✅ Supported · ⚠️ Conditional · ➖ Not supported.*
+
+Diagnostics use the standard `textDocument/publishDiagnostics` notification,
+which is not advertised in the initialization capability object.
+MLIR document symbols require the client to advertise hierarchical document
+symbols.
+
+Completion items from the MLIR and PDLL servers are classified by their LSP kind
+and detail, so values, blocks, dialects, operations, types, attributes,
+constraints, and include paths are colored consistently.
+
+## Disable LSP
+
+If the LLVM language servers are not installed, disable LSP for these languages
+to prevent Zed from trying to initialize them:
+
+```jsonc
+{
+  "languages": {
+    "MLIR": {
+      "enable_language_server": false
+    },
+    "PDLL": {
+      "enable_language_server": false
+    },
+    "TableGen": {
+      "enable_language_server": false
+    }
+  }
+}
+```
+
+Add this to your user `settings.json` or a project's `.zed/settings.json`.
+See Zed's official documentation for
+[enabling or disabling language servers](https://zed.dev/docs/configuring-languages#enabling-or-disabling-language-servers).
+
+## Configure LSP
+
+### Build the Servers
+
+The three servers live in the `llvm-project` monorepo under `mlir/tools/`.
+Follow the [official MLIR Getting Started guide](https://mlir.llvm.org/getting_started/)
+to build them. A typical Unix-like flow is:
+
+```bash
+git clone https://github.com/llvm/llvm-project.git
+mkdir llvm-project/build && cd llvm-project/build
+
+cmake -G Ninja ../llvm \
+  -DLLVM_ENABLE_PROJECTS=mlir \
+  -DLLVM_TARGETS_TO_BUILD="Native" \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DLLVM_ENABLE_ASSERTIONS=ON
+
+cmake --build . --target mlir-lsp-server mlir-pdll-lsp-server tblgen-lsp-server
+```
+
+After a successful build, the binaries are in `llvm-project/build/bin/`.
+Configure each server's binary path directly in Zed. Alternatively, make that
+directory available on the worktree's `$PATH`.
+
+If `mlir` is listed in `LLVM_ENABLE_PROJECTS` and you build the default `all`
+target, the three servers are produced with the rest of MLIR and do not need a
+separate build command.
+
+### Configure Zed
+
+Configure each server under `lsp.<server-id>` in Zed's `settings.json`. The
+extension resolves the executable in this order:
+
+1. `binary.path`
+2. `settings.path`
+3. The worktree's `$PATH`
+
+#### Extension Settings
+
+| Field | Type | Applies to | Description |
+|---|---|---|---|
+| `path` | `string` | All | Path to the server binary |
+| `compilation_database` | `string` | TableGen, PDLL | Path to the compilation-database YAML |
+| `extra_dirs` | `string[]` | TableGen, PDLL | Extra include directories |
+| `log` | `string` | All | Log verbosity: `"error"`, `"info"`, or `"verbose"` |
+| `pretty` | `bool` | All | Pretty-print JSON output |
+
+All fields are optional. When `compilation_database` is unset and
+`binary.arguments` does not already contain the corresponding database flag,
+the extension searches the worktree's `build/` and `out/` directories for the
+TableGen or PDLL compilation database.
+
+Zed's native `binary.path`, `binary.arguments`, and `binary.env` fields are also
+supported. `binary.path` selects the executable, `binary.arguments` supplies
+launch arguments, and `binary.env` overrides matching environment variables.
+
+#### Example
+
+```jsonc
+{
+  "lsp": {
+    "mlir-lsp-server": {
+      "settings": {
+        "path": "/path/to/mlir-lsp-server",
+        "log": "verbose"
+      }
+    },
+    "tblgen-lsp-server": {
+      "settings": {
+        "path": "/path/to/tblgen-lsp-server",
+        "compilation_database": "/path/to/build/tablegen_compile_commands.yml",
+        "extra_dirs": [
+          "/path/to/llvm-project/llvm/include",
+          "/path/to/llvm-project/mlir/include"
+        ]
+      }
+    },
+    "mlir-pdll-lsp-server": {
+      "settings": {
+        "path": "/path/to/mlir-pdll-lsp-server",
+        "compilation_database": "/path/to/build/pdll_compile_commands.yml",
+        "extra_dirs": [
+          "/path/to/llvm-project/mlir/include"
+        ]
+      }
+    }
+  }
+}
+```
+
+After changing a server's launch settings, open the command palette and run
+`zed: restart language server`.
+
+### SSH Remote Development
+
+Language servers run on the remote server for projects opened over SSH. Set
+remote binary paths with `zed: open server settings`, not
+`zed: open settings file`, which edits settings on the local UI machine.
+
+See [SSH Remote Development](REMOTE_DEVELOPMENT.md) for settings scopes, path
+resolution, and a complete remote example.
diff --git a/docs/README_ZH.md b/docs/README_ZH.md
new file mode 100644
index 0000000..38efd2a
--- /dev/null
+++ b/docs/README_ZH.md
@@ -0,0 +1,142 @@
+# Zed MLIR
+
+[![EN](https://img.shields.io/badge/lang-EN-lightgrey?style=flat-square)](../README.md)
+[![中文](https://img.shields.io/badge/lang-中文-red?style=flat-square)](README_ZH.md)
+
+[![CI](https://img.shields.io/github/actions/workflow/status/felixtensor/mlir-tablegen/ci.yml?style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/felixtensor/mlir-tablegen/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/github/v/tag/felixtensor/mlir-tablegen?style=flat-square&logo=github&label=version)](https://github.com/felixtensor/mlir-tablegen/tags)
+[![License](https://img.shields.io/badge/license-Apache%202.0%20with%20LLVM%20Exceptions-blue?style=flat-square&logo=apache&logoColor=white)](../LICENSE)
+[![Stars](https://img.shields.io/github/stars/felixtensor/mlir-tablegen?style=flat-square&logo=github)](https://github.com/felixtensor/mlir-tablegen/stargazers)
+
+为 [Zed](https://zed.dev) 编辑器提供 [MLIR](https://mlir.llvm.org)、[TableGen](https://llvm.org/docs/TableGen/) 和 [PDLL](https://mlir.llvm.org/docs/PDLL/) 支持。
+
+## 功能特性
+
+- **MLIR、TableGen 和 PDLL 的 Tree-sitter grammar** — 固定使用的 MLIR parser 在解析[从官方 MLIR 测试套件中精选的用例集](https://github.com/felixtensor/tree-sitter-mlir/blob/main/examples/README.md)时不会产生 `ERROR` 节点；本扩展的 Zed queries 基于这些语法树提供高亮。
+- **C++ raw string 内嵌 MLIR 高亮** — 当 Zed 内置的 C++ grammar 按分隔符注入 `raw_string_content` 时，`R"mlir(…)mlir"` 字符串中的 MLIR 会使用本扩展的 MLIR grammar 高亮。
+- **一流的自定义 dialect 支持** — 用户自定义或外部 `dialect.op` 形式均可正确识别和高亮，你的项目自有 dialect 开箱即用。
+- **符号大纲** — 在大纲面板中导航 MLIR、TableGen 和 PDLL 符号。
+- **集成三种上游 LLVM Language Server**：
+  - `mlir-lsp-server` 用于 `.mlir`
+  - `mlir-pdll-lsp-server` 用于 `.pdll`
+  - `tblgen-lsp-server` 用于 `.td`
+- **更丰富的补全标签样式** — MLIR 与 PDLL language server 返回的补全项会按 LSP kind 和 detail 分类着色，数值、块、dialect、操作、类型、属性、约束以及 include 路径都能获得一致的高亮。
+- **编辑体验优化** — 括号匹配、自动补全配对符号，以及针对每种语言调优的缩进。
+- **Vim 文本对象** — 三种语言均提供函数和注释文本对象，语法中有对应结构的还提供类对象，以及基于它们的移动命令。
+
+## 前置条件
+
+- [Zed](https://zed.dev/download) 编辑器
+- （可选）LLVM Language Server 用于 LSP 功能 — 详见 [语言支持](#语言支持)。
+
+## 安装
+
+在 macOS 按 `Cmd+Shift+X`、Linux/Windows 按 `Ctrl+Shift+X` 打开扩展面板 —— 或从菜单栏选择 **Zed > Extensions** —— 搜索 **MLIR** 并点击 **Install**。除此之外无需任何准备：不需要 Rust 工具链，也不需要 LLVM 二进制文件。
+
+### 作为开发扩展安装
+
+若想改用本地检出运行 —— 例如试用尚未发布的改动，或参与本扩展的开发 —— 先克隆仓库：
+
+```bash
+git clone https://github.com/felixtensor/mlir-tablegen.git
+```
+
+然后打开命令面板（macOS 按 `Cmd+Shift+P`，Linux/Windows 按 `Ctrl+Shift+P`），执行 **`zed: install dev extension`** 并选择克隆的目录。Zed 会在安装时将扩展编译为 WebAssembly，因此这条路径需要通过 [rustup](https://rustup.rs) 安装的 stable Rust 工具链。首次构建需要拉取依赖，可能耗时一两分钟；若失败，执行 **`zed: open log`** 查看详细信息。
+
+开发环境配置见 [CONTRIBUTING.md](../CONTRIBUTING.md)（仅英文）；关于 Zed 扩展的结构，可参考 Zed 文档的 [Developing Extensions](https://zed.dev/docs/extensions/developing-extensions) 章节（仅英文）。
+
+## 语言支持
+
+### 基础编辑功能
+
+无需安装 LLVM 二进制文件。若只需 Tree-sitter 高亮、符号大纲、括号匹配、缩进和 Vim 文本对象，可在用户配置或项目 `.zed/settings.json` 中禁用 Language Server：
+
+```jsonc
+{
+  "languages": {
+    "MLIR": { "enable_language_server": false },
+    "PDLL": { "enable_language_server": false },
+    "TableGen": { "enable_language_server": false }
+  }
+}
+```
+
+详细说明见 [Language Server Setup](LANGUAGE_SERVER.md#disable-lsp)（仅英文）。
+
+### LSP 代码智能
+
+安装 `mlir-lsp-server`、`mlir-pdll-lsp-server` 和 `tblgen-lsp-server` 后，可使用各服务器为对应语言提供的 LSP 功能。建议在 Zed 中配置各服务器的二进制文件路径；也可以选择将其所在目录加入当前 worktree 的 `$PATH`。能力矩阵、构建方法和配置项见 [Language Server Setup](LANGUAGE_SERVER.md#configure-lsp)（仅英文），SSH 远程开发见 [SSH Remote Development](REMOTE_DEVELOPMENT.md)（仅英文）。
+
+### Vim 模式
+
+在 Vim 模式下，`af` / `if` 和 `ac` / `ic` 分别选择函数和类，`gc` 选取光标周围连续的注释，`]m` 在函数间跳转：
+
+| 语言 | 函数（`af` / `if`、`]m`） | 类（`ac` / `ic`） |
+| --- | --- | --- |
+| MLIR | `func.func`、`llvm.func` | `module`、`builtin.module` |
+| PDLL | 顶层 `Pattern`、`Constraint`、`Rewrite` | — |
+| TableGen | 具名 `def`、`defm` | `class`、`multiclass` |
+
+各语言的映射如何对应到 grammar 的节点结构，以及 MLIR 中移动命令的深度限制，见 [Vim Mode](VIM_MODE.md)（仅英文）。
+
+## 截图
+
+### 外部 dialect 高亮
+
+![Out-of-Tree Dialect Highlighting](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/downstream-triton.png)
+
+### C++ raw string 内嵌 MLIR
+
+![MLIR in C++ Raw Strings](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/cpp-inject-mlir.png)
+
+### 跳转到定义
+
+![Go to Definition](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/go-to-definition.gif)
+
+### 查找引用
+
+![Find References](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/find-references.gif)
+
+### 悬停 / 签名
+
+![Hover / Signature](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/hover.gif)
+
+### 补全
+
+![Completion](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/completion.gif)
+
+### 诊断
+
+![Diagnostics](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/diagnostics.gif)
+
+### 符号大纲
+
+![Symbol Outline](https://raw.githubusercontent.com/felixtensor/mlir-tablegen/assets/screenshots/outline.gif)
+
+## 致谢
+
+本扩展基于以下项目构建：
+
+- [MLIR](https://mlir.llvm.org) — LLVM 项目中的多层中间表示框架。
+- [tree-sitter-mlir](https://github.com/felixtensor/tree-sitter-mlir) — MLIR 的 Tree-sitter 语法。
+- [tree-sitter-tablegen](https://github.com/felixtensor/tree-sitter-tablegen) — TableGen 的 Tree-sitter 语法。
+- [tree-sitter-pdll](https://github.com/felixtensor/tree-sitter-pdll) — PDLL 的 Tree-sitter 语法。
+- 三个 LSP 服务器（`mlir-lsp-server`、`mlir-pdll-lsp-server`、`tblgen-lsp-server`）是 [LLVM 项目](https://github.com/llvm/llvm-project) 的一部分。
+
+外部 dialect 高亮截图使用了 [Triton](https://github.com/triton-lang/triton) 仓库中的 TritonGPU 测试文件。
+
+其他编辑器中的 MLIR 工具：
+
+- [vscode-mlir](https://github.com/llvm/vscode-mlir) — 官方的 MLIR、PDLL 和 TableGen VS Code 扩展。
+- [mlir-mode](https://github.com/llvm/llvm-project/tree/main/mlir/utils/emacs) — Emacs 主模式及 LSP 客户端，随 LLVM 单体仓库发布。
+
+## 反馈与贡献
+
+开发方向和优先级记录在 [路线图](ROADMAP.md) 中（仅英文）。[贡献指南](../CONTRIBUTING.md)（仅英文）说明了 Issue 报告、开发与验证要求。
+
+- 通过 [Issue 选择器](https://github.com/felixtensor/mlir-tablegen/issues/new/choose) 报告错误、提出功能请求或咨询配置问题。
+- 提交改动时，请遵循 [拉取请求指南](../CONTRIBUTING.md#pull-requests)。
+
+## 许可证
+
+Apache License 2.0 with LLVM Exceptions。
diff --git a/docs/REMOTE_DEVELOPMENT.md b/docs/REMOTE_DEVELOPMENT.md
new file mode 100644
index 0000000..1be5633
--- /dev/null
+++ b/docs/REMOTE_DEVELOPMENT.md
@@ -0,0 +1,94 @@
+# SSH Remote Development
+
+This extension follows Zed's remote development model: when a project is opened
+over SSH, the source code, language servers, tasks, and terminals run on the
+remote server. The local machine only runs the Zed UI.
+
+See Zed's official remote development documentation:
+<https://zed.dev/docs/remote-development#zed-settings>
+
+## Which Settings File To Edit
+
+Zed has separate settings scopes in remote workspaces:
+
+| Scope | How to open it | Use it for |
+|---|---|---|
+| Local user settings | `zed: open settings file` | Local UI preferences, local workspaces, SSH connection definitions |
+| Remote server settings | `zed: open server settings` | Remote language-server paths, remote environment-specific settings |
+| Project settings | `zed: open project settings file` or `.zed/settings.json` in the project | Settings that are valid for everyone opening that project |
+
+Local user settings and remote server settings are intentionally separate.
+Editing one does not update the other.
+
+For SSH remote development, configure this extension's language-server binaries
+in the remote server settings, not the local settings file. For example, if Zed
+is running on Windows but the project is opened on a Linux server, the `path`
+value must be a Linux path on the remote server.
+
+```jsonc
+{
+  "lsp": {
+    "mlir-lsp-server": {
+      "settings": {
+        "path": "/home/you/llvm-project/build/bin/mlir-lsp-server"
+      }
+    },
+    "tblgen-lsp-server": {
+      "settings": {
+        "path": "/home/you/llvm-project/build/bin/tblgen-lsp-server"
+      }
+    },
+    "mlir-pdll-lsp-server": {
+      "settings": {
+        "path": "/home/you/llvm-project/build/bin/mlir-pdll-lsp-server"
+      }
+    }
+  }
+}
+```
+
+`zed: open settings file` still opens the local machine's settings. That is
+expected: those settings are for local Zed. They are not the right place to put
+Linux-only language-server paths for a remote SSH workspace.
+
+## How the Extension Resolves Paths
+
+The extension asks Zed for settings and environment information for the current
+worktree. The server command is resolved in this order:
+
+1. `lsp.<server-id>.binary.path`
+2. `lsp.<server-id>.settings.path`
+3. The worktree's `PATH`
+
+In a local workspace, those values are resolved against the local machine. In an
+SSH remote workspace, they are resolved against the remote server.
+
+The same rule applies to other path-like settings:
+
+- `compilation_database` must point to a file visible to the machine running the
+  language server.
+- `extra_dirs` must point to include directories visible to that same machine.
+- Auto-detected `build/tablegen_compile_commands.yml`,
+  `out/tablegen_compile_commands.yml`, `build/pdll_compile_commands.yml`, and
+  `out/pdll_compile_commands.yml` are searched relative to the worktree.
+
+## Typical Remote Layout
+
+Local UI host + Linux SSH server is the standard setup. The split is:
+
+- Local user settings (`zed: open settings file`): local UI preferences, SSH
+  connection definitions, and host-specific LSP paths if you also open local
+  workspaces on this machine.
+- Remote server settings (`zed: open server settings`): Linux paths to
+  `mlir-lsp-server`, `tblgen-lsp-server`, and `mlir-pdll-lsp-server` on the
+  remote server.
+- Project settings (`zed: open project settings file`): settings valid for
+  every developer opening the project on the remote server, such as shared
+  relative build layouts or project-specific LSP options.
+
+Never put host-specific absolute paths into project `.zed/settings.json` for a
+Linux SSH workspace — the remote server cannot execute them. Examples of paths
+that do not belong there: `C:\...` on a Windows UI host; `/Applications/...`,
+Homebrew, or other macOS-specific paths on a macOS UI host.
+
+After changing any LSP setting, run `zed: restart language server`.
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
new file mode 100644
index 0000000..6cebd14
--- /dev/null
+++ b/docs/ROADMAP.md
@@ -0,0 +1,49 @@
+# Roadmap
+
+This document tracks the planned direction of **Zed MLIR**. Core language and LSP integration is in place, so remaining work favors focused parser and query maintenance over broad feature expansion. Items are grouped by priority, not by commitment — timing depends on upstream LLVM releases, Zed extension-API surface, concrete user feedback, and available time. Nothing here is a promise.
+
+For shipped milestones and tag-by-tag release history, see [CHANGELOG.md](../CHANGELOG.md).
+
+## Near-term
+
+### v0.6.x follow-ups
+
+- ~~**TableGen `[{ ... }]` auto-close.** Test a config-only entry first (`{ start = "[{", end = "}]", close = true, newline = true }`); this controls insertion, independently of bracket matching.~~ **Closed:** the experiment is complete, but the pair is deliberately not shipped without concrete editing demand.
+- ~~**TableGen `[{ ... }]` matching, if needed.** The pinned grammar merges each delimiter into an anonymous token that `brackets.scm` cannot address. Only pursue named open/close nodes through the parser branch/push/pin workflow if multi-character matching proves useful after the auto-close experiment.~~ **Closed with auto-close:** matching remains unshipped unless concrete demand justifies both the editor behavior and parser churn.
+- ~~**Current-Zed compatibility pass.** Re-test PDLL/TableGen document links with `lsp_document_links` enabled, verify PDLL inlay hints and completion-label rendering with stock themes, and separately reproduce the historical TableGen cross-file definition issue with valid compilation databases / `extra_dirs` and protocol logs.~~ **Completed on Zed 1.12.0:** all paths worked as expected; no extension-side follow-up was required.
+- **Query smoke tests against the pinned grammars.** CI checks the Rust extension but never compiles `languages/*/*.scm` against the exact grammar SHAs in `extension.toml`, so a grammar bump can leave a stale node name unnoticed. Before the next pin update, add a lightweight gate that uses temporary checkouts of the public pins, compiles every query, and parses representative fixtures without committing grammar checkouts or duplicating upstream corpora.
+- **MLIR alias outline support.** Add stable `name:` fields for `#` / `!` alias definitions on a non-`main` `tree-sitter-mlir` branch, test, commit, and push the change, then pin that public SHA before updating `outline.scm`. Keep external resources out of the outline because they have no stable symbol name.
+
+## Mid-term
+
+- ~~**Vim text objects (`textobjects.scm`).** Add `@function.around` / `@function.inside`, `@class.around` / `@class.inside`, and `@comment.around` captures with language-specific semantics.~~ **Shipped in #15:** `func.func` / `llvm.func` and modules in MLIR, named `def` / `defm` and `class` / `multiclass` in TableGen, and the three top-level declarations in PDLL, which has no class-like construct. Only modules take the class object in MLIR: its other regions are nested operation bodies rather than file sections, and treating them as classes would make `ac` select an arbitrary nesting level. See [Vim Mode](VIM_MODE.md).
+- **TableGen grammar — broaden corpus coverage.** The current real-world gate covers 141 MLIR and 7 LLVM TableGen files. Keep extending and validating [`felixtensor/tree-sitter-tablegen`](https://github.com/felixtensor/tree-sitter-tablegen) against four corpora and gate version bumps on zero `ERROR` nodes:
+  - **MLIR TableGen** — dialect / op / pass definitions under `mlir/include/mlir/` and `mlir/test/`
+  - **LLVM TableGen** — target backends under `llvm/lib/Target/*/` (heavy use of intrinsics, patterns, register classes)
+  - **Clang TableGen** — `clang/include/clang/Basic/{Attr,Diagnostic,StmtNodes,…}.td`
+  - **LLDB TableGen** — command option definitions under `lldb/source/Commands/Options.td` and related
+
+  Scope the zero-`ERROR` gate to curated, valid source corpora; deliberately invalid diagnostic tests should be tracked separately.
+
+## Ideas (unscored)
+
+- Lit-aware `// RUN:` highlighting and per-line runnables. Comments are single tokens in all three grammars, so faithfully highlighting lit substitutions (`%s`, `%t`, `%{...}`) would require a dedicated tree-sitter lit grammar injected into comment content — injecting generic `shellscript` misrepresents lit syntax — and executing a single `RUN:` line requires lit substitution plus test-suite configuration. A project-specific whole-file wrapper covers the practical workflow in the meantime; revisit only if a maintained lit grammar appears or user demand justifies owning one.
+- Quick-fix for "missing `include`" in TableGen (auto-insert the canonical header path), most likely as an upstream `tblgen-lsp-server` code action rather than a Zed-only feature.
+- Dialect-aware highlighting inside MLIR string attributes that embed recognized DSLs. Keep this opt-in / whitelist-driven so ordinary MLIR string attributes are not over-highlighted.
+- Semantic-token defaults, if one of the LLVM servers begins advertising useful semantic token types.
+- Custom symbol labels, if a future `label_for_symbol` API exposes richer data than the current symbol kind and name.
+- Block folding driven by tree-sitter regions. Zed currently derives folds from indentation and does not document a `folds.scm` capability for extensions; revisit if/when one is exposed.
+
+## Out of scope (today)
+
+- **`.mlirbc` bytecode editor.** `vscode-mlir` implements this with a custom editor, virtual file system, and custom requests that the current Zed extension API does not expose. Do not register `.mlirbc` as normal text.
+- **PDLL intermediate output.** `vscode-mlir` uses the custom `pdll/viewOutput` request, an output-kind picker, and temporary editor documents to show the AST, generated MLIR, or C++ output. Zed and `zed_extension_api` do not currently expose the custom-request and editor-command surfaces needed to reproduce this workflow; revisit only if both add the necessary support.
+- **Extension-side LSP response synthesis.** Diagnostics, navigation, inlay hints, and code actions come from the LLVM servers and are handled by Zed core. New standard responses belong upstream in LLVM; revisit suite work only when they require launch/configuration integration or reveal a concrete Zed compatibility issue.
+- **LSP initialization / workspace-configuration migration.** The current LLVM servers do not consume compilation-database or extra-include settings through these LSP channels, so CLI flags remain the supported path until upstream behavior changes.
+- **LSP settings-change behaviour.** Zed documents initialization options as startup-time configuration that requires a language-server restart to reapply. The extension API does not expose hooks to intercept settings changes or present custom restart prompts, so finer-grained control (prompt / auto-restart / ignore) is not implementable by extensions today.
+
+## How to propose changes
+
+Open an issue at [felixtensor/mlir-tablegen](https://github.com/felixtensor/mlir-tablegen/issues) with:
+- What problem you hit or what workflow you want,
+- Any pointers to upstream LLVM docs or related issues.
diff --git a/docs/VIM_MODE.md b/docs/VIM_MODE.md
new file mode 100644
index 0000000..26181e7
--- /dev/null
+++ b/docs/VIM_MODE.md
@@ -0,0 +1,41 @@
+# Vim Mode
+
+Zed's Vim mode provides function, class, and comment text objects, and the
+motions built on them. This extension supplies the captures behind them for
+MLIR, TableGen, and PDLL — no language server is involved, since they come from
+the Tree-sitter grammars. Coverage follows each grammar, so not every language
+has every object.
+
+## Mapping
+
+| Language | Function (`af` / `if`, `]m`) | Class (`ac` / `ic`) |
+| --- | --- | --- |
+| MLIR | `func.func`, `llvm.func` | `module`, `builtin.module` |
+| PDLL | top-level `Pattern`, `Constraint`, `Rewrite` | — |
+| TableGen | named `def`, `defm` | `class`, `multiclass` |
+
+`gc` takes the surrounding run of comments in all three languages.
+
+The mapping follows each grammar's node shapes rather than applying one rule
+everywhere:
+
+- **MLIR** gives the function object to `func.func` and `llvm.func`, and the
+  class object to modules. Other regions and blocks are nested operation bodies
+  rather than file sections, so treating them as classes would make `ac` select
+  an arbitrary nesting level.
+- **PDLL** gives the function object to its three top-level declarations, and
+  has no class-like construct. Inline `Constraint` and `Rewrite` helpers are
+  skipped in favor of the declaration enclosing them, because the grammar
+  aliases the inline forms to the same node types as the top-level ones.
+- **TableGen** keeps `class` / `multiclass` and named `def` / `defm` on
+  different nesting levels inside a multiclass. Anonymous records are skipped in
+  favor of the declaration enclosing them.
+
+## Motion Depth in MLIR
+
+Zed bounds how deep the motions search, but not the text objects. In MLIR that
+bound falls inside an explicit `module { ... }`, so `]]` stops on the module and
+`]m` has nothing to visit, while `af` and `ac` keep working at any depth.
+
+This affects only the motions. Selecting a function or class with a text object
+behaves the same regardless of nesting.
diff --git a/extension.toml b/extension.toml
index b2804ab..46487e4 100644
--- a/extension.toml
+++ b/extension.toml
@@ -7,7 +7,7 @@ authors = [
     "felixtensor <xubuyun@outlook.com>",
     "feichai0017 <songguocheng348@gmail.com>",
 ]
-repository = "https://github.com/zed-extensions/mlir-tablegen"
+repository = "https://github.com/felixtensor/mlir-tablegen"
 
 [grammars.mlir]
 repository = "https://github.com/felixtensor/tree-sitter-mlir"