docs: final update after rewrite

Make clear this is not the default branch

3 files changed, 28 insertions, 53 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 983499e81..f665ce1ed 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -22,15 +22,15 @@ To add a new parser, edit the following files:
 zimbu = {
   install_info = {
     url = 'https://github.com/zimbulang/tree-sitter-zimbu', -- git repo; use `path` for local path
-    revision = 'v2.1', -- tag or commit hash, will be updated automatically
+    revision = 'v2.1', -- tag or commit hash
     -- optional entries:
     branch = 'develop', -- only needed if different from default branch
     location = 'parser', -- only needed if the parser is in subdirectory of a "monorepo"
     generate = true, -- only needed if repo does not contain pre-generated src/parser.c
-    generate_from_json = true, -- only needed if grammar.js has npm-installed dependencies
+    generate_from_json = false, -- only needed if repo does not contain `src/grammar.json` either
   },
   maintainers = { '@me' }, -- the _query_ maintainers
-  tier = 1, -- stable: track versioned releases
+  tier = 1, -- stable: track versioned releases instead of latest commit
   -- optional entries:
   requires = { 'vim' }, -- if the queries inherit from another language
   readme_note = "an example language",
diff --git a/README.md b/README.md
index 703a41781..ef3a9f32c 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,17 @@
 <h1 align="center">
   <img src="https://github.com/nvim-treesitter/nvim-treesitter/assets/2361214/0513b223-c902-4f12-92ee-8ac4d8d6f41f" alt="nvim-treesitter">
 </h1>
-<div align="center">
-  <p>
-    <a href="https://matrix.to/#/#nvim-treesitter:matrix.org">
-      <img alt="Matrix Chat" src="https://img.shields.io/matrix/nvim-treesitter:matrix.org" />
-    </a>
-    <a href="https://github.com/nvim-treesitter/nvim-treesitter/actions?query=workflow%3A%22Linting+and+style+checking%22+branch%3Amaster">
-      <img alt="Linting and Style" src="https://github.com/nvim-treesitter/nvim-treesitter/workflows/Linting%20and%20style%20checking/badge.svg" />
-    </a>
-    <a href="https://github.com/nvim-treesitter/nvim-treesitter/actions?query=workflow%3A%22Check+loading+of+syntax+files%22+branch%3Amaster">
-      <img alt="Syntax files" src="https://github.com/nvim-treesitter/nvim-treesitter/workflows/Check%20loading%20of%20syntax%20files/badge.svg" />
-    </a>
-  </p>
-</div>
-
-
->[!WARNING]
-> This branch is a [full, incompatible, rewrite of `nvim-treesitter`](https://github.com/nvim-treesitter/nvim-treesitter/issues/4767) and [work in progress](TODO.md). The **stable** branch is [`master`](https://github.com/nvim-treesitter/nvim-treesitter/tree/master).
 
 The `nvim-treesitter` plugin provides
 1. functions for installing, updating, and removing [**tree-sitter parsers**](SUPPORTED_LANGUAGES.md);
-2. a collection of **queries** for enabling tree-sitter features built into Neovim for these languages.
+2. a collection of **queries** for enabling tree-sitter features built into Neovim for these languages;
+3. a staging ground for [treesitter-based features](#Supported-features) considered for upstreaming to Neovim.
 
 For details on these and how to help improving them, see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
+>[!CAUTION]
+> This is a full, incompatible, rewrite. If you can't or don't want to update, check out the [`master` branch](https://github.com/nvim-treesitter/nvim-treesitter/blob/master/README.md) (which is locked but will remain available for backward compatibility).
+
 # Quickstart
 
 ## Requirements
@@ -35,6 +22,12 @@ For details on these and how to help improving them, see [CONTRIBUTING.md](./CON
 - a C compiler in your path (see <https://docs.rs/cc/latest/cc/#compile-time-requirements>)
 - `Node` (23.0.0 or later) for some parsers (see the [list of supported languages](SUPPORTED_LANGUAGES.md))
 
+>[!IMPORTANT]
+> The **support policy** for Neovim is
+> 1. the _latest_ [stable release](https://github.com/neovim/neovim/releases/tag/stable);
+> 2. the _latest_ [nightly prerelease](https://github.com/neovim/neovim/releases/tag/nightly).
+> Other versions may work but are neither tested nor considered for fixes. In general, compatibility with Nvim 0.X is removed after the release of Nvim 0.(X+1).1.
+
 ## Installation
 
 You can install `nvim-treesitter` with your favorite package manager (or using the native `package` feature of vim, see `:h packages`).
@@ -43,14 +36,20 @@ This plugin is only guaranteed to work with specific versions of language parser
 It is strongly recommended to automate this; e.g., using [lazy.nvim](https://github.com/folke/lazy.nvim)
 
 ```lua
-require('lazy').setup(
-  { 'nvim-treesitter/nvim-treesitter', build = ':TSUpdate', lazy = false }
-)
+require('lazy').setup({
+  'nvim-treesitter/nvim-treesitter',
+  lazy = false,
+  branch = 'main',
+  build = ':TSUpdate'
+})
 ```
 
 >[!IMPORTANT]
 > This plugin does not support lazy-loading.
 
+>[!IMPORTANT]
+> Make sure to specify the `main` branch since (for now) the default branch is [`master`](https://github.com/nvim-treesitter/nvim-treesitter/blob/master/README.md).
+
 ## Setup
 
 `nvim-treesitter` can be configured by calling `setup`. The following snippet lists the available options and their default values. **You do not need to call `setup` for `nvim-treesitter` to work using default values.**
@@ -69,6 +68,7 @@ require'nvim-treesitter'.install { 'rust', 'javascript', 'zig' }
 ```
 
 (This is a no-op if the parsers are already installed.) Note that this function runs asynchronously; for synchronous installation in a script context ("bootstrapping"), you need to `wait()` for it to finish:
+
 ```lua
 require('nvim-treesitter').install({ 'rust', 'javascript', 'zig' }):wait(300000) -- wait max. 5 minutes
 ```
@@ -143,13 +143,14 @@ callback = function()
       branch = 'develop', -- only needed if different from default branch
       location = 'parser', -- only needed if the parser is in subdirectory of a "monorepo"
       generate = true, -- only needed if repo does not contain pre-generated `src/parser.c`
-      generate_from_json = false, -- only needed if repo does not contain `src/grammar.json`
+      generate_from_json = false, -- only needed if repo does not contain `src/grammar.json` either
     },
   }
 end})
 ```
 
 Alternatively, if you have a local checkout, you can instead use
+
 ```lua
     install_info = {
       path = '~/parsers/tree-sitter-zimbu',
@@ -177,6 +178,7 @@ If Neovim does not detect your language's filetype by default, you can use [Neov
 ### Modifying parsers
 
 You can use the same approach for overriding parser information. E.g., if you always want to generate the `lua` parser from grammar, add
+
 ```lua
 vim.api.nvim_create_autocmd('User', { pattern = 'TSUpdate',
 callback = function()
@@ -189,6 +191,7 @@ end})
 Queries can be placed anywhere in your `runtimepath` under `queries/<language>`, with earlier directories taking precedence unless the queries are marked with `; extends`; see [`:h treesitter-query-modelines`](https://neovim.io/doc/user/treesitter.html#treesitter-query-modeline).
 
 E.g., to add queries for `zimbu`, put `highlights.scm` etc. under
+
 ```lua
 vim.fn.stdpath('data') .. 'site/queries/zimbu'
 ```
diff --git a/TODO.md b/TODO.md
deleted file mode 100644
index 937a8b63b..000000000
--- a/TODO.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Roadmap
-
-This document lists the planned and finished changes in this rewrite towards [Nvim-treesitter 1.0](https://github.com/nvim-treesitter/nvim-treesitter/issues/4767).
-
-## TODO
-
-- [ ] **tests:** remove custom crate, plenary dependency
-- [ ] **indents:** rewrite (Helix or Zed compatible)
-- [ ] **textobjects:** include simple(!) `node`, `scope` (using `locals`) objects
-
-## DONE
-
-- [X] remove module framework
-- [X] remove extra utilities
-- [X] refactor `indent.lua` into standalone
-- [X] refactor `locals.lua` into standalone
-- [X] refactor commands, predicates, filetypes registration to plugin/
-- [X] support installing tiers of parsers
-- [X] install parsers to standard directory by default
-- [X] remove bundled queries from runtimepath; copy on parser install
-- [X] general refactor and cleanup
-- [X] rewrite installation using async module (drop support for sync; use callback instead)
-- [X] switch to upstream injection format
-- [X] remove locals from highlighting (cf. https://github.com/nvim-treesitter/nvim-treesitter/issues/3944#issuecomment-1458782497)
-- [X] drop ensure_install (replace with install)
-- [X] **CI:** switch to ts_query_ls, add update readme as check (remove update job)
-- [X] **CI:** track versioned releases for tier 1
-- [X] **`install.lua`:** migrate to async v2