@@ -27,7 +27,7 @@ See proposal.md. The switch of the published site is `migrate-docs-to-starlight`
 
 ### D1: A standalone Astro project in `docs-next/`
 
-`docs-next/` has its own `package.json` and `package-lock.json` with `astro`, `@astrojs/starlight`, `@astrojs/markdown-satteri`, `starlight-blog`, `starlight-links-validator`, `starlight-llms-txt` and `lite-youtube-embed`, plus `js-yaml` and `github-slugger` for the conversion script, pinned to the minors verified during exploration (Astro 7.3, Starlight 0.42) and otherwise on their newest versions, and is not added to the root `workspaces`. `sharp` needs no entry: Astro brings it as an optional dependency. `@astrojs/markdown-satteri` is listed because `astro.config.mjs` imports it to set the processor options (D9); Astro has no other setting for them. Starlight imports js-yaml 4 with a default import, and Astro's prerender build keeps that import external, so it would load the `js-yaml` 5 of the conversion script from the project root and fail; `environments.prerender.resolve.noExternal: ["js-yaml"]` bundles it with Starlight's own copy, as Astro does for `neotraverse` (withastro/astro#17508). An `overrides` entry pins `@astrojs/markdown-satteri` to the direct dependency: `starlight-blog` 0.30 still depends on `@astrojs/mdx` 7, which declares it as a `^0.3` peer, and npm 10 (Node 22, the CI) and npm 12 resolve that differently, so without the entry a lockfile written by one fails `npm ci` in the other; the entry goes when `starlight-blog` moves to `@astrojs/mdx` 8. A `vite.build.rolldownOptions.onwarn` filter drops rolldown's `MODULE_LEVEL_DIRECTIVE` warning about the `use astro:head-inject` directive Astro 7.3 still prepends to MDX pages but no longer reads (withastro/astro#18087), once per MDX page; the filter goes when the fix is released. Root scripts `docs-next:install|dev|build|preview` call `npm --prefix docs-next …` for convenience. Layout: `astro.config.mjs`, `src/pages/404.astro` (the not-found page, D9), `src/content.config.ts` (with Starlight's optional `i18n` collection; `src/content/i18n/en.json` overrides no UI string but keeps the collection from being empty, which Astro 7 reports as a warning on every build), `scripts/convert.mjs`, `content/` (hand-written pages), `src/components/`, `src/styles/custom.css`, `README.md`; `src/content/docs/`, `src/assets/` and `public/` are generated.
+`docs-next/` has its own `package.json` and `package-lock.json` with `astro`, `@astrojs/starlight`, `@astrojs/markdown-satteri`, `starlight-blog`, `starlight-links-validator`, `starlight-llms-txt` and `lite-youtube-embed`, plus `js-yaml` and `github-slugger` for the conversion script, pinned to the minors verified during exploration (Astro 7.3, Starlight 0.42) and otherwise on their newest versions, and is not added to the root `workspaces`. `sharp` needs no entry: Astro brings it as an optional dependency. `@astrojs/markdown-satteri` is listed because `astro.config.mjs` imports it to set the processor options (D9); Astro has no other setting for them. Starlight imports js-yaml 4 with a default import, and Astro's prerender build keeps that import external, so it would load the `js-yaml` 5 of the conversion script from the project root and fail; `environments.prerender.resolve.noExternal: ["js-yaml"]` bundles it with Starlight's own copy, as Astro does for `neotraverse` (withastro/astro#17508). An `overrides` entry gives `starlight-blog` the `@astrojs/mdx` 8 that Starlight and `starlight-llms-txt` use, with Starlight's range `^8.0.0`: `starlight-blog` 0.30 still declares `@astrojs/mdx` 7, whose `@astrojs/markdown-satteri` `^0.3` peer npm 10 (Node 22, the CI) and npm 12 resolve differently, so a lockfile written by one would fail `npm ci` in the other; with the entry the tree has one MDX integration and no unmet peer. The entry goes when `starlight-blog` moves to `@astrojs/mdx` 8. A `vite.build.rolldownOptions.onwarn` filter drops rolldown's `MODULE_LEVEL_DIRECTIVE` warning about the `use astro:head-inject` directive Astro 7.3 still prepends to MDX pages but no longer reads (withastro/astro#18087), once per MDX page; the filter goes when the fix is released. Root scripts `docs-next:install|dev|build|preview` call `npm --prefix docs-next …` for convenience. Layout: `astro.config.mjs`, `src/pages/404.astro` (the not-found page, D9), `src/content.config.ts` (with Starlight's optional `i18n` collection; `src/content/i18n/en.json` overrides no UI string but keeps the collection from being empty, which Astro 7 reports as a warning on every build), `scripts/convert.mjs`, `content/` (hand-written pages), `src/components/`, `src/styles/custom.css`, `README.md`; `src/content/docs/`, `src/assets/` and `public/` are generated.
 
 Rejected: a root workspace — the root `npm install` of every contributor and of the Node-20 CI jobs would pull about 375 more packages and print `EBADENGINE` for Astro; a branch — it would fall behind `docs/` and need regular merges; a one-time copy of the content — see D3.
 
@@ -73,7 +73,7 @@ Rejected: the numbered folders — their numbers exist only to order the VitePre
 - Page-specific rules from the page map: the "Requirements" and "Optional Python Packages" sections of the VS Code walkthrough are cut out and inserted into the Getting Started overview at a marker; the April Fools post gets its joke notice as first paragraph (D7); `reference/cli` gets `tableOfContents.maxHeadingLevel: 6`, since its commands sit at H3–H6.
 - Static files: `docs/public/robotcode-logo.svg`, `robotcode-logo-mini.png`, `robotcode-logo.jpg` and `schemas/robot.toml.json` go to `public/`, and `robotcode-logo.svg` also to `src/assets/` for Starlight's `logo` option; the nine hero pictures listed in `RandomHeroImage.vue` (not `robotcode-golf2.png` and `robotcode-vintage-christmas.png`) go to `src/assets/hero/`, the supporter logos of `docs/images/` to `src/assets/logos/`; images no page references are not copied.
 - A page index for `/llms.txt` (title, URL and description of every page, in sidebar order) is written to `docs-next/.generated/llms-index.md` (git-ignored), which `astro.config.mjs` passes to `starlight-llms-txt` as `details`.
-- After converting, the script scans its output outside code for patterns only VitePress uses — `:::` followed by whitespace (its own asides are written `:::tip[…]`), `:::` followed by a container name Starlight lacks (`info`, `warning`, `details`, `code-group`, `tabs`, `raw`, `v-pre`), `[[`, `[!code`, a line starting with `=== `, `{#` in `.mdx` — and fails if it finds any; the build then fails on broken links (D6).
+- After converting, the script scans its output outside code for patterns only VitePress uses — `:::` followed by whitespace (its own asides are written `:::tip[…]`), `:::` followed by a container name Starlight lacks (`info`, `warning`, `details`, `code-group`, `tabs`, `raw`, `v-pre`), `[[`, `[!code`, a line starting with `=== `, `{#` in `.mdx` — and fails if it finds any. It also checks that every root-relative link in `src/pages/` (the not-found page) points to a page of the site, since the link check of the build (D6) reads only the docs collection; the build then fails on broken links in the pages.
 
 Pages that need no component stay `.md` (all generated pages, all pages with `<PORT>`-style placeholders). The demo's script (`scratchpad/demo/scripts/convert.mjs`) implements most of these rules and is the starting point.
 
@@ -110,7 +110,7 @@ The April Fools post invents options (`prediction-depth`, `sponsored-keywords`,
 ### D9: Home page, 404, search, images, theming, LLM exports
 
 - **Home:** `content/index.mdx` with `template: splash` and `hero` (title, tagline, actions with icons; Get Started → `/getting-started/`). A `Hero` override wraps Starlight's `Hero` and ports `RandomHeroImage.vue` and `RandomTagline.vue` as a custom element, passed to Starlight's `Hero` as the hero's HTML image so that Starlight's layout places it: random picture from `src/assets/hero/` on load (all rendered as optimized images), previous/next buttons, horizontal swipe with the same thresholds and click suppression, an enlarged view as a `<dialog>` closed by click or Escape with arrow-key navigation, and a random subline. Features as `<CardGrid>`/`<Card>` with Starlight icons, linking to the pages that cover them: REPL & notebooks → `/guides/repl/`, Run, debug & test explorer → `/getting-started/vscode/` and `/guides/robot-debug/`, One config everywhere → `/getting-started/configuration/`, Multi-IDE → `/getting-started/`, Powerful CLI → `/reference/cli/`; Project-wide refactoring links nowhere, since no page covers refactoring. The RoboCon video with `lite-youtube` through a small `YouTubeVideo` component, which imports the script and CSS of `lite-youtube-embed` so they are bundled; a `Footer` override adds the license line.
-- **404:** `src/pages/404.astro`, a `StarlightPage` (splash, no edit link or last-change date, not indexed by Pagefind): this documentation keeps evolving, so pages and links can move; use the search, or start from Getting Started, Guides, Reference or News. It is not part of the docs collection, so it stays out of `/llms-full.txt` and `/llms-small.txt` (whose plugin reads the whole collection), and `astro dev` shows it for unknown paths too. `disable404Route: true` turns off Starlight's own 404 route. The link check reads only the docs collection, so the page's four links to the areas are not checked.
+- **404:** `src/pages/404.astro`, a `StarlightPage` (splash, no edit link or last-change date, not indexed by Pagefind): this documentation keeps evolving, so pages and links can move; use the search, or start from Getting Started, Guides, Reference or News. It is not part of the docs collection, so it stays out of `/llms-full.txt` and `/llms-small.txt` (whose plugin reads the whole collection), and `astro dev` shows it for unknown paths too. `disable404Route: true` turns off Starlight's own 404 route. The link check reads only the docs collection, so the conversion script checks the page's four links to the areas (D3).
 - **Search:** Pagefind, Starlight's default, available in `build`/`preview`. The Algolia index describes the published site; switching to Algolia is part of `migrate-docs-to-starlight`.
 - **Theme and code:** brand colours as `--sl-color-accent-*` in `custom.css`; the Robot grammar, a small `gitignore` grammar for the `.robotignore` examples (comments, negation, wildcards; Shiki has none) and the two Material themes through `expressiveCode.shiki.langs`/`themes`; Sätteri with `smartPunctuation: false` and `headingAttributes: true`.
 - **Social links:** built-in icons `github`, `seti:python` (PyPI), `vscode`, `jetbrains`, `openCollective`; `starlight-blog` adds the RSS icon.
@@ -120,7 +120,7 @@ The April Fools post invents options (`prediction-depth`, `sponsored-keywords`,
 ### D10: Preview workflow, CI and isolation
 
 - `docs-next/README.md`: Node ≥22.12, `npm ci`, `npm run dev` (reloads components and styles live; edits in `docs/` or `docs-next/content/` need a restart, since the conversion runs at start) or `npm run build && npm run preview` (with search), that content is edited in `docs/`, how to add a page-map entry, and `ASTRO_TELEMETRY_DISABLED=1`. `CONTRIBUTING.md` gets a short section pointing to it and saying that a new page in `docs/` needs a page-map entry and that changes to the home page or an overview in `docs/` must be mirrored in `docs-next/content/`.
-- `.github/workflows/docs-next.yml`: on pushes and pull requests that touch `docs/**`, `docs-next/**` or the workflow, on Node 22 with `ASTRO_TELEMETRY_DISABLED=1`, `npm ci` and `npm run build` in `docs-next/`; nothing is uploaded or deployed.
+- `.github/workflows/docs-next.yml`: on pushes and pull requests that touch `docs/**`, `docs-next/**`, the Robot grammar `syntaxes/robotframework.tmLanguage.json` (which the preview highlights with) or the workflow, on Node 22 with `ASTRO_TELEMETRY_DISABLED=1`, `npm ci` and `npm run build` in `docs-next/`; nothing is uploaded or deployed.
 - `build-test-package-publish.yml` gets `docs-next/**` in `paths-ignore`, `.vscodeignore` gets `docs-next/`, `eslint.config.mjs` ignores `**/docs-next/`, each next to the existing `docs` entry.
 - `AGENTS.md` (Task Routing, Docs): `docs-next/` is the Starlight preview; content is edited only in `docs/`; the page map is `docs-next/scripts/convert.mjs`; `src/content/docs/`, `src/assets/` and `public/` of `docs-next/` are generated. Common Commands: `npm run docs-next:dev|docs-next:build|docs-next:preview`.
 - The documentation tasks of `doc-cli` (7.1), `library-keyword-set-declaration` (5.1) and `library-index` (8.1), which add pages to `docs/03_reference/`, get a page-map entry (id and area by the rule of D2, title, label, order, description) and a `npm run docs-next:build` check.
 
@@ -29,11 +29,11 @@
 ## 5. Preview workflow, CI and isolation
 
 - [x] 5.1 Write `docs-next/README.md`, the preview section in `CONTRIBUTING.md` and the `docs-next` entries in `AGENTS.md` (D10); verify that the commands they name work from a fresh clone on Node 22
-- [x] 5.2 Add `.github/workflows/docs-next.yml` (build only, on changes to `docs/**`, `docs-next/**` and the workflow itself, Node 22, `ASTRO_TELEMETRY_DISABLED=1`) (D10); verify by running its steps locally (`npm ci` and `npm run build` in `docs-next/`) and, once pushed by the maintainer, by a green run
+- [x] 5.2 Add `.github/workflows/docs-next.yml` (build only, on changes to `docs/**`, `docs-next/**`, `syntaxes/robotframework.tmLanguage.json` and the workflow itself, Node 22, `ASTRO_TELEMETRY_DISABLED=1`) (D10); verify by running its steps locally (`npm ci` and `npm run build` in `docs-next/`) and, once pushed by the maintainer, by a green run
 - [x] 5.3 Add `docs-next/**` to `paths-ignore` of `build-test-package-publish.yml`, `docs-next/` to `.vscodeignore` and `**/docs-next/` to the ignores of `eslint.config.mjs` (D10); verify that `npx @vscode/vsce ls` lists no file under `docs-next/` and that `npm run lint` does not lint `docs-next/`
 - [x] 5.4 Add the page-map step and a `npm run docs-next:build` check to the documentation tasks of `doc-cli` (7.1), `library-keyword-set-declaration` (5.1) and `library-index` (8.1) (D10); verify with `openspec validate` for each of the three changes
 
 ## 6. Verification
 
-- [ ] 6.1 Check the scenarios of `specs/documentation-site/spec.md` in `npm run docs-next:preview`: old path gets the not-found page, the new paths, top navigation and compact menu, area sidebars (top-level labels About, Getting Started, Guides, Reference, Support & Contribute), meta description and `og:url` of `/guides/repl/`, the three overviews, news list, feed, tag pages and joke notice, optimized screenshots, `/schemas/robot.toml.json`, `/llms.txt` (lists `/guides/repl/`) and `/llms-full.txt` (contains the CLI and configuration references), search for `console-colors`, edit link and last-change date of `/getting-started/neovim/`, `--include` rendered literally, Robot highlighting, home picture controls and card targets; verify each with the page or a `curl`/`grep` against the preview and record the results in the `/opsx:verify` report
+- [x] 6.1 Check the scenarios of `specs/documentation-site/spec.md` in `npm run docs-next:preview`: old path gets the not-found page, the new paths, top navigation and compact menu, area sidebars (top-level labels About, Getting Started, Guides, Reference, Support & Contribute), meta description and `og:url` of `/guides/repl/`, the three overviews, news list, feed, tag pages and joke notice, optimized screenshots, `/schemas/robot.toml.json`, `/llms.txt` (lists `/guides/repl/`) and `/llms-full.txt` (contains the CLI and configuration references), search for `console-colors`, edit link and last-change date of `/getting-started/neovim/`, `--include` rendered literally, Robot highlighting, home picture controls and card targets; verify each with the page or a `curl`/`grep` against the preview and record the results in the `/opsx:verify` report
 - [x] 6.2 Confirm the isolation: `npm run docs:build` builds the current site unchanged apart from the two link fixes, and `openspec validate docs-starlight-preview --strict` passes
@@ -28,7 +28,7 @@ See proposal.md. This change assumes `docs-starlight-preview` is applied: `docs-
 
 1. Run the conversion one last time in a switch mode, from the unmoved tree into a temporary directory: without `editUrl` and `lastUpdated` (from now on `editLink.baseUrl` and the git history of the page files provide them), with the hand-written pages included and the Getting Started marker filled.
 2. Move every old page and every referenced image to its new place with `git mv`, following the page map of `docs-starlight-preview` (e.g. `docs/03_reference/repl.md` → `docs/src/content/docs/guides/repl.md`, `docs/02_get_started/images/python-create-env.gif` → `docs/src/assets/screenshots/python-create-env.gif`, the nine hero pictures from `docs/public/` → `docs/src/assets/hero/`), so `git log --follow` keeps the history; then overwrite each moved file with its converted version from step 1 and add the hand-written pages from there.
-3. Move the project files of `docs-next/` (`astro.config.mjs`, `src/content.config.ts`, `src/content/i18n/`, `src/pages/`, `src/components/`, `src/styles/`) into `docs/`, set `editLink.baseUrl` to `https://github.com/robotcodedev/robotcode/edit/main/docs/` (Starlight appends `src/content/docs/<page>`), merge the dependencies into `docs/package.json` (without `github-slugger`, which only the deleted conversion script uses) and its `overrides` entry into the root `package.json`, since npm reads `overrides` only in the workspace root. The page index for `/llms.txt`, which the conversion script wrote to `.generated/llms-index.md`, is then built by a small module `docs/scripts/llms-index.mjs` that `astro.config.mjs` calls: it reads title, description and sidebar order from the frontmatter of `src/content/docs/` and produces the same list in the same order. Then delete `docs-next/` (with the conversion script and `content/`), `.vitepress/`, `news/posts.data.ts`, the replaced index pages, the old image directories (`docs/images/`, `docs/0x_*/images/`), the images in `docs/public/` no page references (`robotcode-golf2.png`, `robotcode-vintage-christmas.png`, `autocomplete1.gif`, `running_tests.gif`) and the VitePress dependencies.
+3. Move the project files of `docs-next/` (`astro.config.mjs`, `src/content.config.ts`, `src/content/i18n/`, `src/pages/`, `src/components/`, `src/styles/`) into `docs/`, set `editLink.baseUrl` to `https://github.com/robotcodedev/robotcode/edit/main/docs/` (Starlight appends `src/content/docs/<page>`), merge the dependencies into `docs/package.json` (without `github-slugger`, which only the deleted conversion script uses) and its `overrides` entry into the root `package.json`, since npm reads `overrides` only in the workspace root. The page index for `/llms.txt`, which the conversion script wrote to `.generated/llms-index.md`, is then built by a small module `docs/scripts/llms-index.mjs` that `astro.config.mjs` calls: it reads title, description and sidebar order from the frontmatter of `src/content/docs/` and produces the same list in the same order. The check of the links in `src/pages/`, also part of the conversion script, becomes a `prebuild` script `docs/scripts/check-page-links.mjs`. Then delete `docs-next/` (with the conversion script and `content/`), `.vitepress/`, `news/posts.data.ts`, the replaced index pages, the old image directories (`docs/images/`, `docs/0x_*/images/`), the images in `docs/public/` no page references (`robotcode-golf2.png`, `robotcode-vintage-christmas.png`, `autocomplete1.gif`, `running_tests.gif`) and the VitePress dependencies.
 
 `docs/public/` keeps `CNAME`, the favicons, the Open Graph image and `schemas/robot.toml.json`. `docs/` stays the root workspace; the root `.gitignore` gets `docs/.astro/` (`dist/` is ignored already).