From 66ad34192d248f5615de9fdf09294422484b5380 Mon Sep 17 00:00:00 2001
From: Krishna Ayyalasomayajula <krishna@ayyalasomayajula.net>
Date: Wed, 20 May 2026 12:53:17 -0500
Subject: [PATCH] checkpoint: preserve pre AstroNvim v6 migration state

---
 ...migration-orchestrator-execution-prompt.md | 542 +++++++++++++++
 ...12-treesitter-migration-atomic-git-plan.md | 617 ++++++++++++++++++
 lazy-lock.json                                |  12 +-
 lua/plugins/treesitter.lua                    |   7 +-
 4 files changed, 1169 insertions(+), 9 deletions(-)
 create mode 100644 .opencode/astronvim-v6-migration-orchestrator-execution-prompt.md
 create mode 100644 .opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md

diff --git a/.opencode/astronvim-v6-migration-orchestrator-execution-prompt.md b/.opencode/astronvim-v6-migration-orchestrator-execution-prompt.md
new file mode 100644
index 0000000..1a5131c
--- /dev/null
+++ b/.opencode/astronvim-v6-migration-orchestrator-execution-prompt.md
@@ -0,0 +1,542 @@
+# Orchestrator Execution Prompt: AstroNvim v6 migration
+
+## Purpose
+
+This prompt teaches the orchestrator how to interpret and execute the authoritative migration plan:
+
+```text
+.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md
+```
+
+The plan file is law. The orchestrator must treat it as the source of truth for scope, order, constraints, branch strategy, atomic commits, testing, and rollback behavior.
+
+This execution prompt does not replace the plan. It explains how to operationalize it safely with subagents and atomic git operations.
+
+## Prime directive
+
+Before doing any implementation, the orchestrator must read:
+
+```text
+.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md
+```
+
+Then execute that plan in order.
+
+If this prompt and the plan conflict, the plan wins.
+
+If runtime observations conflict with the plan, stop and ask the user before deviating, unless the change is clearly non-destructive diagnostic work.
+
+## Mission summary
+
+Migrate the user's modified AstroNvim v5-based Neovim dotfiles to an AstroNvim v6-compatible configuration to fix Neovim 0.12 Tree-sitter crashes, while preserving the user's commits and using atomic git operations on a dedicated migration branch.
+
+Known root issue:
+
+```text
+Neovim 0.12 + AstroNvim v5 + old nvim-treesitter master/snapshot = incompatible
+```
+
+Supported target:
+
+```text
+Neovim 0.12 + AstroNvim v6 + nvim-treesitter main-compatible snapshot
+```
+
+## Non-negotiable constraints
+
+1. Work on a dedicated branch:
+
+   ```text
+   migrate/astronvim-v6-nvim-0.12
+   ```
+
+2. Do not work directly on `main` except to inspect or when the user explicitly asks.
+
+3. The user will merge back to `main` manually when satisfied.
+
+4. Use atomic commits. Each commit should represent one logical step.
+
+5. Preserve current WIP before changing it.
+
+6. Do not edit Lazy plugin checkouts directly:
+
+   ```text
+   ~/.local/share/nvim/lazy/AstroNvim
+   ~/.local/share/nvim/lazy/nvim-treesitter
+   ```
+
+7. Do not merge `AstroNvim/AstroNvim` upstream history into the user's dotfiles repo.
+
+8. Consume AstroNvim updates through Lazy and `lazy-lock.json`.
+
+9. Do not use force operations unless the user explicitly approves.
+
+10. Do not hide lockfile weirdness. Inspect and report it.
+
+11. Do not commit a known-bad `nvim-treesitter` state where the lockfile says `branch = "main"` but still points to old commit `42fc28ba...`, except in the initial checkpoint commit whose purpose is to preserve pre-migration state.
+
+12. If branch already exists, stop and ask before reusing, resetting, or creating a suffixed branch.
+
+## Required orchestration paradigm
+
+Use this loop for implementation:
+
+```text
+worker -> reviewer -> commit-worker if pass
+```
+
+### Worker
+
+The worker performs one atomic implementation unit only.
+
+Examples:
+
+- create/check out migration branch
+- checkpoint current WIP
+- change AstroNvim version constraint
+- migrate Tree-sitter config to AstroCore style
+- run Lazy sync and capture results
+- refresh lockfile
+- perform one follow-up fix if tests reveal an issue
+
+The worker should return:
+
+- files changed
+- exact diff summary
+- commands run
+- outputs/errors
+- whether it believes the unit is complete
+- whether review is needed before commit
+
+### Reviewer
+
+The reviewer checks the worker's changes before committing.
+
+Reviewer must verify:
+
+- changes match the plan
+- only intended files changed
+- no Lazy plugin checkout files were modified
+- no unrelated source edits slipped in
+- lockfile changes are expected for the current phase
+- config syntax/startup checks pass where applicable
+- Tree-sitter migration uses AstroCore v6 style, not old `nvim-treesitter.configs` style
+- commit message matches the atomic unit
+
+Reviewer should return one of:
+
+```text
+PASS
+PASS_WITH_NOTES
+FAIL
+```
+
+If FAIL, explain exactly what must be fixed.
+
+### Commit-worker
+
+Only after reviewer PASS or user-approved PASS_WITH_NOTES, the commit-worker stages the precise files for that atomic unit and commits them.
+
+Commit-worker must:
+
+- run `git status --short --branch` before staging
+- stage only intended files
+- run `git diff --cached --stat`
+- run `git diff --cached` if needed for sanity
+- create the commit with the planned message
+- run `git status --short --branch` after commit
+
+Do not use `git add -A` except for the initial checkpoint commit, where preserving current WIP exactly is intentional.
+
+## Parallelization strategy
+
+Parallelize read-only audits and research. Do not parallelize state-changing steps that depend on git branch, file contents, Lazy lockfile state, or plugin runtime state.
+
+Good parallel tasks:
+
+- Search for v6-renamed plugin repository names.
+- Search for removed plugin references.
+- Inspect AstroLSP config for v6-breaking patterns.
+- Inspect Mason/tree-sitter-cli assumptions.
+- Inspect AstroCommunity imports.
+- Research/update docs if uncertainty appears.
+
+Do not parallelize:
+
+- branch creation/check out
+- commits
+- Lazy sync/update
+- lockfile refresh
+- edits to the same file
+- cleanup of runtime/plugin folders
+
+## Subagent templates
+
+### Worker subagent template
+
+Use this when asking a worker to perform a single atomic unit:
+
+```text
+You are a worker subagent. Execute exactly one atomic unit from the authoritative plan.
+
+Authoritative plan:
+.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md
+
+Current atomic unit:
+<describe unit>
+
+Constraints:
+- Follow the plan exactly.
+- Do not modify Lazy plugin checkouts under ~/.local/share/nvim/lazy/.
+- Do not touch unrelated files.
+- Do not commit unless explicitly instructed that you are the commit-worker.
+- Report commands run, files changed, diff summary, and any blockers.
+
+Expected output:
+- status: complete/blocked
+- files changed
+- commands run
+- concise diff summary
+- tests/checks run
+- recommended next step
+```
+
+### Reviewer subagent template
+
+Use this before every commit:
+
+```text
+You are a reviewer subagent. Review the current uncommitted changes against the authoritative plan.
+
+Authoritative plan:
+.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md
+
+Atomic unit under review:
+<describe unit>
+
+Check:
+- Does the diff match the plan?
+- Are only intended files changed?
+- Are there unrelated lockfile/source changes?
+- Are Lazy plugin checkouts untouched?
+- Are tests/checks sufficient for this unit?
+- Is the proposed commit message accurate?
+
+Return exactly one verdict: PASS, PASS_WITH_NOTES, or FAIL.
+Then provide concise rationale and required fixes if any.
+```
+
+### Commit-worker template
+
+Use only after review passes:
+
+```text
+You are the commit-worker. Commit exactly the reviewed atomic unit.
+
+Authoritative plan:
+.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md
+
+Reviewed atomic unit:
+<describe unit>
+
+Files to stage:
+<explicit file list>
+
+Commit message:
+<exact commit message>
+
+Rules:
+- Run git status before staging.
+- Stage only listed files, unless this is the initial checkpoint commit.
+- Show cached diff/stat before committing.
+- Commit with the exact message.
+- Show git status after committing.
+- Do not amend, reset, rebase, or force push.
+```
+
+## Ordered execution phases
+
+The orchestrator must follow the phases from the plan. Summary below; use the actual plan file for details.
+
+### Phase 1: Inspect and create migration branch
+
+Commands:
+
+```bash
+cd /home/kbot/.config/nvim
+git status --short --branch
+git log --oneline --decorate -8
+git switch -c migrate/astronvim-v6-nvim-0.12
+```
+
+If branch exists, ask user before proceeding.
+
+### Phase 2: Checkpoint current WIP
+
+If dirty:
+
+```bash
+git add -A
+git commit -m "checkpoint: preserve pre AstroNvim v6 migration state"
+```
+
+This is the only phase where `git add -A` is acceptable by default.
+
+### Phase 3: Migrate AstroNvim version constraint
+
+File:
+
+```text
+lua/lazy_setup.lua
+```
+
+Change:
+
+```lua
+version = "^5"
+```
+
+to:
+
+```lua
+version = "^6"
+```
+
+Keep `pin_plugins = nil`.
+
+Commit message:
+
+```text
+chore: migrate AstroNvim constraint to v6
+```
+
+### Phase 4: Migrate Tree-sitter config to AstroCore
+
+File:
+
+```text
+lua/plugins/treesitter.lua
+```
+
+Final shape should configure `AstroNvim/astrocore`, not direct old-style `nvim-treesitter` opts:
+
+```lua
+-- Customize Treesitter through AstroCore for AstroNvim v6
+
+---@type LazySpec
+return {
+  {
+    "AstroNvim/astrocore",
+    ---@type AstroCoreOpts
+    opts = {
+      treesitter = {
+        ensure_installed = {
+          "lua",
+          "vim",
+          "vimdoc",
+          "markdown",
+          "markdown_inline",
+        },
+        highlight = true,
+        indent = true,
+      },
+    },
+  },
+}
+```
+
+Commit message:
+
+```text
+refactor: migrate treesitter config to AstroCore
+```
+
+### Phase 5: Audit plugin rename/removal references
+
+Read-only searches first. Only edit if active source references are found.
+
+Renamed plugin names:
+
+```text
+Saghen/blink.cmp                  -> saghen/blink.cmp
+echasnovski/mini.icons            -> nvim-mini/mini.icons
+williamboman/mason.nvim           -> mason-org/mason.nvim
+williamboman/mason-lspconfig.nvim -> mason-org/mason-lspconfig.nvim
+```
+
+Removed plugin refs:
+
+```text
+JoosepAlviste/nvim-ts-context-commentstring
+folke/neoconf.nvim
+kevinhwang91/nvim-ufo
+RRethy/vim-illuminate
+```
+
+Planning audit found no active source edits needed. Confirm anyway.
+
+### Phase 6: Audit AstroLSP
+
+Planning audit found no changes likely needed. Confirm no active root-level `capabilities`, root-level `flags`, old default handlers, `require("lspconfig")`, or `require("astrolsp").lsp_opts`.
+
+Only edit if current code proves otherwise.
+
+### Phase 7: Review Mason tree-sitter-cli
+
+Planning audit found `tree-sitter-cli` in Mason config. Keep unless health checks prove it wrong.
+
+Do not remove proactively.
+
+### Phase 8: Lazy sync/update
+
+Run through Neovim/Lazy, not by editing plugin checkouts.
+
+Preferred interactive commands:
+
+```vim
+:Lazy sync
+:TSUpdate
+:checkhealth nvim-treesitter
+:checkhealth vim.lsp
+```
+
+Headless alternative if appropriate:
+
+```bash
+nvim --headless "+Lazy! sync" +qa
+nvim --headless "+TSUpdate" +qa
+```
+
+Do not run `:Lazy restore` unless rolling back.
+
+### Phase 9: Commit lockfile refresh
+
+Inspect first:
+
+```bash
+git diff -- lazy-lock.json
+rg '"nvim-treesitter"|"AstroNvim"|"astrocore"|"astrolsp"|"nvim-treesitter-textobjects"|"nvim-ts-autotag"' lazy-lock.json
+```
+
+Verify old `nvim-treesitter` commit `42fc28ba...` is gone after successful sync.
+
+Commit message:
+
+```text
+chore: refresh lazy lockfile for AstroNvim v6
+```
+
+### Phase 10: Verification
+
+Minimum checks:
+
+```bash
+nvim --headless +'lua print("startup ok")' +qa
+nvim --headless '+checkhealth nvim-treesitter' +qa
+```
+
+Manual markdown fenced-code test:
+
+````markdown
+# Tree-sitter crash test
+
+```lua
+print("hello")
+```
+
+```bash
+echo hello
+```
+````
+
+Open with:
+
+```bash
+nvim /tmp/treesitter-crash-test.md
+```
+
+Confirm no `range()` nil crash.
+
+Also check:
+
+```vim
+:checkhealth vim.lsp
+:Lazy show nvim-treesitter
+```
+
+## Optimal execution notes
+
+1. Start with local diagnostics; do not assume branch/dirty state from prior conversation.
+2. Create branch first, then checkpoint WIP.
+3. Make source migration commits before running Lazy sync.
+4. Keep lockfile refresh as its own commit.
+5. Use reviewers before each commit.
+6. Use parallel read-only audits after source commits but before Lazy sync if uncertainty remains.
+7. Treat unexpected Lazy/plugin changes as review events, not automatic success.
+8. Prefer fixing config source over manually mutating lockfile unless the plan explicitly says otherwise.
+9. If Neovim startup crashes after v6 constraint change, inspect error and fix config source; do not edit plugin checkout.
+10. Keep the repo on the migration branch when done so the user can inspect and merge manually.
+
+## Done criteria
+
+The orchestrator may report the migration ready for user review only when:
+
+- branch is `migrate/astronvim-v6-nvim-0.12`
+- working tree is clean
+- commits are atomic
+- `lua/lazy_setup.lua` tracks AstroNvim `^6`
+- Tree-sitter config uses AstroCore v6 style
+- `lazy-lock.json` has been refreshed by Lazy
+- `nvim-treesitter` is not locked to old `42fc28ba...`
+- startup check passes
+- Tree-sitter health is acceptable or documented
+- markdown fenced-code test no longer triggers the `range()` nil crash
+- user has a clear merge command
+
+## User handoff message template
+
+When done, report:
+
+```text
+Migration branch ready: migrate/astronvim-v6-nvim-0.12
+
+Summary:
+- <commit 1>
+- <commit 2>
+- <commit 3>
+
+Verification:
+- startup: pass/fail
+- nvim-treesitter health: pass/warnings
+- markdown fenced code crash reproduction: pass/fail
+- vim.lsp health: pass/warnings
+
+Remaining notes:
+- <anything the user should know>
+
+To merge when satisfied:
+  git switch main
+  git merge --ff-only migrate/astronvim-v6-nvim-0.12
+```
+
+## Rollback/remediation rules
+
+If something fails:
+
+1. Stop and report exact failing phase.
+2. Do not force reset unless user approves.
+3. Keep branch state inspectable.
+4. If on migration branch, returning to `main` is enough to leave source changes behind.
+5. Runtime/plugin state may still have changed due to Lazy sync; if the user needs to restore v5 runtime, ask before cleaning or restoring runtime directories.
+
+Supported compatibility fallback:
+
+```text
+AstroNvim v5 + Neovim 0.11.x
+```
+
+Supported target:
+
+```text
+AstroNvim v6 + Neovim 0.12.x
+```
diff --git a/.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md b/.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md
new file mode 100644
index 0000000..c24fb5f
--- /dev/null
+++ b/.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md
@@ -0,0 +1,617 @@
+# Task: AstroNvim v6 migration for Neovim 0.12 Tree-sitter compatibility with atomic git operations
+
+## Objective
+
+Migrate the user's modified AstroNvim v5-based Neovim dotfiles to an AstroNvim v6-compatible configuration while preserving the user's commits and avoiding destructive changes to `main` until the migration branch is reviewed and accepted.
+
+Primary bug to fix:
+
+```text
+Decoration provider "start" (ns=nvim.treesitter.highlighter):
+Lua: /usr/share/nvim/runtime/lua/vim/treesitter/languagetree.lua:215:
+/usr/share/nvim/runtime/lua/vim/treesitter.lua:196:
+attempt to call method 'range' (a nil value)
+```
+
+Root cause established by research/audit:
+
+- User is on Neovim 0.12.
+- AstroNvim v5 pins/uses old `nvim-treesitter` `master`/old snapshot behavior.
+- `nvim-treesitter` `master` is not compatible with Neovim 0.12.
+- AstroNvim v6 is the supported AstroNvim line for Neovim 0.12 Tree-sitter/LSP API changes.
+- The migration must not be just `version = "^6"`; Tree-sitter config must move to AstroCore v6 style, and lockfile/runtime state must be refreshed through Lazy.
+
+## Repository/context facts
+
+- Working repo: `/home/kbot/.config/nvim`
+- This is the user's personal dotfiles repo, not AstroNvim itself.
+- Current branch during audit: `main`
+- Remote during audit: `https://git.cyber.ayyalasomayajula.net/marsultor/neovim-dots.git`
+- AstroNvim itself is a Lazy-managed plugin checkout under:
+
+```text
+/home/kbot/.local/share/nvim/lazy/AstroNvim
+```
+
+- Do not edit or commit files inside Lazy plugin checkouts:
+
+```text
+~/.local/share/nvim/lazy/AstroNvim
+~/.local/share/nvim/lazy/nvim-treesitter
+```
+
+- Current active imports:
+
+```lua
+-- lua/lazy_setup.lua
+{ import = "community" },
+{ import = "plugins" },
+```
+
+- `lua/community.lua` is disabled with `if true then return {} end`, but this does not block active AstroCommunity usage because `lua/plugins/astrocommunity.lua` is imported through `plugins`.
+
+- Active AstroCommunity imports:
+
+```lua
+-- lua/plugins/astrocommunity.lua
+astrocommunity.colorscheme.oxocarbon-nvim
+astrocommunity.git.neogit
+astrocommunity.git.diffview-nvim
+astrocommunity.markdown-and-latex.vimtex
+```
+
+- These modules exist on current AstroCommunity. Watch item: the `vimtex` module may still touch `nvim-treesitter` to disable LaTeX highlighting; test after migration.
+
+## Key constraints and best practices
+
+1. Use atomic git operations.
+2. Use a dedicated migration branch, not `main`.
+3. The user will merge back to `main` manually when satisfied.
+4. Preserve current WIP before rewriting it.
+5. Do not merge AstroNvim upstream git history into the dotfiles repo.
+6. Consume AstroNvim updates through Lazy/AstroNvim plugin specs and `lazy-lock.json`.
+7. Do not hand-edit Lazy plugin checkouts.
+8. Avoid committing a confusing lockfile state where `nvim-treesitter` says `branch = "main"` but still points to old commit `42fc28ba...`.
+9. Prefer source migration commits before lockfile refresh commit.
+10. Run tests/health checks before recommending merge.
+
+## Branch strategy
+
+Use this branch:
+
+```bash
+migrate/astronvim-v6-nvim-0.12
+```
+
+All implementation work should happen on that branch.
+
+The user explicitly requested:
+
+> use a different branch. check that branch out. when we like it i'll merge and go back to main
+
+So the orchestrator/build agent should check out this branch and leave the repo on this branch for testing. Do not switch back to `main` unless asked.
+
+## Current WIP to preserve
+
+At audit time, uncommitted files included:
+
+```text
+lazy-lock.json
+lua/plugins/treesitter.lua
+```
+
+`lua/plugins/treesitter.lua` had been changed from disabled to active and made a direct `nvim-treesitter` spec with:
+
+```lua
+branch = "main",
+build = ":TSUpdate",
+ensure_installed = { "lua", "markdown", "markdown_inline", "vim" }
+```
+
+This is not the desired final v6 config, but it should be checkpointed before further changes.
+
+`lazy-lock.json` had unrelated plugin updates and a weird Tree-sitter state:
+
+- `nvim-treesitter` branch changed to `main`
+- old commit remained around `42fc28ba...`
+- unrelated plugin pins also changed, including some of:
+  - `astrocommunity`
+  - `milli.nvim`
+  - `neo-tree.nvim`
+  - `neogit`
+  - `vimtex`
+
+The first atomic operation should checkpoint or otherwise preserve this current state intentionally.
+
+## Phased implementation plan
+
+### Phase 1: Inspect and create migration branch
+
+Run diagnostic status first:
+
+```bash
+cd /home/kbot/.config/nvim
+git status --short --branch
+git log --oneline --decorate -8
+```
+
+Then create and check out the migration branch:
+
+```bash
+git switch -c migrate/astronvim-v6-nvim-0.12
+```
+
+If the branch already exists, do not overwrite it blindly. Inspect:
+
+```bash
+git branch --list migrate/astronvim-v6-nvim-0.12
+git status --short --branch
+```
+
+If it exists, ask the user whether to reuse, reset, or create a suffixed branch such as:
+
+```text
+migrate/astronvim-v6-nvim-0.12-2
+```
+
+Expected output: repo is now on the migration branch.
+
+### Phase 2: Atomic checkpoint commit of current WIP
+
+If working tree is dirty, preserve it exactly:
+
+```bash
+git add -A
+git commit -m "checkpoint: preserve pre AstroNvim v6 migration state"
+```
+
+If working tree is clean, skip this commit and note that no checkpoint commit was needed.
+
+Expected output: current WIP is preserved on the migration branch before any migration edits.
+
+### Phase 3: Migrate AstroNvim version constraint
+
+Affected file:
+
+```text
+lua/lazy_setup.lua
+```
+
+Current audited state:
+
+```lua
+{
+  "AstroNvim/AstroNvim",
+  version = "^5",
+  import = "astronvim.plugins",
+  opts = {
+    pin_plugins = nil,
+  },
+}
+```
+
+Required change:
+
+```lua
+version = "^6"
+```
+
+Keep:
+
+```lua
+pin_plugins = nil
+```
+
+Reasoning:
+
+- AstroNvim v6 is the official compatibility path for Neovim 0.12.
+- `pin_plugins = nil` lets AstroNvim decide based on versioned release behavior.
+- Do not remove version tracking unless the user wants nightly AstroNvim.
+
+Commit:
+
+```bash
+git add lua/lazy_setup.lua
+git commit -m "chore: migrate AstroNvim constraint to v6"
+```
+
+### Phase 4: Migrate Tree-sitter config to AstroCore v6 style
+
+Affected file:
+
+```text
+lua/plugins/treesitter.lua
+```
+
+Do not keep old v5/direct `nvim-treesitter` feature config such as:
+
+```lua
+return {
+  "nvim-treesitter/nvim-treesitter",
+  branch = "main",
+  build = ":TSUpdate",
+  opts = {
+    ensure_installed = { ... },
+  },
+}
+```
+
+AstroNvim v6 treats `nvim-treesitter` primarily as a parser download utility. Tree-sitter features should be configured via `AstroNvim/astrocore` under `opts.treesitter`.
+
+Target config:
+
+```lua
+-- Customize Treesitter through AstroCore for AstroNvim v6
+
+---@type LazySpec
+return {
+  {
+    "AstroNvim/astrocore",
+    ---@type AstroCoreOpts
+    opts = {
+      treesitter = {
+        ensure_installed = {
+          "lua",
+          "vim",
+          "vimdoc",
+          "markdown",
+          "markdown_inline",
+        },
+        highlight = true,
+        indent = true,
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- AstroNvim v6 defaults already include many parsers such as `bash`, `c`, `lua`, `markdown`, `markdown_inline`, `python`, `query`, `vim`, `vimdoc`.
+- The explicit list above is acceptable and focused on the user's known needs.
+- Do not configure `highlight = { enable = true }`; v6 AstroCore uses `highlight = true`.
+- Do not use old `nvim-treesitter.configs` options.
+
+Commit:
+
+```bash
+git add lua/plugins/treesitter.lua
+git commit -m "refactor: migrate treesitter config to AstroCore"
+```
+
+### Phase 5: Audit plugin rename/removal references
+
+Search active config for renamed plugin repository names:
+
+```bash
+rg 'Saghen/blink\.cmp|echasnovski/mini\.icons|echanovski/mini\.icons|williamboman/mason\.nvim|williamboman/mason-lspconfig\.nvim' lua
+```
+
+If found, replace:
+
+```text
+Saghen/blink.cmp                  -> saghen/blink.cmp
+echasnovski/mini.icons            -> nvim-mini/mini.icons
+williamboman/mason.nvim           -> mason-org/mason.nvim
+williamboman/mason-lspconfig.nvim -> mason-org/mason-lspconfig.nvim
+```
+
+Search active config for removed plugin references:
+
+```bash
+rg 'JoosepAlviste/nvim-ts-context-commentstring|folke/neoconf\.nvim|kevinhwang91/nvim-ufo|RRethy/vim-illuminate' lua
+```
+
+If active source references are found, remove/migrate them.
+
+Audit result from planning phase:
+
+- No active source references were found for renamed plugin repo names.
+- No active source references were found for removed plugins.
+- `lazy-lock.json` may still contain stale entries for old defaults like `neoconf.nvim` and `vim-illuminate`; this should be handled by Lazy sync/lock refresh, not manual source edits.
+
+Commit only if source edits were needed:
+
+```bash
+git add lua/
+git commit -m "chore: update plugin references for AstroNvim v6"
+```
+
+If no source edits were needed, skip this commit.
+
+### Phase 6: Audit AstroLSP config
+
+Affected file if needed:
+
+```text
+lua/plugins/astrolsp.lua
+```
+
+Planning audit found no active v6-breaking patterns:
+
+- no root-level `capabilities`
+- no root-level `flags`
+- no active `require("lspconfig")`
+- no active `require("astrolsp").lsp_opts`
+- `handlers` table exists but is empty
+
+Still, confirm with searches:
+
+```bash
+rg 'capabilities\s*=|flags\s*=|require\(["'"']lspconfig["'"']\)|lsp_opts|handlers\s*=\s*\{' lua/plugins/astrolsp.lua
+```
+
+If root-level `capabilities` or `flags` are found, migrate to:
+
+```lua
+config = {
+  ["*"] = {
+    capabilities = ...,
+    flags = ...,
+  },
+}
+```
+
+If old anonymous default handler is found:
+
+```lua
+handlers = {
+  function(server, opts)
+    require("lspconfig")[server].setup(opts)
+  end,
+}
+```
+
+migrate to v6-style:
+
+```lua
+handlers = {
+  ["*"] = function(server)
+    vim.lsp.enable(server)
+  end,
+}
+```
+
+Commit only if source edits are actually needed:
+
+```bash
+git add lua/plugins/astrolsp.lua
+git commit -m "refactor: migrate AstroLSP config for v6 APIs"
+```
+
+### Phase 7: Review Mason config and `tree-sitter-cli`
+
+Affected file:
+
+```text
+lua/plugins/mason.lua
+```
+
+Planning audit found:
+
+```lua
+"tree-sitter-cli"
+```
+
+Research notes:
+
+- New `nvim-treesitter` main expects modern Tree-sitter tooling.
+- Keeping `tree-sitter-cli` installed through Mason is probably fine.
+- Do not remove it unless v6 health checks indicate it is wrong/outdated.
+
+Action:
+
+- Inspect only.
+- No commit expected.
+
+### Phase 8: Run Lazy sync/update on the migration branch
+
+Important: do not manually edit plugin checkouts.
+
+Run from the migration branch. Prefer interactive Neovim first if possible:
+
+```bash
+nvim
+```
+
+Then inside Neovim:
+
+```vim
+:Lazy sync
+:TSUpdate
+:checkhealth nvim-treesitter
+:checkhealth vim.lsp
+```
+
+Alternative headless commands if appropriate:
+
+```bash
+nvim --headless "+Lazy! sync" +qa
+nvim --headless "+TSUpdate" +qa
+```
+
+Caveat:
+
+- If headless Lazy sync exits nonzero due to plugin changes needing restart, report output and continue with manual/interactive flow.
+- Do not run `:Lazy restore` while the lockfile still has old v5 pins unless intentionally rolling back.
+
+Expected result:
+
+- AstroNvim moves to v6-compatible commit.
+- `nvim-treesitter` moves away from old commit `42fc28ba...`.
+- `nvim-treesitter` should be on the v6-compatible `main` branch/snapshot.
+- Lazy regenerates `lazy-lock.json`.
+
+### Phase 9: Commit regenerated lockfile atomically
+
+Inspect lockfile diff:
+
+```bash
+git diff -- lazy-lock.json
+git status --short
+```
+
+Verify `nvim-treesitter` is no longer old `42fc28ba...`.
+
+Useful checks:
+
+```bash
+rg '"nvim-treesitter"|"AstroNvim"|"astrocore"|"astrolsp"|"nvim-treesitter-textobjects"|"nvim-ts-autotag"' lazy-lock.json
+```
+
+Commit lockfile and only generated plugin-lock changes:
+
+```bash
+git add lazy-lock.json
+git commit -m "chore: refresh lazy lockfile for AstroNvim v6"
+```
+
+If Lazy sync also changes source files unexpectedly, inspect carefully before staging. Do not blindly include unrelated source changes in the lockfile commit.
+
+### Phase 10: Verification
+
+Run startup check:
+
+```bash
+nvim --headless +'lua print("startup ok")' +qa
+```
+
+Run Tree-sitter health:
+
+```bash
+nvim --headless '+checkhealth nvim-treesitter' +qa
+```
+
+Manual markdown crash reproduction test:
+
+Create or open a markdown file containing fenced code blocks:
+
+````markdown
+# Tree-sitter crash test
+
+```lua
+print("hello")
+```
+
+```bash
+echo hello
+```
+````
+
+Open it with the migrated config:
+
+```bash
+nvim /tmp/treesitter-crash-test.md
+```
+
+Confirm:
+
+- no `range()` nil crash
+- highlighting starts without decoration-provider error
+- `:checkhealth nvim-treesitter` is acceptable
+- `:Lazy show nvim-treesitter` shows a new compatible commit, not `42fc28ba...`
+
+Also run:
+
+```vim
+:checkhealth vim.lsp
+```
+
+because AstroNvim v6 uses newer LSP APIs.
+
+### Phase 11: Optional follow-up fixes
+
+Only create these commits if testing reveals real issues.
+
+Possible commit:
+
+```bash
+git commit -m "fix: adjust AstroCommunity vimtex treesitter integration"
+```
+
+Use if `astrocommunity.markdown-and-latex.vimtex` causes Tree-sitter option issues under v6.
+
+Possible commit:
+
+```bash
+git commit -m "fix: resolve AstroNvim v6 startup warnings"
+```
+
+Use for any startup warnings caused by changed APIs.
+
+Possible commit:
+
+```bash
+git commit -m "chore: clean stale v5 plugin locks"
+```
+
+Use only if stale lockfile entries remain after `:Lazy sync` and are confirmed unused.
+
+## Final state before user merge
+
+Before handing back to the user, provide:
+
+```bash
+git status --short --branch
+git log --oneline --decorate -8
+git diff main...HEAD --stat
+```
+
+Expected:
+
+- branch is `migrate/astronvim-v6-nvim-0.12`
+- working tree clean
+- commits are atomic and understandable
+- startup and Tree-sitter tests pass
+
+The user will merge manually when satisfied:
+
+```bash
+git switch main
+git merge --ff-only migrate/astronvim-v6-nvim-0.12
+```
+
+If non-fast-forward is needed, user should inspect first. Do not force merge.
+
+## Rollback plan
+
+If migration branch fails:
+
+```bash
+git switch main
+```
+
+Since migration work is isolated to the branch, `main` remains available.
+
+If runtime/plugin state was changed and user needs old v5 runtime back, options:
+
+1. Use `:Lazy restore` from the old lockfile on `main`, or
+2. restore backed-up runtime folders if backups were created, or
+3. clean Lazy plugin dirs and reinstall from `main` lockfile.
+
+Before destructive runtime cleanup, ask the user.
+
+Supported fallback matrix:
+
+```text
+AstroNvim v5 + Neovim 0.11.x = supported old path
+AstroNvim v6 + Neovim 0.12.x = supported new path
+AstroNvim v5 + Neovim 0.12.x = unsupported/problematic
+```
+
+## Open questions for orchestrator/build agent
+
+1. If branch `migrate/astronvim-v6-nvim-0.12` already exists, ask before reusing or creating a suffixed branch.
+2. If `:Lazy sync` changes many unrelated lock entries, decide whether to accept as part of v6 migration or split additional lockfile commits.
+3. If `tree-sitter-cli` health fails, inspect Mason-installed version before removing/changing Mason config.
+4. If `vimtex` AstroCommunity module conflicts with v6 Tree-sitter configuration, patch that module via user config rather than editing plugin checkout.
+
+## Sources/research basis
+
+- Official AstroNvim v6 migration guide provided by user.
+- AstroNvim v6 docs: Tree-sitter feature configuration moved to AstroCore `opts.treesitter`.
+- AstroNvim v6 docs: AstroLSP uses Neovim `vim.lsp.config` / `vim.lsp.enable` APIs.
+- `nvim-treesitter` current behavior: `main` branch is required/targeted for Neovim 0.12; old `master` is incompatible.
+- Local audit found no active source references to v6-renamed plugin names or removed plugin names.
+- Local audit found `astrolsp.lua` likely does not need migration.
+- Local audit found active AstroCommunity imports are under `lua/plugins/astrocommunity.lua`, not disabled `lua/community.lua`.
diff --git a/lazy-lock.json b/lazy-lock.json
index ffecce3..c707f96 100644
--- a/lazy-lock.json
+++ b/lazy-lock.json
@@ -2,7 +2,7 @@
   "AstroNvim": { "branch": "main", "commit": "7fd58328e2bc91d5cad606ee48fdf924fca6ea3e" },
   "LuaSnip": { "branch": "master", "commit": "642b0c595e11608b4c18219e93b88d7637af27bc" },
   "aerial.nvim": { "branch": "master", "commit": "645d108a5242ec7b378cbe643eb6d04d4223f034" },
-  "astrocommunity": { "branch": "main", "commit": "b2d0afe447eb61f3d648d2c55873f93e1e0b6f4a" },
+  "astrocommunity": { "branch": "main", "commit": "50724d19d4a11f0a8c26a5eb198b1767a67b1da1" },
   "astrocore": { "branch": "main", "commit": "5052189882442cf71e04ad2d5472ee31bfe6a5cf" },
   "astrolsp": { "branch": "main", "commit": "0befe28a4ea96e46b7f7c01e4a634c04225ba55a" },
   "astrotheme": { "branch": "main", "commit": "95c046b763266a4873bdf0cbf6a1824c929dec3a" },
@@ -23,11 +23,11 @@
   "mason-nvim-dap.nvim": { "branch": "main", "commit": "e51f9b259f066c4347f9a79ffde54c29a0619384" },
   "mason-tool-installer.nvim": { "branch": "main", "commit": "443f1ef8b5e6bf47045cb2217b6f748a223cf7dc" },
   "mason.nvim": { "branch": "main", "commit": "44d1e90e1f66e077268191e3ee9d2ac97cc18e65" },
-  "milli.nvim": { "branch": "main", "commit": "6a19fe9ab2a068b7ce384cea277c24672add161e" },
+  "milli.nvim": { "branch": "main", "commit": "00274623b76a66356e31e1861360b269987a7f64" },
   "mini.icons": { "branch": "main", "commit": "397ed3807e96b59709ef3292f0a3e253d5c1dc0a" },
-  "neo-tree.nvim": { "branch": "main", "commit": "84c75e7a7e443586f60508d12fc50f90d9aee14e" },
+  "neo-tree.nvim": { "branch": "main", "commit": "83e7a2982fd12b9c3d35bc39dd5877cd91a02a61" },
   "neoconf.nvim": { "branch": "main", "commit": "bbe36f4d60ed096282f564ddae4e781e420a8270" },
-  "neogit": { "branch": "master", "commit": "395ac481e197784e410b59b987fadaf9e7481df1" },
+  "neogit": { "branch": "master", "commit": "99326a1310fb2d616b455d2fd16d01bf00682f06" },
   "none-ls.nvim": { "branch": "main", "commit": "3c206dfedf5f1385e9d29f85ffaec7874358592a" },
   "nui.nvim": { "branch": "main", "commit": "f535005e6ad1016383f24e39559833759453564e" },
   "nvim-autopairs": { "branch": "master", "commit": "c2a0dd0d931d0fb07665e1fedb1ea688da3b80b4" },
@@ -36,7 +36,7 @@
   "nvim-highlight-colors": { "branch": "main", "commit": "e2cb22089cc2358b2b995c09578224f142de6039" },
   "nvim-lspconfig": { "branch": "master", "commit": "fa2662510d30b06168b6e2e6915518decde6bbac" },
   "nvim-nio": { "branch": "master", "commit": "21f5324bfac14e22ba26553caf69ec76ae8a7662" },
-  "nvim-treesitter": { "branch": "master", "commit": "42fc28ba918343ebfd5565147a42a26580579482" },
+  "nvim-treesitter": { "branch": "main", "commit": "42fc28ba918343ebfd5565147a42a26580579482" },
   "nvim-treesitter-textobjects": { "branch": "main", "commit": "5ca4aaa6efdcc59be46b95a3e876300cfead05ef" },
   "nvim-ts-autotag": { "branch": "main", "commit": "db15f2e0df2f5db916e511e3fffb682ef2f6354f" },
   "nvim-window-picker": { "branch": "main", "commit": "6382540b2ae5de6c793d4aa2e3fe6dbb518505ec" },
@@ -48,6 +48,6 @@
   "todo-comments.nvim": { "branch": "main", "commit": "31e3c38ce9b29781e4422fc0322eb0a21f4e8668" },
   "toggleterm.nvim": { "branch": "main", "commit": "50ea089fc548917cc3cc16b46a8211833b9e3c7c" },
   "vim-illuminate": { "branch": "master", "commit": "0d1e93684da00ab7c057410fecfc24f434698898" },
-  "vimtex": { "branch": "master", "commit": "97e11bd4f56d46a87f8593d6ccb27820e19c4ab0" },
+  "vimtex": { "branch": "master", "commit": "182ad387e3f3107699483606c9a2b6648f8437b2" },
   "which-key.nvim": { "branch": "main", "commit": "fcbf4eea17cb299c02557d576f0d568878e354a4" }
 }
diff --git a/lua/plugins/treesitter.lua b/lua/plugins/treesitter.lua
index 94436aa..b83cd4d 100644
--- a/lua/plugins/treesitter.lua
+++ b/lua/plugins/treesitter.lua
@@ -1,15 +1,16 @@
-if true then return {} end -- WARN: REMOVE THIS LINE TO ACTIVATE THIS FILE
-
 -- Customize Treesitter
 
 ---@type LazySpec
 return {
   "nvim-treesitter/nvim-treesitter",
+  branch = "main",
+  build = ":TSUpdate",
   opts = {
     ensure_installed = {
       "lua",
+      "markdown",
+      "markdown_inline",
       "vim",
-      -- add more arguments for adding more treesitter parsers
     },
   },
 }