soulbah · Oct 8, 2026 · Oct 8, 2026
diff --git a/README.md b/README.md
@@ -1,53 +1,37 @@
 # Rootform editors
 
-VS Code and Zed extensions for Rootform `.rf.hcl` source, powered by
-`rootform lsp` from a local Rootform CLI. The extensions do not include or
-download Rootform; language semantics come from Rootform's compiler, and the
-clients own syntax presentation, launch and lifecycle.
+VS Code and Zed extensions for `.rf.hcl` source: diagnostics, completion,
+hover, definitions and formatting through `rootform lsp`.
 
-- [VS Code](vscode/README.md), for the Visual Studio Marketplace and Open VSX
-- [Zed](zed/README.md), for the Zed extension registry
+Install a local [Rootform CLI](https://docs.rootform.dev/installation/), then
+choose your editor:
 
-## Development
+| Editor | Setup |
+| --- | --- |
+| VS Code (Visual Studio Marketplace, Open VSX) | [Extension guide](vscode/README.md) |
+| Zed (extension registry) | [Extension guide](zed/README.md) |
 
-```sh
-bun install --frozen-lockfile
-bun run verify
-```
-
-`verify` checks that both manifests share one version and description, checks
-formatting, builds and unit-tests the VS Code client, tests the Zed queries
-against the pinned HCL grammar and builds the Zed package for `wasm32-wasip2`
-with Rust 1.90, the toolchain the Zed registry packages with.
+Both clients launch an existing executable from settings or `PATH`. They ship
+no compiler, download no Rootform binary and execute no providers.
+See [editing Rootform source](https://docs.rootform.dev/language/editors/).
 
-Real integration qualification uses an explicitly provided Rootform executable
-and a local VS Code. Nothing is downloaded:
+## Develop
 
 ```sh
-VSCODE_EXECUTABLE_PATH="/Applications/Visual Studio Code.app/Contents/MacOS/Code" \
-ROOTFORM_BINARY="/absolute/path/to/rootform" \
-bun run --cwd vscode test:integration
+bun install --frozen-lockfile
+bun run verify
 ```
 
-The runner uses a temporary multi-root fixture workspace with unique VS Code
-user-data and extension directories. The fixture source is synthetic.
-
-To try the Zed package, run `zed: install dev extension` in Zed and select the
-`zed/` directory. Zed may need network access to prepare the pinned HCL
-grammar and `wasi-sdk` while building it; the language server always comes
-from the local Rootform executable.
-
-Native editor runtime qualification currently covers macOS arm64. The Zed
-package also builds for `wasm32-wasip2`; Linux and Windows editor runtimes
-have not yet been qualified.
-
-## Releasing
+The gate validates manifests, formatting, VS Code build and tests, Zed grammar
+queries and the `wasm32-wasip2` package with Rust 1.90. Real editor integration
+requires an explicitly provided local Rootform executable; see the
+[editor contract](docs/editor-contract.md).
+Native editor qualification covers macOS arm64. Linux and Windows runtime
+qualification remains separate from package checks.
 
-[Releasing](docs/releasing.md) covers versioning, the release workflow and
-publication to each store.
+[Releasing](docs/releasing.md) covers versioning and store publication.
 
 ## License
 
-Source is [Apache-2.0](LICENSE). Third-party dependencies retain their original
-licenses. Rootform name and logo: trademark rights reserved, see
-[TRADEMARKS.md](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md).
+[Apache-2.0](LICENSE). Third-party dependencies retain their licenses.
+[Rootform trademark terms](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md) apply.
diff --git a/vscode/README.md b/vscode/README.md
@@ -1,77 +1,46 @@
 # Rootform for VS Code
 
-Write Rootform `.rf.hcl` source with diagnostics, completion, hover, go to
-definition and formatting. The extension adds the Rootform language mode, with
-syntax highlighting, comments, bracket matching, automatic closing,
-indentation and folding, and connects VS Code to `rootform lsp` from your
-local Rootform CLI.
-
-Rootform owns parsing, compilation and formatting. The extension contains no
-compiler and does not include or download Rootform. Editing runs no Terraform,
-OpenTofu, provider or cloud call.
-
-## Requirements
-
-- Rootform on your machine. Follow
-  [Install Rootform](https://docs.rootform.dev/installation/), then check that
-  `rootform version` works.
-- VS Code 1.133 or later.
+Write `.rf.hcl` with diagnostics, completion, hover, definitions and formatting.
+The extension adds syntax highlighting and launches `rootform lsp` from your
+local CLI. It ships no compiler and downloads no Rootform binary. Editing
+executes no providers and makes no cloud calls.
 
 ## Get started
 
-1. Install Rootform, then this extension.
-2. Open a trusted workspace containing `.rf.hcl` files.
-3. Edit a Dialect or Policy Pack. Diagnostics follow your unsaved changes.
+1. [Install Rootform](https://docs.rootform.dev/installation/) and verify
+   `rootform version`.
+2. Install the extension in VS Code 1.133 or later.
+3. Open a trusted workspace containing `.rf.hcl` files.
 
-The extension starts `rootform` from VS Code's `PATH`. If Rootform is
-installed elsewhere, set **Rootform: Server Path** to the absolute path of the
-executable:
+The extension uses `rootform` from VS Code's `PATH`. For another location, set
+**Rootform: Server Path**:
 
 ```json
 {
   "rootform.server.path": "/absolute/path/to/rootform"
 }
 ```
 
-`.rf.json` source files also reach the language server; VS Code keeps its JSON
-presentation for them.
-
-## Settings and commands
-
-| Setting or command | Purpose |
-| --- | --- |
-| `rootform.server.path` | Absolute path, or command name resolved through `PATH`, of the local Rootform executable. Default: `rootform`. |
-| **Rootform: Restart Language Server** | Restarts `rootform lsp`, for example after replacing the executable outside VS Code. |
-
-## Workspace trust
-
-The extension starts the configured executable only in a trusted workspace.
-In Restricted Mode, syntax highlighting still works and no process starts. A
-workspace cannot change `rootform.server.path` until you trust it.
+The setting accepts an absolute path or a command name. Run **Rootform: Restart
+Language Server** after changing the executable. `.rf.json` files also reach the
+server, while VS Code keeps their JSON presentation.
 
-## Troubleshooting
+## Trust and troubleshooting
 
-- **Rootform executable was not found**: install Rootform or set
-  `rootform.server.path` to an absolute path. A desktop application may not
-  see the `PATH` of your terminal.
-- If the process does not complete LSP initialization within 10 seconds, the
-  extension stops it and points to the setting. A failed first start is not
-  retried: fix the setting, then run **Rootform: Restart Language Server**.
-- A server that stops after a successful start is restarted by the language
-  client, within a bounded number of attempts.
+In Restricted Mode, syntax highlighting works and no process starts. A workspace
+cannot change the executable path until you trust it.
 
-## Learn more
+If Rootform is missing, set an absolute path; VS Code may have a different
+`PATH` from your terminal. Initialization times out after 10 seconds. Fix the
+setting, then restart the language server. After a successful start, unexpected
+server exits have a bounded number of automatic retries.
 
-- [Rootform in VS Code](https://docs.rootform.dev/integrations/vscode/)
-- [Edit Rootform source](https://docs.rootform.dev/language/editors/)
-- [`rootform lsp` reference](https://docs.rootform.dev/reference/cli/lsp/)
-- [Report an issue](https://github.com/rootform-dev/editors/issues)
+[VS Code guide](https://docs.rootform.dev/integrations/vscode/) |
+[`rootform lsp`](https://docs.rootform.dev/reference/cli/lsp/) |
+[Report an issue](https://github.com/rootform-dev/editors/issues)
 
 ## License
 
-The extension source is licensed under
 [Apache-2.0](https://github.com/rootform-dev/editors/blob/dev/vscode/LICENSE).
-Bundled runtime packages keep their own licenses, listed in
-[THIRD_PARTY_NOTICES.md](https://github.com/rootform-dev/editors/blob/dev/vscode/THIRD_PARTY_NOTICES.md).
-Rootform name and logo: trademark rights reserved, see
-[TRADEMARKS.md](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md).
+[Third-party notices](https://github.com/rootform-dev/editors/blob/dev/vscode/THIRD_PARTY_NOTICES.md)
+and [Rootform trademark terms](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md) apply.
diff --git a/zed/README.md b/zed/README.md
@@ -1,23 +1,18 @@
 # Rootform for Zed
 
-Write Rootform `.rf.hcl` source with diagnostics, completion, hover, go to
-definition and formatting. The extension adds Rootform syntax highlighting,
-bracket matching, indentation and folding, and starts `rootform lsp` from your
-local Rootform CLI.
-
-Rootform owns parsing, compilation and formatting. The extension does not
-include or download Rootform.
+Write `.rf.hcl` with diagnostics, completion, hover, definitions and formatting.
+The extension adds syntax highlighting and launches `rootform lsp` from your
+local CLI. It ships no compiler and downloads no Rootform binary.
 
 ## Get started
 
-1. [Install Rootform](https://docs.rootform.dev/installation/) and check that
-   `rootform version` works.
-2. In Zed, open **Extensions**, search for **Rootform** and install it.
+1. [Install Rootform](https://docs.rootform.dev/installation/) and verify
+   `rootform version`.
+2. In Zed's **Extensions**, install **Rootform**.
 3. Open a `.rf.hcl` file.
 
-The extension finds `rootform` on the worktree `PATH` and starts it with the
-`lsp` argument. If Rootform is installed elsewhere, set both the path and the
-arguments in Zed's settings:
+The extension finds `rootform` on the worktree `PATH`. To choose another
+executable, set both its path and arguments:
 
 ```json
 {
@@ -32,26 +27,16 @@ arguments in Zed's settings:
 }
 ```
 
-With `binary.path` set, Zed launches that executable directly and passes
-`binary.env` to it. Keep `arguments` set to `["lsp"]`: without it, Rootform
-starts without a subcommand.
-
-## Troubleshooting
-
-A missing executable produces a message with the complete setting. After
-fixing a launch error or replacing Rootform, run
-`editor: restart language server`.
-
-## Learn more
+Zed launches that executable directly and passes `binary.env` to it.
+Keep `arguments` set to `["lsp"]`. After a launch error or executable replacement,
+run `editor: restart language server`.
 
-- [Rootform in Zed](https://docs.rootform.dev/integrations/zed/)
-- [Edit Rootform source](https://docs.rootform.dev/language/editors/)
-- [Report an issue](https://github.com/rootform-dev/editors/issues)
+[Zed guide](https://docs.rootform.dev/integrations/zed/) |
+[`rootform lsp`](https://docs.rootform.dev/reference/cli/lsp/) |
+[Report an issue](https://github.com/rootform-dev/editors/issues)
 
 ## License
 
-The extension source is licensed under [Apache-2.0](LICENSE). The pinned HCL
-Tree-sitter grammar and the Rust crates compiled into the extension keep their
-own licenses, listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
-Rootform name and logo: trademark rights reserved, see
-[TRADEMARKS.md](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md).
+[Apache-2.0](LICENSE). [Third-party notices](THIRD_PARTY_NOTICES.md) cover the
+pinned HCL grammar and Rust dependencies.
+[Rootform trademark terms](https://github.com/rootform-dev/rootform/blob/dev/TRADEMARKS.md) apply.