From 19eeb1f300b55719b44b6d7404931b57ac9db8e6 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Fri, 7 Aug 2026 00:47:39 +0000
Subject: [PATCH] docs: add Antora component and migrate guides to AsciiDoc

- Add docs/antora.yml with ROOT module pages for ecosystem, specification,
  AI reproduction spec, glass lens capabilities, and editor integrations
- Add changelog index with detail pages backfilled from git history
- Add README.adoc with Docs | Dev-Centr badge; update README.md links
- Point package, extension, and demo links at docs.devcentr.org/code-lens/

Co-authored-by: Ryan Johnson <AMDphreak@users.noreply.github.com>
---
 .gitignore                                    |   1 +
 CHANGELOG.md                                  |   6 +
 README.adoc                                   | 114 ++++++++++
 README.md                                     |  13 +-
 demo/README.md                                |   3 +-
 demo/src/App.tsx                              |   4 +-
 docs/README.adoc                              |  10 +
 docs/ai-reproduction-spec.md                  | 189 -----------------
 docs/antora.yml                               |   6 +
 docs/ecosystem.md                             | 143 -------------
 docs/editor-integrations.md                   |  93 ---------
 docs/glass-lens-capabilities.md               |  62 ------
 docs/modules/ROOT/nav.adoc                    |   7 +
 .../ROOT/pages/ai-reproduction-spec.adoc      | 196 ++++++++++++++++++
 .../changelog-details/2026-05-28-v0.1.0.adoc  |  14 ++
 .../changelog-details/2026-05-29-v0.2.x.adoc  |  74 +++++++
 .../changelog-details/2026-05-29-v0.3.12.adoc |  10 +
 .../changelog-details/2026-05-29-v0.3.13.adoc |  11 +
 .../changelog-details/2026-05-29-v0.3.x.adoc  |  79 +++++++
 docs/modules/ROOT/pages/changelog.adoc        |  45 ++++
 docs/modules/ROOT/pages/ecosystem.adoc        | 156 ++++++++++++++
 .../ROOT/pages/editor-integrations.adoc       | 102 +++++++++
 .../ROOT/pages/glass-lens-capabilities.adoc   |  68 ++++++
 docs/modules/ROOT/pages/index.adoc            |  65 ++++++
 docs/modules/ROOT/pages/specification.adoc    |  99 +++++++++
 docs/specification.md                         |  91 --------
 extensions/vscode/README.md                   |   2 +-
 extensions/zed/README.md                      |   2 +-
 implementations/REGISTRY.md                   |   2 +-
 packages/core/src/capabilities.ts             |   2 +-
 packages/css/README.md                        |   2 +-
 packages/react/README.md                      |   2 +-
 packages/solid/README.md                      |   2 +-
 packages/tailwind/README.md                   |   2 +-
 spec/implementations.json5                    |   2 +-
 35 files changed, 1084 insertions(+), 595 deletions(-)
 create mode 100644 README.adoc
 create mode 100644 docs/README.adoc
 delete mode 100644 docs/ai-reproduction-spec.md
 create mode 100644 docs/antora.yml
 delete mode 100644 docs/ecosystem.md
 delete mode 100644 docs/editor-integrations.md
 delete mode 100644 docs/glass-lens-capabilities.md
 create mode 100644 docs/modules/ROOT/nav.adoc
 create mode 100644 docs/modules/ROOT/pages/ai-reproduction-spec.adoc
 create mode 100644 docs/modules/ROOT/pages/changelog-details/2026-05-28-v0.1.0.adoc
 create mode 100644 docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.2.x.adoc
 create mode 100644 docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.12.adoc
 create mode 100644 docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.13.adoc
 create mode 100644 docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.x.adoc
 create mode 100644 docs/modules/ROOT/pages/changelog.adoc
 create mode 100644 docs/modules/ROOT/pages/ecosystem.adoc
 create mode 100644 docs/modules/ROOT/pages/editor-integrations.adoc
 create mode 100644 docs/modules/ROOT/pages/glass-lens-capabilities.adoc
 create mode 100644 docs/modules/ROOT/pages/index.adoc
 create mode 100644 docs/modules/ROOT/pages/specification.adoc
 delete mode 100644 docs/specification.md

diff --git a/.gitignore b/.gitignore
index 6754135..704b117 100644
--- a/.gitignore
+++ b/.gitignore
@@ -18,6 +18,7 @@
 !extensions/
 !extensions/**
 !README.md
+!README.adoc
 !CHANGELOG.md
 !LICENSE
 !package.json
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4d6ebe3..1a721ef 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,9 +2,15 @@
 
 ## Unreleased
 
+### Added
+
+- **Antora docs** — `docs/antora.yml` and AsciiDoc pages under `docs/modules/ROOT/` for the Dev-Centr docs portal; changelog index with detail pages.
+- **README.adoc** — primary readme with Docs | Dev-Centr badge; `README.md` retained for GitHub/npm rendering.
+
 ### Changed
 
 - Repository transferred from `AMDphreak/code-lens` to [`dev-centr/code-lens`](https://github.com/dev-centr/code-lens). Live demo: [dev-centr.github.io/code-lens](https://dev-centr.github.io/code-lens/).
+- Flat `docs/*.md` guides migrated to AsciiDoc; links in README and demo README point at `docs.devcentr.org/code-lens/`.
 
 ## [0.3.13] - 2026-05-29
 
diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..394f848
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,114 @@
+ifndef::env-github[:icons: font]
+:toc: preamble
+:toclevels: 2
+:sectanchors:
+
+ifndef::env-github[]
+image:https://img.shields.io/github/contributors/dev-centr/code-lens.svg?style=for-the-badge[Contributors,link=https://github.com/dev-centr/code-lens/graphs/contributors]
+image:https://img.shields.io/github/forks/dev-centr/code-lens.svg?style=for-the-badge[Forks,link=https://github.com/dev-centr/code-lens/network/members]
+image:https://img.shields.io/github/stars/dev-centr/code-lens.svg?style=for-the-badge[Stars,link=https://github.com/dev-centr/code-lens/stargazers]
+image:https://img.shields.io/github/issues/dev-centr/code-lens.svg?style=for-the-badge[Issues,link=https://github.com/dev-centr/code-lens/issues]
+image:https://img.shields.io/github/license/dev-centr/code-lens.svg?style=for-the-badge[License,link=https://github.com/dev-centr/code-lens/blob/main/LICENSE]
+image:https://img.shields.io/badge/docs-Dev--Centr-22c55e[Docs,link=https://docs.devcentr.org/code-lens/]
+image:https://github.com/dev-centr/code-lens/actions/workflows/pages.yml/badge.svg[Deploy GitHub Pages,link=https://github.com/dev-centr/code-lens/actions/workflows/pages.yml]
+endif::[]
+
+ifdef::env-github[]
+image:https://img.shields.io/github/contributors/dev-centr/code-lens.svg?style=for-the-badge[Contributors]
+image:https://img.shields.io/github/forks/dev-centr/code-lens.svg?style=for-the-badge[Forks]
+image:https://img.shields.io/github/stars/dev-centr/code-lens.svg?style=for-the-badge[Stars]
+image:https://img.shields.io/github/issues/dev-centr/code-lens.svg?style=for-the-badge[Issues]
+image:https://img.shields.io/github/license/dev-centr/code-lens.svg?style=for-the-badge[License]
+image:https://img.shields.io/badge/docs-Dev--Centr-22c55e[Docs | Dev-Centr]
+image:https://github.com/dev-centr/code-lens/actions/workflows/pages.yml/badge.svg[Deploy GitHub Pages]
+endif::[]
+
+= code-lens
+
+[.text-center]
+One code snippet, multiple pedagogical lenses — portable JSON5 spec and `<code-lens>` web component with framework adapters.
+
+link:https://dev-centr.github.io/code-lens/[Live demo] ·
+link:https://docs.devcentr.org/code-lens/[Docs | Dev-Centr] ·
+link:https://github.com/dev-centr/code-lens/issues[Report Bug] ·
+link:https://github.com/dev-centr/code-lens/issues[Request Feature]
+
+== About The Project
+
+One snippet, multiple pedagogical naming conventions — the real lens for code examples (not a metaphor).
+
+=== Delivery model
+
+*In Solid/React/Next you install a component* — e.g. `import { CodeLens } from "@code-lens/solid"`.
+Under the hood one shared engine powers every framework package.
+
+[cols="1,1",options="header"]
+|===
+| Layer | Package
+| Component (your import) | `@code-lens/solid`, `@code-lens/react`, …
+| Skin | `@code-lens/css` or `@code-lens/tailwind` (planned)
+| Engine | `@code-lens/vanilla` + `@code-lens/core` (pulled in automatically)
+|===
+
+→ link:https://docs.devcentr.org/code-lens/ecosystem.html[Delivery model docs]
+
+== Installation
+
+[source,bash]
+----
+pnpm install
+pnpm dev          # SolidJS + solid-ui demo (port 5174)
+----
+
+== Usage
+
+[source,javascript]
+----
+import "@code-lens/css";
+import { createCodeLens, registerCodeLens } from "@code-lens/vanilla";
+import { parseLensBlock, parseThemes, parseUi } from "@code-lens/core";
+
+registerCodeLens();
+const el = createCodeLens({
+  document: parseLensBlock(blockJson5),
+  themes: parseThemes(themesJson5),
+  ui: parseUi(uiJson5),
+}, "earth");
+document.body.appendChild(el);
+----
+
+[source,html]
+----
+<code-lens theme="earth" appearance="auto"></code-lens>
+----
+
+`appearance`: `auto` | `light` | `dark` — independent of pedagogical color theme.
+
+`slotHighlight`: `plain` | `box` — rounded highlight on changeable tokens (default `plain`).
+
+=== Portable spec
+
+[cols="1,2",options="header"]
+|===
+| File | Role
+| link:https://github.com/dev-centr/code-lens/tree/main/spec/examples[`spec/examples/*.json5`] | Aligned token data per lens
+| link:https://github.com/dev-centr/code-lens/blob/main/spec/themes.json5[`spec/themes.json5`] | Color schemes (light/dark per theme)
+| link:https://github.com/dev-centr/code-lens/blob/main/spec/ui.json5[`spec/ui.json5`] | Interaction + animation
+|===
+
+* link:https://docs.devcentr.org/code-lens/ecosystem.html[Ecosystem / delivery model]
+* link:https://docs.devcentr.org/code-lens/specification.html[Full specification]
+* link:https://docs.devcentr.org/code-lens/ai-reproduction-spec.html[AI / LLM reproduction spec]
+* link:https://docs.devcentr.org/code-lens/glass-lens-capabilities.html[Glass lens capabilities]
+* link:https://github.com/dev-centr/code-lens/blob/main/implementations/REGISTRY.md[Implementation registry]
+
+== License
+
+MIT
+
+== Contact
+
+DevCentr.org — support@devcentr.org
+
+* Project: https://github.com/dev-centr/code-lens
+* Site: https://dev-centr.github.io/code-lens/
diff --git a/README.md b/README.md
index 55e15b0..fbab1ec 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,7 @@
 [![Stargazers][stars-shield]][stars-url]
 [![Issues][issues-shield]][issues-url]
 [![License][license-shield]][license-url]
+[![Docs | Dev-Centr](https://img.shields.io/badge/docs-Dev--Centr-22c55e)](https://docs.devcentr.org/code-lens/)
 [![Deploy GitHub Pages](https://github.com/dev-centr/code-lens/actions/workflows/pages.yml/badge.svg)](https://github.com/dev-centr/code-lens/actions/workflows/pages.yml)
 
 <div align="center">
@@ -13,6 +14,8 @@
   <p>
     <a href="https://dev-centr.github.io/code-lens/">Live demo</a>
     ·
+    <a href="https://docs.devcentr.org/code-lens/">Docs | Dev-Centr</a>
+    ·
     <a href="https://github.com/dev-centr/code-lens/issues">Report Bug</a>
     ·
     <a href="https://github.com/dev-centr/code-lens/issues">Request Feature</a>
@@ -44,7 +47,7 @@ One snippet, multiple pedagogical naming conventions — the real lens for code
 | Skin | `@code-lens/css` or `@code-lens/tailwind` (planned) |
 | Engine | `@code-lens/vanilla` + `@code-lens/core` (pulled in automatically) |
 
-→ [docs/ecosystem.md](docs/ecosystem.md)
+→ [Delivery model docs](https://docs.devcentr.org/code-lens/ecosystem.html)
 
 ## Installation
 
@@ -85,10 +88,10 @@ document.body.appendChild(el);
 | [`spec/themes.json5`](spec/themes.json5) | Color schemes (light/dark per theme) |
 | [`spec/ui.json5`](spec/ui.json5) | Interaction + animation |
 
-- [Ecosystem / delivery model](docs/ecosystem.md)
-- [Full specification](docs/specification.md)
-- [AI / LLM reproduction spec](docs/ai-reproduction-spec.md) — normative porting detail
-- [Glass lens capabilities](docs/glass-lens-capabilities.md)
+- [Ecosystem / delivery model](https://docs.devcentr.org/code-lens/ecosystem.html)
+- [Full specification](https://docs.devcentr.org/code-lens/specification.html)
+- [AI / LLM reproduction spec](https://docs.devcentr.org/code-lens/ai-reproduction-spec.html) — normative porting detail
+- [Glass lens capabilities](https://docs.devcentr.org/code-lens/glass-lens-capabilities.html)
 - [Implementation registry](implementations/REGISTRY.md)
 
 ## License
diff --git a/demo/README.md b/demo/README.md
index 2c58f00..4cab19b 100644
--- a/demo/README.md
+++ b/demo/README.md
@@ -38,6 +38,7 @@ pnpm dlx solidui-cli@latest add dialog tabs
 
 ## GitHub Pages URL
 
-When published from the `code-lens` repository, the site is served at the repo Pages URL (e.g. `https://amdphreak.github.io/code-lens/`). The portfolio links to `https://dev-centr.github.io/code-lens/` when that custom domain is configured on the repo.
+Published from the `dev-centr/code-lens` repository at **https://dev-centr.github.io/code-lens/**.
+Product documentation lives on the Dev-Centr docs portal: **https://docs.devcentr.org/code-lens/**.
 
 `vite.config.ts` uses `base: "./"` so asset paths work under a subdirectory.
diff --git a/demo/src/App.tsx b/demo/src/App.tsx
index 67d0603..a57a783 100644
--- a/demo/src/App.tsx
+++ b/demo/src/App.tsx
@@ -84,7 +84,7 @@ export default function App() {
           </ul>
           <Button
             as="a"
-            href="https://github.com/dev-centr/code-lens/blob/main/docs/specification.md"
+            href="https://docs.devcentr.org/code-lens/specification.html"
             variant="link"
             class="h-auto p-0 font-mono text-xs uppercase tracking-widest"
             target="_blank"
@@ -108,7 +108,7 @@ export default function App() {
             — see{" "}
             <a
               class="link-neutral"
-              href="https://github.com/dev-centr/code-lens/blob/main/docs/editor-integrations.md"
+              href="https://docs.devcentr.org/code-lens/editor-integrations.html"
             >
               editor feasibility
             </a>
diff --git a/docs/README.adoc b/docs/README.adoc
new file mode 100644
index 0000000..cdc98bf
--- /dev/null
+++ b/docs/README.adoc
@@ -0,0 +1,10 @@
+= code-lens documentation
+
+Antora component for the Dev-Centr docs portal.
+
+* Component descriptor: `antora.yml`
+* Pages: `modules/ROOT/pages/`
+* Navigation: `modules/ROOT/nav.adoc`
+
+Build locally as part of the link:https://github.com/dev-centr/docs[dev-centr/docs] playbook.
+Published URL (after playbook registration): link:https://docs.devcentr.org/code-lens/[docs.devcentr.org/code-lens/].
diff --git a/docs/ai-reproduction-spec.md b/docs/ai-reproduction-spec.md
deleted file mode 100644
index ea2ef5b..0000000
--- a/docs/ai-reproduction-spec.md
+++ /dev/null
@@ -1,189 +0,0 @@
-# AI / LLM Reproduction Spec — code-lens
-
-Use this document to implement **code-lens** in any UI framework or toolkit. Follow normative MUST/SHOULD language.
-
-**Reference commit behavior:** slotted morph layout as shipped in `@code-lens/vanilla` ≥ 0.3.9 (restored in 0.3.11) — flex baseline lines, `inline-block` slots at rest and morph, width pin to measured incoming text only, opacity cross-fade, block glass sweep.
-
-## Product definition
-
-Build a component that renders **one aligned multi-line code example** in **four pedagogical lenses**:
-
-1. **didactic** — names are the lesson (`bad_field`)
-2. **schematic** — abstract placeholders (`T`, `value`)
-3. **contextual** — production-shaped names (`WriterHelpers`)
-4. **role** — structural roles (`namespace_member`)
-
-Syntax tokens are identical across lenses. Only slotted tokens (identifiers, strings, comments with a shared `slot` key) differ.
-
-## Data loading
-
-Load three JSON5 files from the repository `spec/` directory:
-
-- Example document (e.g. `spec/examples/zig-namespace.json5`)
-- `spec/themes.json5` (version **2** — light/dark per theme + `syntaxDark`)
-- `spec/ui.json5`
-
-Parse with JSON5. Validate: equal line counts, equal token counts per line, `version: 1`.
-
-Compute variable slots: any `slot` whose `text` differs across lenses.
-
-## Visual structure
-
-```
-┌─ toolbar ─────────────────────────────────────┐
-│ [glass pill]  Lens  [Didactic][Schematic]…  zig │
-├─ body (background = theme.lenses[active].panel) ─┤
-│ subtitle + description (updates instantly)      │
-│ ┌─ code surface (chrome.codeSurface) ─────────┐ │
-│ │ one flex row per line (baseline-aligned)     │ │
-│ │ slotted tokens = plain spans + morph sheen   │ │
-│ └─────────────────────────────────────────────┘ │
-│ footnote hint                                   │
-└─────────────────────────────────────────────────┘
-```
-
-## Theme rules
-
-- When lens `L` is active, set panel background to `themes[themeId][appearance].lenses[L].panel` where `appearance` is resolved `light` or `dark`.
-- Each of the four lenses MUST use a **different** panel color within a theme mode.
-- Slotted tokens are syntax-colored plain spans at rest — **no highlight box, no fixed width**.
-- On lens change: opacity cross-fade inside a clipped morph shell, optional per-token gradient sheen, block glass sweeps the full panel.
-- Expose six themes: tropical, earth, earthenware, patina, fruits, desert.
-- Host attribute `appearance="auto|light|dark"` selects light/dark chrome + syntax independently of pedagogical theme id.
-
-## Interaction
-
-### Desktop (pointer fine)
-
-- `mouseenter` / `focus` on tab → preview lens (update code + panel color + meta).
-- `mouseleave` toolbar → revert preview to committed lens.
-- `click` tab → commit lens.
-- Animate a **glassmorphism pill** behind tabs: `backdrop-filter: blur(12px)`, semi-transparent white/tint, slides with `cubic-bezier(0.16, 1, 0.3, 1)` over ~320ms (`glassSlideMs`).
-
-### Mobile (pointer coarse)
-
-- **Tap lens tabs** to switch lenses (`touch.preview: "tabs"`). Do not bind swipe to the code panel — keep code selectable for copy/paste.
-- Larger tab hit targets (`tabMinHeightPx` from spec).
-- Hint text: "Tap lens tabs to switch — code is selectable".
-
-Optional legacy mode: `touch.preview: "swipe"` enables horizontal swipe on the code area (not recommended when copy matters).
-
-## Code line layout (normative)
-
-Each source line is a **flex row** (`.el-line`):
-
-- `display: flex; flex-direction: row; flex-wrap: nowrap; align-items: baseline`
-- `white-space: pre; line-height: inherit` (match monospace `line-height`, typically ~1.6)
-- Direct children (`span` tokens) MUST NOT shrink: `flex-shrink: 0`
-
-Plain (non-slotted) tokens: single `<span class="el-token-kind-{kind}">` with text.
-
-## Slotted token morph (required)
-
-Applies to tokens with a `slot` key whose text **varies** across lenses.
-
-### At rest
-
-- Element: `<span class="el-slot el-token-kind-{kind}">`
-- CSS: `display: inline-block; width: auto; vertical-align: baseline; line-height: inherit`
-- **MUST NOT** use diff highlight boxes, borders, or fixed pixel width by default.
-- Optional **box** mode: `slot-highlight="box"` or `slotHighlight="box"` adds rounded pill via `::before` (`--el-diff-bg`, `--el-diff-border`, padding/radius from `ui.json5`).
-
-### On lens change (when incoming text ≠ previous)
-
-1. **Morph shell:** `<span class="el-slot is-morphing">` with **same** `display: inline-block` (no display flip at rest vs morph).
-2. **Width pin:** set `style.width` to measured **incoming** text width in px. Measure using a hidden probe attached to the code panel with the live monospace font — **never** measure inside the clipped morph shell (that yields ~0–4px and breaks layout).
-3. **Do not pin height.** Line height comes from flex baseline alignment + in-flow incoming layer.
-4. **Cross-fade layers:**
-   - `.el-slot-in` — incoming text, **in document flow** (`white-space: pre`)
-   - `.el-slot-out` — outgoing text, `position: absolute; left: 0; top: 0`, same line-height
-   - Animate opacity: out `fadeMs` ease-out; in `fadeMs` ease-in after `fadeDelayMs`
-5. **No CSS width transition** — width jumps to final incoming size immediately (no animated width morph).
-6. **Per-token sheen:** `::after` on `.el-slot.is-morphing` — soft-light gradient sweep for `glassBlockPassMs`, easing `widthEasing`.
-7. **Settle:** after `fadeMs + fadeDelayMs + buffer`, remove morph shell, clear width, replace with plain `.el-slot` text node.
-
-### Anti-patterns (do NOT implement)
-
-| Wrong | Why |
-|-------|-----|
-| `display: inline` at rest → `inline-block` only while morphing | Causes line-height jumps |
-| `inline-grid` stack for in/out text | Broke width/height metrics in reference |
-| Pinning measured **height** on morph shell | Regressed vertical spacing (reverted in 0.3.11) |
-| Measuring width inside `overflow: hidden` shell | Clips probe → invisible text |
-| Bordered `.el-diff` boxes around slots | Removed — use plain syntax-colored spans |
-| Animated meta/description height on lens switch | Not shipped — subtitle/description update instantly |
-
-Non-slotted tokens: swap text instantly, syntax color by `kind`.
-
-### Block glass overlay (when blur compositing is available)
-
-On any platform that supports blur (CSS `backdrop-filter`, native Material/blur APIs, `BackdropFilter`, etc.), simultaneously render a **single block-wide glass layer** over the code panel (not per-token). **Probe at runtime** — use cross-fade only when blur is unavailable. See [glass-lens-capabilities.md](./glass-lens-capabilities.md).
-
-- One overlay (`.el-code-glass`) covers the full code panel during lens switches.
-- Three diagonal gradient sheens sweep in opposing directions; a brief `backdrop-filter` blur pass runs in parallel.
-- Duration: `glassBlockPassMs` (520ms default). **No line stagger** — the entire panel animates as one layer.
-- `mix-blend-mode: soft-light` and `pointer-events: none` keep syntax colors readable and text selectable underneath.
-- Runs in parallel with slotted cross-fade and per-token sheen.
-- Honor `prefers-reduced-motion`: hide block glass and per-token sheen.
-
-## Syntax colors
-
-Map token `kind` to theme `syntax.{kind}` (light) or `syntaxDark.{kind}` (dark) hex values.
-
-Kinds: keyword, type, identifier, string, comment, punctuation, number, builtin, macro, operator.
-
-## API surface (web reference)
-
-```js
-import "@code-lens/css";
-import { createCodeLens, registerCodeLens } from "@code-lens/vanilla";
-registerCodeLens();
-const el = createCodeLens({ document, themes, ui, appearance: "auto" }, "earth");
-host.appendChild(el);
-```
-
-```html
-<code-lens theme="earth" appearance="auto"></code-lens>
-```
-
-Other frameworks: wrap the same state machine — `committedLensIndex`, `previewLensIndex`, `themeId`, `appearance`, morph map keyed by `line:token`.
-
-## State machine
-
-```
-displayIndex = previewIndex ?? committedIndex
-onTabHover(i): previewIndex = i; update meta + code
-onToolbarLeave(): previewIndex = null
-onTabClick(i): committedIndex = i; previewIndex = null
-onSwipe(delta): if |delta| > threshold, previewIndex ± 1  // legacy touch.preview: swipe only
-onTouchEnd(): committedIndex = displayIndex; previewIndex = null
-```
-
-On lens index change: rebuild code DOM, preserve morph state per slot key, trigger block glass once per lens change (not first paint).
-
-## Accessibility
-
-- `role="tablist"` / `role="tab"` / `aria-selected`
-- Support keyboard tab focus on lens buttons
-- Respect `prefers-reduced-motion`: skip cross-fade transitions, block glass, and per-token sheen
-
-## Reference implementation
-
-- `@code-lens/core` — parsing, themes, glass capability probe
-- `@code-lens/vanilla` — `<code-lens>` custom element (`packages/vanilla/src/code-lens.ts`, `code-lens.css`)
-- `@code-lens/solid` — Solid adapter (demo)
-- Live demo: GitHub Pages `/demo` (port 5174 locally)
-
-## Acceptance checklist
-
-- [ ] Four lenses switch with aligned tokens
-- [ ] Variable slots highlighted (plain spans, syntax-colored)
-- [ ] Panel background changes per lens
-- [ ] Six themes selectable
-- [ ] Hover preview + click commit on desktop
-- [ ] Tap lens tabs on touch (code panel stays selectable)
-- [ ] `appearance="auto|light|dark"` tints chrome + syntax (`themes.json5` v2)
-- [ ] Glass pill tracks active/hovered tab
-- [ ] Code lines use flex baseline alignment; slotted morph does not increase line height
-- [ ] Slotted tokens cross-fade with width pinned to incoming text; block glass sweep on lens change
-- [ ] Loads JSON5 spec without hardcoding example text
diff --git a/docs/antora.yml b/docs/antora.yml
new file mode 100644
index 0000000..bfa87f7
--- /dev/null
+++ b/docs/antora.yml
@@ -0,0 +1,6 @@
+name: code-lens
+title: code-lens
+version: ~
+start_page: ROOT:index.adoc
+nav:
+  - modules/ROOT/nav.adoc
diff --git a/docs/ecosystem.md b/docs/ecosystem.md
deleted file mode 100644
index 195d747..0000000
--- a/docs/ecosystem.md
+++ /dev/null
@@ -1,143 +0,0 @@
-# Delivery model
-
-Two views of the same thing — start with the one that matches how you build apps.
-
-## What you install (app developer)
-
-You always get a **component** (or a custom element for plain HTML). You never hand-wire lens logic yourself.
-
-| Your stack | Install | Use |
-|------------|---------|-----|
-| **Solid** | `@code-lens/solid` | `<CodeLens … />` |
-| **React** | `@code-lens/react` | `<CodeLens … />` |
-| **Next.js** | `@code-lens/next` | `import { CodeLens } from "@code-lens/next"` (client) |
-| **Preact** | `@code-lens/preact` | `<CodeLens … />` |
-| **Vue 3** | `@code-lens/vue` | `<CodeLens … />` |
-| **Svelte** | `@code-lens/svelte` | `<div use:codeLens={config} />` |
-| **Angular** | `@code-lens/angular` | `<code-lens-host … />` |
-| **Lit** | `@code-lens/lit` | `<code-lens-lit …>` |
-| **Leptos / Yew / Dioxus / Sycamore / Dominator / Seed** | `code-lens-*` crate + `@code-lens/wasm-bridge` | `<CodeLens config_json=… />` or framework view |
-| **Jane Street Bonsai_web** | `implementations/bonsai` | `Code_lens_mount.mount ~host ~config_json` |
-| **D libwasm (browser)** | `code-lens-d` (`code_lens.libwasm`) | `attachScript(configJson)` via JS interop |
-| **dlangui (desktop)** | `code-lens-d` (`code_lens.dlangui`) | Companion **webview** panel — native widgets cannot host DOM |
-| **No framework** | `@code-lens/vanilla` | `<code-lens>` |
-| **Any** | `@code-lens/css` | Styles (once per app) |
-
-```tsx
-// Solid — shipped today
-import { CodeLens } from "@code-lens/solid";
-import "@code-lens/css";
-
-<CodeLens document={doc} themes={themes} ui={ui} themeId="earth" appearance="auto" />
-```
-
-```tsx
-// React / Next.js — same API (package planned; pattern identical)
-"use client";
-import { CodeLens } from "@code-lens/react";
-import "@code-lens/css";
-
-export function Example() {
-  return <CodeLens document={doc} themes={themes} ui={ui} themeId="earth" />;
-}
-```
-
-That **is** the product in a React or Solid app — not a raw web component you manage yourself. The framework package is the delivery mechanism.
-
----
-
-## What we maintain (one engine)
-
-We do **not** rewrite lens switching six times. Framework packages are **official components** whose implementation mounts one shared runtime:
-
-```
-┌─────────────────────────────────────────────────┐
-│  @code-lens/react   @code-lens/solid   …        │  ← what you import
-│       CodeLens / CodeLens / …                   │
-└────────────────────┬────────────────────────────┘
-                     │ props → configure()
-┌────────────────────▼────────────────────────────┐
-│  @code-lens/vanilla  (<code-lens>)              │  ← one behavior engine
-│  @code-lens/core     (spec, themes, probe)      │
-└────────────────────┬────────────────────────────┘
-                     │ renders DOM + applies
-┌────────────────────▼────────────────────────────┐
-│  @code-lens/css  or  @code-lens/tailwind        │  ← presentation skin
-└─────────────────────────────────────────────────┘
-```
-
-**User-facing:** “React component” / “Solid component”  
-**Internal:** custom element + CSS — same pattern as many design systems that wrap a lower layer.
-
-This is **not** like Uiverse’s “React export” (a one-off syntax rewrite of a static snippet). It’s a real component with props, types, and lifecycle — the engine just lives in one place.
-
----
-
-## CSS vs Tailwind vs JS (orthogonal)
-
-These are **not** “Solid vs React editions.” They stack:
-
-| Piece | Package | You need it when… |
-|-------|---------|-------------------|
-| **Spec** | `spec/*.json5` | Always (data) |
-| **CSS skin** | `@code-lens/css` | Default styling (modern CSS) |
-| **Tailwind skin** | `@code-lens/tailwind` | You want utilities instead of `.el-*` CSS (planned) |
-| **Behavior** | `@code-lens/vanilla` + `@code-lens/core` | Always for interactivity — usually pulled in **by** your framework package |
-
-CSS/Tailwind alone cannot switch lenses. JS is required for behavior; the framework package bundles that path for you.
-
----
-
-## Plain HTML / embed anywhere
-
-When there is no framework:
-
-```html
-<script type="module">
-  import { registerCodeLens, createCodeLens } from "@code-lens/vanilla";
-  import "@code-lens/css";
-  registerCodeLens();
-  document.body.appendChild(createCodeLens({ … }));
-</script>
-```
-
-Or `<code-lens theme="earth">` after `registerCodeLens()`.
-
-Editors (VS Code webview), Electron, and Tauri use this same runtime unchanged.
-
----
-
-## Next.js specifically
-
-- Put `<CodeLens />` in a **`"use client"`** module (custom elements and DOM measurement don’t run on the server).
-- Import `@code-lens/css` once (global CSS or in the client component).
-- Props and types come from `@code-lens/react` — same as Solid.
-
-No App Router–specific edition; it’s the React component package.
-
----
-
-## Comparison to shadcn / solid-ui
-
-| | shadcn / solid-ui | code-lens |
-|--|-------------------|-----------|
-| Unit | Button, Card, … in **your** repo | `<CodeLens />` from **npm** |
-| Styling | Tailwind utilities | `@code-lens/css` or Tailwind skin |
-| Framework | Per-framework copy | Per-framework **package** wrapping one engine |
-| Logic | In the component source | In `@code-lens/vanilla` (shared) |
-
-Your demo page uses **solid-ui for site chrome** (header, cards, table) and **`@code-lens/solid` for the lens block**. Different products.
-
----
-
-## Quick chooser
-
-| You want… | Do this |
-|-----------|---------|
-| Solid app | `pnpm add @code-lens/solid @code-lens/css` → `<CodeLens />` |
-| React / Next app | `@code-lens/react` + `@code-lens/css` → `<CodeLens />` (client) |
-| Vue / Svelte app | `@code-lens/vue` / `@code-lens/svelte` when published |
-| Static HTML / CMS | `@code-lens/vanilla` + `@code-lens/css` |
-| Tailwind-only styling | Keep framework component; swap CSS import when `@code-lens/tailwind` ships |
-
-See [implementations/REGISTRY.md](../implementations/REGISTRY.md) for ship status per package.
diff --git a/docs/editor-integrations.md b/docs/editor-integrations.md
deleted file mode 100644
index 7d3c5fe..0000000
--- a/docs/editor-integrations.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# Editor integrations — feasibility
-
-Can VS Code and Zed do **code-lens** (pedagogical lens switching on real source code)? **Partially yes**, with different ceilings.
-
-## The core problem in editors
-
-Static examples in [code-lens](https://github.com/dev-centr/code-lens) ship pre-aligned token data. **Real code** has no `slot` keys — you must infer which identifiers play which role, then generate four naming variants (didactic, schematic, contextual, role-labeled).
-
-That second step is where **AI or LSP + heuristics** enter. The portable spec still applies once you have aligned variants.
-
-## VS Code — feasible (phased)
-
-| Capability | API | Feasibility |
-|------------|-----|-------------|
-| Lens tab bar + preview | `WebviewPanel` + `@code-lens/vanilla` | **High** — reuse web component in sidebar or panel |
-| Highlight “variable” tokens | `TextEditorDecorationType` | **High** — background/border on ranges |
-| Slotted cross-fade / glass sweep | DOM in webview only | **In panel: high.** Inline in Monaco: **low** — Monaco has no per-token morph; use decorations + optional ghost text |
-| Swap identifier text in buffer | `WorkspaceEdit` / transient virtual doc | **Medium** — apply edits to a **preview document** or ghost buffer, not silently mutating saved file |
-| Infer roles from semantics | LSP `DocumentSymbol`, Tree-sitter, or **AI** | **Medium–high** — AI best for role-labeled/didactic naming |
-| Hover lens switch | `HoverProvider` + commands | **High** |
-| Keybinding cycle lenses | Commands | **High** |
-
-### Recommended VS Code architecture
-
-```
-Selection / document
-    → Role extractor (Tree-sitter + LSP symbols, optional AI)
-    → Lens generator (AI or template) → JSON5-shaped lens document
-    → @code-lens/core validate
-    → Present via:
-        (A) Webview panel — full glass lens + morph (best fidelity)
-        (B) Editor decorations — diff-token highlights on real buffer
-        (C) Optional VirtualDocument — show alternate lens text read-only
-```
-
-**AI generation prompt shape:** Given snippet + language + optional surrounding context, return four aligned variants with `slot` on tokens that change (same schema as `spec/examples/*.json5`).
-
-Monaco **cannot** replicate the exact DOM glass-lens sweep on inline tokens without heavy custom rendering (e.g. `ViewZone` + HTML, fragile). **Use the webview for the full experience**; use **decorations** in the editor for “which tokens matter.”
-
-See [extensions/vscode/README.md](../extensions/vscode/README.md).
-
-## Zed — limited today, path via LSP
-
-| Capability | Zed support | Feasibility |
-|------------|-------------|-------------|
-| Extension manifest | `extension.toml` | **High** |
-| Custom web UI in editor | No first-class webview like VS Code | **Low** |
-| Buffer decorations / inlays | Evolving; inlay hints, some extension APIs | **Medium** — check current Zed version |
-| Lens preview UI | Embedded browser / panel extensions immature | **Low for inline morph** |
-| LSP server | **Full** — Zed is LSP-native | **High** |
-
-### Recommended Zed architecture
-
-Ship a **code-lens LSP** (or extend an existing one) that:
-
-1. Accepts `textDocument/didOpen` / range requests.
-2. Runs role extraction + AI lens generation server-side.
-3. Returns **inlay hints** (role labels), **diagnostic-style tags**, or **code actions** to open an external preview (browser / VS Code panel).
-
-A native Zed UI matching the web glass-lens animation likely requires **upstream editor features** (custom element overlays on text). Until then, Zed users get **semantic role hints + external preview**, not pixel-identical morph.
-
-See [extensions/zed/README.md](../extensions/zed/README.md).
-
-## Shared: AI lens generation
-
-Proposed module (editor-agnostic):
-
-```
-Input:  { language, source, selectionRange?, projectContext? }
-Output: LensBlockDocument (JSON5) — four lenses, slotted tokens
-```
-
-- **Without AI:** user manually tags slots (CodeLens / command on selection).
-- **With AI:** call configured provider (OpenAI, Anthropic, local Ollama); validate with `@code-lens/core`.
-- Cache by content hash in workspace storage.
-
-Privacy: default to **local / user-approved** AI; never send full repo without consent.
-
-## DevCentr roadmap
-
-IDE integrations are tracked on DevCentr as part of **developer UX / literate tooling**:
-
-- [DevCentr Todo & Roadmap — code-lens IDE](https://docs.devcentr.org/DevCentr/latest/todo-roadmap.html)
-- Upstream spec: [github.com/dev-centr/code-lens](https://github.com/dev-centr/code-lens)
-
-## Summary
-
-| Editor | Full web-parity lens UI | Role inference on real code | Practical v1 |
-|--------|-------------------------|----------------------------|--------------|
-| **VS Code** | Yes (webview panel) | Yes (AI + LSP) | Panel + decorations + AI generate |
-| **Zed** | No (today) | Yes (via LSP) | LSP inlays + open preview in browser |
-
-Both editors can participate in the **ecosystem**; neither needs to duplicate the spec — load `spec/` and `@code-lens/core`.
diff --git a/docs/glass-lens-capabilities.md b/docs/glass-lens-capabilities.md
deleted file mode 100644
index 05befc0..0000000
--- a/docs/glass-lens-capabilities.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# Glass lens capabilities
-
-The **glass lens** effect is two related animations:
-
-1. **Tab pill** — glassmorphism indicator sliding behind the active lens tab.
-2. **Block glass sweep** — diagonal gradient sheens and a brief blur pass over the entire code panel during lens switches.
-
-These are **not tied to a fixed list of frameworks**. Implement them on **any runtime that supports blur compositing**; otherwise use the documented fallback.
-
-## Capability tiers
-
-| Tier | When to use | Effect |
-|------|-------------|--------|
-| **full** | `backdrop-filter` / `-webkit-backdrop-filter` works | Tab pill + block glass sweep (normative in `@code-lens/vanilla`) |
-| **webview** | App embeds a DOM surface | Ship `@code-lens/vanilla` unchanged — Electron, Tauri, WebView2, Qt WebEngine, WebKitGTK |
-| **native** | Platform blur API, no DOM | Reproduce block sweep with layered gradients + blur on the code viewport (SwiftUI Material, Compose `blur`, Flutter `BackdropFilter`, RN blur module) |
-| **fallback** | No blur compositing | Keep slotted cross-fade + width pin; omit block glass overlay |
-| **none** | Editor / hint-only integrations | Role labels without inline morph |
-
-Canonical registry rows and expected tiers: [`spec/implementations.json5`](../spec/implementations.json5).
-
-## Runtime probing (DOM)
-
-`@code-lens/core` exports helpers:
-
-```ts
-import { shouldUseDomGlassLens, supportsDomGlassLens } from "@code-lens/core";
-
-if (shouldUseDomGlassLens()) {
-  // show .el-code-glass block overlay + .el-glass tab pill
-} else {
-  // morph + cross-fade only
-}
-```
-
-`@code-lens/vanilla` applies this automatically via the `el-glass-disabled` host class.
-
-Also honor `prefers-reduced-motion: reduce` (CSS and `prefersReducedMotion()`).
-
-## Native ports (guidance)
-
-When porting outside the DOM, map spec timings from `spec/ui.json5`:
-
-| Spec field | Use |
-|------------|-----|
-| `glassSlideMs` | Tab pill slide duration |
-| `glassBlockPassMs` | Block glass sweep duration |
-| `glassBlurPx` | Blur radius for native APIs (peak of blur pass) |
-
-Implement the block sweep on **every platform where blur is available** — do not skip native mobile/desktop targets because the reference is web-only.
-
-## Web framework adapters
-
-React, Vue, Svelte, Angular, Preact, Lit, and Solid should **embed** `<code-lens>` from `@code-lens/vanilla` (adapter layer). Only ship a separate port if embedding is impossible (e.g. SSR constraints).
-
-See [ecosystem.md](./ecosystem.md).
-
-## Contributing
-
-1. Add a row to `spec/implementations.json5`.
-2. Mirror the row in [`implementations/REGISTRY.md`](../implementations/REGISTRY.md).
-3. Set `glassLens` to the tier you **probe or implement**, not a wish list — update when the port lands.
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
new file mode 100644
index 0000000..2bee861
--- /dev/null
+++ b/docs/modules/ROOT/nav.adoc
@@ -0,0 +1,7 @@
+* xref:index.adoc[Introduction]
+* xref:ecosystem.adoc[Delivery model]
+* xref:specification.adoc[Specification]
+* xref:ai-reproduction-spec.adoc[AI reproduction spec]
+* xref:glass-lens-capabilities.adoc[Glass lens capabilities]
+* xref:editor-integrations.adoc[Editor integrations]
+* xref:changelog.adoc[Changelog]
diff --git a/docs/modules/ROOT/pages/ai-reproduction-spec.adoc b/docs/modules/ROOT/pages/ai-reproduction-spec.adoc
new file mode 100644
index 0000000..a92cebd
--- /dev/null
+++ b/docs/modules/ROOT/pages/ai-reproduction-spec.adoc
@@ -0,0 +1,196 @@
+= AI / LLM Reproduction Spec — code-lens
+
+
+Use this document to implement *code-lens* in any UI framework or toolkit. Follow normative MUST/SHOULD language.
+
+*Reference commit behavior:* slotted morph layout as shipped in `@code-lens/vanilla` ≥ 0.3.9 (restored in 0.3.11) — flex baseline lines, `inline-block` slots at rest and morph, width pin to measured incoming text only, opacity cross-fade, block glass sweep.
+
+== Product definition
+
+Build a component that renders *one aligned multi-line code example* in *four pedagogical lenses*:
+
+1. *didactic* — names are the lesson (`bad_field`)
+2. *schematic* — abstract placeholders (`T`, `value`)
+3. *contextual* — production-shaped names (`WriterHelpers`)
+4. *role* — structural roles (`namespace_member`)
+
+Syntax tokens are identical across lenses. Only slotted tokens (identifiers, strings, comments with a shared `slot` key) differ.
+
+== Data loading
+
+Load three JSON5 files from the repository `spec/` directory:
+
+* Example document (e.g. `spec/examples/zig-namespace.json5`)
+* `spec/themes.json5` (version *2* — light/dark per theme + `syntaxDark`)
+* `spec/ui.json5`
+
+Parse with JSON5. Validate: equal line counts, equal token counts per line, `version: 1`.
+
+Compute variable slots: any `slot` whose `text` differs across lenses.
+
+== Visual structure
+
+[source,none]
+----
+┌─ toolbar ─────────────────────────────────────┐
+│ [glass pill]  Lens  [Didactic][Schematic]…  zig │
+├─ body (background = theme.lenses[active].panel) ─┤
+│ subtitle + description (updates instantly)      │
+│ ┌─ code surface (chrome.codeSurface) ─────────┐ │
+│ │ one flex row per line (baseline-aligned)     │ │
+│ │ slotted tokens = plain spans + morph sheen   │ │
+│ └─────────────────────────────────────────────┘ │
+│ footnote hint                                   │
+└─────────────────────────────────────────────────┘
+----
+
+== Theme rules
+
+* When lens `L` is active, set panel background to `themes[themeId][appearance].lenses[L].panel` where `appearance` is resolved `light` or `dark`.
+* Each of the four lenses MUST use a *different* panel color within a theme mode.
+* Slotted tokens are syntax-colored plain spans at rest — *no highlight box, no fixed width*.
+* On lens change: opacity cross-fade inside a clipped morph shell, optional per-token gradient sheen, block glass sweeps the full panel.
+* Expose six themes: tropical, earth, earthenware, patina, fruits, desert.
+* Host attribute `appearance="auto|light|dark"` selects light/dark chrome + syntax independently of pedagogical theme id.
+
+== Interaction
+
+=== Desktop (pointer fine)
+
+* `mouseenter` / `focus` on tab → preview lens (update code + panel color + meta).
+* `mouseleave` toolbar → revert preview to committed lens.
+* `click` tab → commit lens.
+* Animate a *glassmorphism pill* behind tabs: `backdrop-filter: blur(12px)`, semi-transparent white/tint, slides with `cubic-bezier(0.16, 1, 0.3, 1)` over ~320ms (`glassSlideMs`).
+
+=== Mobile (pointer coarse)
+
+* *Tap lens tabs* to switch lenses (`touch.preview: "tabs"`). Do not bind swipe to the code panel — keep code selectable for copy/paste.
+* Larger tab hit targets (`tabMinHeightPx` from spec).
+* Hint text: "Tap lens tabs to switch — code is selectable".
+
+Optional legacy mode: `touch.preview: "swipe"` enables horizontal swipe on the code area (not recommended when copy matters).
+
+== Code line layout (normative)
+
+Each source line is a *flex row* (`.el-line`):
+
+* `display: flex; flex-direction: row; flex-wrap: nowrap; align-items: baseline`
+* `white-space: pre; line-height: inherit` (match monospace `line-height`, typically ~1.6)
+* Direct children (`span` tokens) MUST NOT shrink: `flex-shrink: 0`
+
+Plain (non-slotted) tokens: single `<span class="el-token-kind-{kind}">` with text.
+
+== Slotted token morph (required)
+
+Applies to tokens with a `slot` key whose text *varies* across lenses.
+
+=== At rest
+
+* Element: `<span class="el-slot el-token-kind-{kind}">`
+* CSS: `display: inline-block; width: auto; vertical-align: baseline; line-height: inherit`
+* *MUST NOT* use diff highlight boxes, borders, or fixed pixel width by default.
+* Optional *box* mode: `slot-highlight="box"` or `slotHighlight="box"` adds rounded pill via `::before` (`--el-diff-bg`, `--el-diff-border`, padding/radius from `ui.json5`).
+
+=== On lens change (when incoming text ≠ previous)
+
+1. *Morph shell:* `<span class="el-slot is-morphing">` with *same* `display: inline-block` (no display flip at rest vs morph).
+2. *Width pin:* set `style.width` to measured *incoming* text width in px. Measure using a hidden probe attached to the code panel with the live monospace font — *never* measure inside the clipped morph shell (that yields ~0–4px and breaks layout).
+3. *Do not pin height.* Line height comes from flex baseline alignment + in-flow incoming layer.
+4. *Cross-fade layers:*
+   - `.el-slot-in` — incoming text, *in document flow* (`white-space: pre`)
+   - `.el-slot-out` — outgoing text, `position: absolute; left: 0; top: 0`, same line-height
+   - Animate opacity: out `fadeMs` ease-out; in `fadeMs` ease-in after `fadeDelayMs`
+5. *No CSS width transition* — width jumps to final incoming size immediately (no animated width morph).
+6. *Per-token sheen:* `::after` on `.el-slot.is-morphing` — soft-light gradient sweep for `glassBlockPassMs`, easing `widthEasing`.
+7. *Settle:* after `fadeMs + fadeDelayMs + buffer`, remove morph shell, clear width, replace with plain `.el-slot` text node.
+
+=== Anti-patterns (do NOT implement)
+
+[cols="1,1",options="header"]
+|===
+| Wrong | Why
+| `display: inline` at rest → `inline-block` only while morphing | Causes line-height jumps
+| `inline-grid` stack for in/out text | Broke width/height metrics in reference
+| Pinning measured *height* on morph shell | Regressed vertical spacing (reverted in 0.3.11)
+| Measuring width inside `overflow: hidden` shell | Clips probe → invisible text
+| Bordered `.el-diff` boxes around slots | Removed — use plain syntax-colored spans
+| Animated meta/description height on lens switch | Not shipped — subtitle/description update instantly
+|===
+
+Non-slotted tokens: swap text instantly, syntax color by `kind`.
+
+=== Block glass overlay (when blur compositing is available)
+
+On any platform that supports blur (CSS `backdrop-filter`, native Material/blur APIs, `BackdropFilter`, etc.), simultaneously render a *single block-wide glass layer* over the code panel (not per-token). *Probe at runtime* — use cross-fade only when blur is unavailable. See xref:glass-lens-capabilities.adoc[glass-lens-capabilities.md].
+
+* One overlay (`.el-code-glass`) covers the full code panel during lens switches.
+* Three diagonal gradient sheens sweep in opposing directions; a brief `backdrop-filter` blur pass runs in parallel.
+* Duration: `glassBlockPassMs` (520ms default). *No line stagger* — the entire panel animates as one layer.
+* `mix-blend-mode: soft-light` and `pointer-events: none` keep syntax colors readable and text selectable underneath.
+* Runs in parallel with slotted cross-fade and per-token sheen.
+* Honor `prefers-reduced-motion`: hide block glass and per-token sheen.
+
+== Syntax colors
+
+Map token `kind` to theme `syntax.{kind}` (light) or `syntaxDark.{kind}` (dark) hex values.
+
+Kinds: keyword, type, identifier, string, comment, punctuation, number, builtin, macro, operator.
+
+== API surface (web reference)
+
+[source,js]
+----
+import "@code-lens/css";
+import { createCodeLens, registerCodeLens } from "@code-lens/vanilla";
+registerCodeLens();
+const el = createCodeLens({ document, themes, ui, appearance: "auto" }, "earth");
+host.appendChild(el);
+----
+
+[source,html]
+----
+<code-lens theme="earth" appearance="auto"></code-lens>
+----
+
+Other frameworks: wrap the same state machine — `committedLensIndex`, `previewLensIndex`, `themeId`, `appearance`, morph map keyed by `line:token`.
+
+== State machine
+
+[source,none]
+----
+displayIndex = previewIndex ?? committedIndex
+onTabHover(i): previewIndex = i; update meta + code
+onToolbarLeave(): previewIndex = null
+onTabClick(i): committedIndex = i; previewIndex = null
+onSwipe(delta): if |delta| > threshold, previewIndex ± 1  // legacy touch.preview: swipe only
+onTouchEnd(): committedIndex = displayIndex; previewIndex = null
+----
+
+On lens index change: rebuild code DOM, preserve morph state per slot key, trigger block glass once per lens change (not first paint).
+
+== Accessibility
+
+* `role="tablist"` / `role="tab"` / `aria-selected`
+* Support keyboard tab focus on lens buttons
+* Respect `prefers-reduced-motion`: skip cross-fade transitions, block glass, and per-token sheen
+
+== Reference implementation
+
+* `@code-lens/core` — parsing, themes, glass capability probe
+* `@code-lens/vanilla` — `<code-lens>` custom element (`packages/vanilla/src/code-lens.ts`, `code-lens.css`)
+* `@code-lens/solid` — Solid adapter (demo)
+* Live demo: GitHub Pages `/demo` (port 5174 locally)
+
+== Acceptance checklist
+
+* [ ] Four lenses switch with aligned tokens
+* [ ] Variable slots highlighted (plain spans, syntax-colored)
+* [ ] Panel background changes per lens
+* [ ] Six themes selectable
+* [ ] Hover preview + click commit on desktop
+* [ ] Tap lens tabs on touch (code panel stays selectable)
+* [ ] `appearance="auto|light|dark"` tints chrome + syntax (`themes.json5` v2)
+* [ ] Glass pill tracks active/hovered tab
+* [ ] Code lines use flex baseline alignment; slotted morph does not increase line height
+* [ ] Slotted tokens cross-fade with width pinned to incoming text; block glass sweep on lens change
+* [ ] Loads JSON5 spec without hardcoding example text
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/changelog-details/2026-05-28-v0.1.0.adoc b/docs/modules/ROOT/pages/changelog-details/2026-05-28-v0.1.0.adoc
new file mode 100644
index 0000000..cf11137
--- /dev/null
+++ b/docs/modules/ROOT/pages/changelog-details/2026-05-28-v0.1.0.adoc
@@ -0,0 +1,14 @@
+= v0.1.0 — Initial release
+:navtitle: v0.1.0
+:page-date: 2026-05-28
+
+== Added
+
+* Portable JSON5 spec (`spec/`) for examples, themes, and UI behavior.
+* `@code-lens/core` — parse, validate, variable slot detection, theme resolution.
+* `@code-lens/vanilla` — `<code-lens>` with hover preview, glass tab indicator, swipe, morphing diff tokens.
+* Six color schemes with distinct panel color per lens.
+* Demo site (Vite) for GitHub Pages.
+* xref:specification.adoc[Specification], xref:ai-reproduction-spec.adoc[AI reproduction spec], and implementation registry.
+
+Back to xref:changelog.adoc[Changelog index].
diff --git a/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.2.x.adoc b/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.2.x.adoc
new file mode 100644
index 0000000..d78fdaa
--- /dev/null
+++ b/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.2.x.adoc
@@ -0,0 +1,74 @@
+= v0.2.0–v0.2.9 — Delivery model and demo rebuild
+:navtitle: v0.2.x releases
+:page-date: 2026-05-29
+
+== v0.2.9
+
+=== Added
+
+* link:ecosystem.adoc[Delivery model] — CSS skin, Tailwind skin (planned), runtime, adapters.
+* `@code-lens/css` — stylesheet package.
+
+=== Changed
+
+* Registry simplified; `spec/implementations.json5` adds `delivery` layer per row.
+
+== v0.2.8
+
+=== Changed
+
+* Mobile uses lens tabs only; dark appearance glass/tab contrast; `@code-lens/solid` shipped.
+
+== v0.2.7
+
+=== Changed
+
+* Block-wide glass overlay replaces per-token pill sweep; text selection restored except during swipe.
+
+== v0.2.6
+
+=== Added
+
+* Component `appearance="auto|light|dark"` with `themes.json5` v2 light/dark palettes.
+
+== v0.2.5
+
+=== Added
+
+* Demo color scheme toggle with system autodetect.
+
+== v0.2.4
+
+=== Fixed
+
+* Diff token measurement probe; glass lens `backdrop-filter` detection.
+
+== v0.2.3
+
+=== Changed
+
+* GitHub Pages demo rebuilt with SolidJS + solid-ui.
+
+== v0.2.2
+
+=== Added
+
+* `spec/implementations.json5`, glass lens capabilities doc, `@code-lens/solid`, planned package scaffolds.
+
+== v0.2.1
+
+=== Added
+
+* xref:editor-integrations.adoc[Editor integration docs]; VS Code and Zed extension scaffolds.
+
+== v0.2.0
+
+=== Changed
+
+* Renamed project to *code-lens* (`@code-lens/*` packages).
+
+=== Added
+
+* Glass lens sweep over diff tokens during morph.
+
+Back to xref:changelog.adoc[Changelog index].
diff --git a/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.12.adoc b/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.12.adoc
new file mode 100644
index 0000000..d00f358
--- /dev/null
+++ b/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.12.adoc
@@ -0,0 +1,10 @@
+= v0.3.12 — Documentation alignment
+:navtitle: v0.3.12
+:page-date: 2026-05-29
+
+== Changed
+
+* *Docs* — align `ai-reproduction-spec` and `specification` with shipped slotted morph (flex baseline lines, inline-block slots, width-only pin, opacity cross-fade, block glass).
+  Document anti-patterns and note that meta copy updates instantly.
+
+Back to xref:changelog.adoc[Changelog index].
diff --git a/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.13.adoc b/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.13.adoc
new file mode 100644
index 0000000..c65f03f
--- /dev/null
+++ b/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.13.adoc
@@ -0,0 +1,11 @@
+= v0.3.13 — Slot highlight modes
+:navtitle: v0.3.13
+:page-date: 2026-05-29
+
+== Added
+
+* *Slot highlight modes* — `slotHighlight="plain"|"box"` / `slot-highlight="box"` for rounded pills on changeable tokens; optional `@code-lens/css/slots-box.css` for global box styling.
+* Demo *Plain / Box* toggle with persisted preference.
+* README badges; GitHub repo description, homepage, and topics.
+
+Back to xref:changelog.adoc[Changelog index].
diff --git a/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.x.adoc b/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.x.adoc
new file mode 100644
index 0000000..7e8912f
--- /dev/null
+++ b/docs/modules/ROOT/pages/changelog-details/2026-05-29-v0.3.x.adoc
@@ -0,0 +1,79 @@
+= v0.3.1–v0.3.11 — Morph fixes and adapters
+:navtitle: v0.3.x patch releases
+:page-date: 2026-05-29
+
+== v0.3.11
+
+=== Fixed
+
+* *Restore slotted morph layout* — revert height-lock experiment; back to flex baseline lines, inline-block slots, width-only pin.
+
+== v0.3.10
+
+=== Fixed
+
+* *Slotted token line height during morph* — slots stay `display: inline` at rest; morph box uses measured width and height.
+
+== v0.3.9
+
+=== Fixed
+
+* *Vertical spacing during slotted morph* — slotted tokens stay `inline-block` at rest and morph; code lines use flex `align-items: baseline`.
+
+== v0.3.8
+
+=== Fixed
+
+* *Slotted morph width* — pin morph shell to measured incoming text width.
+
+== v0.3.7
+
+=== Fixed
+
+* *Slotted token width during morph* — stack width follows incoming text.
+
+== v0.3.6
+
+=== Changed
+
+* *Slotted tokens* — removed diff highlight boxes and width morph; plain inline spans at rest with cross-fade sheen.
+
+== v0.3.5
+
+=== Fixed
+
+* *Plain token vertical shift during morph* — morph layers over in-flow sizing strut.
+
+== v0.3.4
+
+=== Fixed
+
+* *Line height during lens morph* — inner clip locked to `1lh` with stacked cross-fade layers.
+* *GitHub Pages CI* — build `@code-lens/css` before the demo.
+
+== v0.3.3
+
+=== Fixed
+
+* *Slotted token alignment* — diff highlights use `::before` overlay; fixed pixel widths only during width morph.
+
+== v0.3.2
+
+=== Fixed
+
+* *Component dark mode* — appearance/theme changes sync before `configure()` and call `refreshAppearance()`.
+* Solid/React adapters split config updates from appearance patches.
+
+== v0.3.1
+
+=== Added
+
+* *Rust UI adapters:* `code-lens-sycamore`, `code-lens-dominator`, `code-lens-seed`.
+* *D adapters:* `implementations/d` — `code_lens.libwasm` and `code_lens.dlangui`.
+* *Jane Street Bonsai:* moved to `implementations/bonsai/`.
+
+=== Removed
+
+* `@code-lens/bonsai` (NCAC TypeScript framework).
+
+Back to xref:changelog.adoc[Changelog index].
diff --git a/docs/modules/ROOT/pages/changelog.adoc b/docs/modules/ROOT/pages/changelog.adoc
new file mode 100644
index 0000000..075cc4c
--- /dev/null
+++ b/docs/modules/ROOT/pages/changelog.adoc
@@ -0,0 +1,45 @@
+= Changelog
+:navtitle: Changelog
+:description: Release history for code-lens and its documentation.
+
+This changelog records functional changes to code-lens packages, the demo site, and published documentation.
+Entries are in reverse chronological order.
+Detailed release notes link from each version summary below.
+
+== Unreleased
+
+* Repository transferred from `AMDphreak/code-lens` to link:https://github.com/dev-centr/code-lens[dev-centr/code-lens].
+  Live demo: link:https://dev-centr.github.io/code-lens/[dev-centr.github.io/code-lens].
+* **Docs** — Antora component under `docs/` for the Dev-Centr docs portal; AsciiDoc pages migrated from flat Markdown.
+
+== 2026-05-29 — v0.3.13
+
+* **Slot highlight modes** — `slotHighlight="plain"|"box"` for rounded pills on changeable tokens.
+* Demo Plain / Box toggle with persisted preference.
+* README badges; GitHub repo metadata.
+
+xref:changelog-details/2026-05-29-v0.3.13.adoc[Detailed changelog]
+
+== 2026-05-29 — v0.3.12
+
+* **Docs** — align AI reproduction spec and specification with shipped slotted morph layout.
+
+xref:changelog-details/2026-05-29-v0.3.12.adoc[Detailed changelog]
+
+== 2026-05-29 — v0.3.0 through v0.3.11
+
+Morph layout fixes, appearance/dark-mode sync, slotted token alignment, and framework adapter shipping.
+
+xref:changelog-details/2026-05-29-v0.3.x.adoc[Detailed changelog — v0.3.1–v0.3.11]
+
+== 2026-05-29 — v0.2.x
+
+Delivery model docs, component appearance, glass block overlay, Solid demo rebuild, editor integration scaffolds, implementation registry.
+
+xref:changelog-details/2026-05-29-v0.2.x.adoc[Detailed changelog — v0.2.0–v0.2.9]
+
+== 2026-05-28 — v0.1.0
+
+Initial portable JSON5 spec, `@code-lens/core`, `@code-lens/vanilla`, demo site, and specification docs.
+
+xref:changelog-details/2026-05-28-v0.1.0.adoc[Detailed changelog]
diff --git a/docs/modules/ROOT/pages/ecosystem.adoc b/docs/modules/ROOT/pages/ecosystem.adoc
new file mode 100644
index 0000000..b83e484
--- /dev/null
+++ b/docs/modules/ROOT/pages/ecosystem.adoc
@@ -0,0 +1,156 @@
+= Delivery model
+
+
+Two views of the same thing — start with the one that matches how you build apps.
+
+== What you install (app developer)
+
+You always get a *component* (or a custom element for plain HTML). You never hand-wire lens logic yourself.
+
+[cols="1,1,1",options="header"]
+|===
+| Your stack | Install | Use
+| *Solid* | `@code-lens/solid` | `<CodeLens … />`
+| *React* | `@code-lens/react` | `<CodeLens … />`
+| *Next.js* | `@code-lens/next` | `import { CodeLens } from "@code-lens/next"` (client)
+| *Preact* | `@code-lens/preact` | `<CodeLens … />`
+| *Vue 3* | `@code-lens/vue` | `<CodeLens … />`
+| *Svelte* | `@code-lens/svelte` | `<div use:codeLens={config} />`
+| *Angular* | `@code-lens/angular` | `<code-lens-host … />`
+| *Lit* | `@code-lens/lit` | `<code-lens-lit …>`
+| *Leptos / Yew / Dioxus / Sycamore / Dominator / Seed* | `code-lens-*` crate + `@code-lens/wasm-bridge` | `<CodeLens config_json=… />` or framework view
+| *Jane Street Bonsai_web* | `implementations/bonsai` | `Code_lens_mount.mount ~host ~config_json`
+| *D libwasm (browser)* | `code-lens-d` (`code_lens.libwasm`) | `attachScript(configJson)` via JS interop
+| *dlangui (desktop)* | `code-lens-d` (`code_lens.dlangui`) | Companion *webview* panel — native widgets cannot host DOM
+| *No framework* | `@code-lens/vanilla` | `<code-lens>`
+| *Any* | `@code-lens/css` | Styles (once per app)
+|===
+
+[source,tsx]
+----
+// Solid — shipped today
+import { CodeLens } from "@code-lens/solid";
+import "@code-lens/css";
+
+<CodeLens document={doc} themes={themes} ui={ui} themeId="earth" appearance="auto" />
+----
+
+[source,tsx]
+----
+// React / Next.js — same API (package planned; pattern identical)
+"use client";
+import { CodeLens } from "@code-lens/react";
+import "@code-lens/css";
+
+export function Example() {
+  return <CodeLens document={doc} themes={themes} ui={ui} themeId="earth" />;
+}
+----
+
+That *is* the product in a React or Solid app — not a raw web component you manage yourself. The framework package is the delivery mechanism.
+
+'''
+
+== What we maintain (one engine)
+
+We do *not* rewrite lens switching six times. Framework packages are *official components* whose implementation mounts one shared runtime:
+
+[source,none]
+----
+┌─────────────────────────────────────────────────┐
+│  @code-lens/react   @code-lens/solid   …        │  ← what you import
+│       CodeLens / CodeLens / …                   │
+└────────────────────┬────────────────────────────┘
+                     │ props → configure()
+┌────────────────────▼────────────────────────────┐
+│  @code-lens/vanilla  (<code-lens>)              │  ← one behavior engine
+│  @code-lens/core     (spec, themes, probe)      │
+└────────────────────┬────────────────────────────┘
+                     │ renders DOM + applies
+┌────────────────────▼────────────────────────────┐
+│  @code-lens/css  or  @code-lens/tailwind        │  ← presentation skin
+└─────────────────────────────────────────────────┘
+----
+
+*User-facing:* “React component” / “Solid component”  
+*Internal:* custom element + CSS — same pattern as many design systems that wrap a lower layer.
+
+This is *not* like Uiverse’s “React export” (a one-off syntax rewrite of a static snippet). It’s a real component with props, types, and lifecycle — the engine just lives in one place.
+
+'''
+
+== CSS vs Tailwind vs JS (orthogonal)
+
+These are *not* “Solid vs React editions.” They stack:
+
+[cols="1,1,1",options="header"]
+|===
+| Piece | Package | You need it when…
+| *Spec* | `spec/*.json5` | Always (data)
+| *CSS skin* | `@code-lens/css` | Default styling (modern CSS)
+| *Tailwind skin* | `@code-lens/tailwind` | You want utilities instead of `.el-*` CSS (planned)
+| *Behavior* | `@code-lens/vanilla` + `@code-lens/core` | Always for interactivity — usually pulled in *by* your framework package
+|===
+
+CSS/Tailwind alone cannot switch lenses. JS is required for behavior; the framework package bundles that path for you.
+
+'''
+
+== Plain HTML / embed anywhere
+
+When there is no framework:
+
+[source,html]
+----
+<script type="module">
+  import { registerCodeLens, createCodeLens } from "@code-lens/vanilla";
+  import "@code-lens/css";
+  registerCodeLens();
+  document.body.appendChild(createCodeLens({ … }));
+</script>
+----
+
+Or `<code-lens theme="earth">` after `registerCodeLens()`.
+
+Editors (VS Code webview), Electron, and Tauri use this same runtime unchanged.
+
+'''
+
+== Next.js specifically
+
+* Put `<CodeLens />` in a *`"use client"`* module (custom elements and DOM measurement don’t run on the server).
+* Import `@code-lens/css` once (global CSS or in the client component).
+* Props and types come from `@code-lens/react` — same as Solid.
+
+No App Router–specific edition; it’s the React component package.
+
+'''
+
+== Comparison to shadcn / solid-ui
+
+[cols="1,1,1",options="header"]
+|===
+|  | shadcn / solid-ui | code-lens
+| Unit | Button, Card, … in *your* repo | `<CodeLens />` from *npm*
+| Styling | Tailwind utilities | `@code-lens/css` or Tailwind skin
+| Framework | Per-framework copy | Per-framework *package* wrapping one engine
+| Logic | In the component source | In `@code-lens/vanilla` (shared)
+|===
+
+Your demo page uses *solid-ui for site chrome* (header, cards, table) and *`@code-lens/solid` for the lens block*. Different products.
+
+'''
+
+== Quick chooser
+
+[cols="1,1",options="header"]
+|===
+| You want… | Do this
+| Solid app | `pnpm add @code-lens/solid @code-lens/css` → `<CodeLens />`
+| React / Next app | `@code-lens/react` + `@code-lens/css` → `<CodeLens />` (client)
+| Vue / Svelte app | `@code-lens/vue` / `@code-lens/svelte` when published
+| Static HTML / CMS | `@code-lens/vanilla` + `@code-lens/css`
+| Tailwind-only styling | Keep framework component; swap CSS import when `@code-lens/tailwind` ships
+|===
+
+See link:https://github.com/dev-centr/code-lens/blob/main/implementations/REGISTRY.md[implementations/REGISTRY.md] for ship status per package.
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/editor-integrations.adoc b/docs/modules/ROOT/pages/editor-integrations.adoc
new file mode 100644
index 0000000..8f7690a
--- /dev/null
+++ b/docs/modules/ROOT/pages/editor-integrations.adoc
@@ -0,0 +1,102 @@
+= Editor integrations — feasibility
+
+
+Can VS Code and Zed do *code-lens* (pedagogical lens switching on real source code)? *Partially yes*, with different ceilings.
+
+== The core problem in editors
+
+Static examples in link:https://github.com/dev-centr/code-lens[code-lens] ship pre-aligned token data. *Real code* has no `slot` keys — you must infer which identifiers play which role, then generate four naming variants (didactic, schematic, contextual, role-labeled).
+
+That second step is where *AI or LSP + heuristics* enter. The portable spec still applies once you have aligned variants.
+
+== VS Code — feasible (phased)
+
+[cols="1,1,1",options="header"]
+|===
+| Capability | API | Feasibility
+| Lens tab bar + preview | `WebviewPanel` + `@code-lens/vanilla` | *High* — reuse web component in sidebar or panel
+| Highlight “variable” tokens | `TextEditorDecorationType` | *High* — background/border on ranges
+| Slotted cross-fade / glass sweep | DOM in webview only | *In panel: high.* Inline in Monaco: *low* — Monaco has no per-token morph; use decorations + optional ghost text
+| Swap identifier text in buffer | `WorkspaceEdit` / transient virtual doc | *Medium* — apply edits to a *preview document* or ghost buffer, not silently mutating saved file
+| Infer roles from semantics | LSP `DocumentSymbol`, Tree-sitter, or *AI* | *Medium–high* — AI best for role-labeled/didactic naming
+| Hover lens switch | `HoverProvider` + commands | *High*
+| Keybinding cycle lenses | Commands | *High*
+|===
+
+=== Recommended VS Code architecture
+
+[source,none]
+----
+Selection / document
+    → Role extractor (Tree-sitter + LSP symbols, optional AI)
+    → Lens generator (AI or template) → JSON5-shaped lens document
+    → @code-lens/core validate
+    → Present via:
+        (A) Webview panel — full glass lens + morph (best fidelity)
+        (B) Editor decorations — diff-token highlights on real buffer
+        (C) Optional VirtualDocument — show alternate lens text read-only
+----
+
+*AI generation prompt shape:* Given snippet + language + optional surrounding context, return four aligned variants with `slot` on tokens that change (same schema as `spec/examples/*.json5`).
+
+Monaco *cannot* replicate the exact DOM glass-lens sweep on inline tokens without heavy custom rendering (e.g. `ViewZone` + HTML, fragile). *Use the webview for the full experience*; use *decorations* in the editor for “which tokens matter.”
+
+See link:https://github.com/dev-centr/code-lens/blob/main/extensions/vscode/README.md[extensions/vscode/README.md].
+
+== Zed — limited today, path via LSP
+
+[cols="1,1,1",options="header"]
+|===
+| Capability | Zed support | Feasibility
+| Extension manifest | `extension.toml` | *High*
+| Custom web UI in editor | No first-class webview like VS Code | *Low*
+| Buffer decorations / inlays | Evolving; inlay hints, some extension APIs | *Medium* — check current Zed version
+| Lens preview UI | Embedded browser / panel extensions immature | *Low for inline morph*
+| LSP server | *Full* — Zed is LSP-native | *High*
+|===
+
+=== Recommended Zed architecture
+
+Ship a *code-lens LSP* (or extend an existing one) that:
+
+1. Accepts `textDocument/didOpen` / range requests.
+2. Runs role extraction + AI lens generation server-side.
+3. Returns *inlay hints* (role labels), *diagnostic-style tags*, or *code actions* to open an external preview (browser / VS Code panel).
+
+A native Zed UI matching the web glass-lens animation likely requires *upstream editor features* (custom element overlays on text). Until then, Zed users get *semantic role hints + external preview*, not pixel-identical morph.
+
+See link:https://github.com/dev-centr/code-lens/blob/main/extensions/zed/README.md[extensions/zed/README.md].
+
+== Shared: AI lens generation
+
+Proposed module (editor-agnostic):
+
+[source,none]
+----
+Input:  { language, source, selectionRange?, projectContext? }
+Output: LensBlockDocument (JSON5) — four lenses, slotted tokens
+----
+
+* *Without AI:* user manually tags slots (CodeLens / command on selection).
+* *With AI:* call configured provider (OpenAI, Anthropic, local Ollama); validate with `@code-lens/core`.
+* Cache by content hash in workspace storage.
+
+Privacy: default to *local / user-approved* AI; never send full repo without consent.
+
+== DevCentr roadmap
+
+IDE integrations are tracked on DevCentr as part of *developer UX / literate tooling*:
+
+* link:https://docs.devcentr.org/DevCentr/latest/todo-roadmap.html[DevCentr Todo & Roadmap — code-lens IDE]
+* Upstream spec: link:https://github.com/dev-centr/code-lens[github.com/dev-centr/code-lens]
+
+== Summary
+
+[cols="1,1,1,1",options="header"]
+|===
+| Editor | Full web-parity lens UI | Role inference on real code | Practical v1
+| *VS Code* | Yes (webview panel) | Yes (AI + LSP) | Panel + decorations + AI generate
+| *Zed* | No (today) | Yes (via LSP) | LSP inlays + open preview in browser
+|===
+
+Both editors can participate in the *ecosystem*; neither needs to duplicate the spec — load `spec/` and `@code-lens/core`.
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/glass-lens-capabilities.adoc b/docs/modules/ROOT/pages/glass-lens-capabilities.adoc
new file mode 100644
index 0000000..1b5209c
--- /dev/null
+++ b/docs/modules/ROOT/pages/glass-lens-capabilities.adoc
@@ -0,0 +1,68 @@
+= Glass lens capabilities
+
+
+The *glass lens* effect is two related animations:
+
+1. *Tab pill* — glassmorphism indicator sliding behind the active lens tab.
+2. *Block glass sweep* — diagonal gradient sheens and a brief blur pass over the entire code panel during lens switches.
+
+These are *not tied to a fixed list of frameworks*. Implement them on *any runtime that supports blur compositing*; otherwise use the documented fallback.
+
+== Capability tiers
+
+[cols="1,1,1",options="header"]
+|===
+| Tier | When to use | Effect
+| *full* | `backdrop-filter` / `-webkit-backdrop-filter` works | Tab pill + block glass sweep (normative in `@code-lens/vanilla`)
+| *webview* | App embeds a DOM surface | Ship `@code-lens/vanilla` unchanged — Electron, Tauri, WebView2, Qt WebEngine, WebKitGTK
+| *native* | Platform blur API, no DOM | Reproduce block sweep with layered gradients + blur on the code viewport (SwiftUI Material, Compose `blur`, Flutter `BackdropFilter`, RN blur module)
+| *fallback* | No blur compositing | Keep slotted cross-fade + width pin; omit block glass overlay
+| *none* | Editor / hint-only integrations | Role labels without inline morph
+|===
+
+Canonical registry rows and expected tiers: link:../spec/implementations.json5[`spec/implementations.json5`].
+
+== Runtime probing (DOM)
+
+`@code-lens/core` exports helpers:
+
+[source,ts]
+----
+import { shouldUseDomGlassLens, supportsDomGlassLens } from "@code-lens/core";
+
+if (shouldUseDomGlassLens()) {
+  // show .el-code-glass block overlay + .el-glass tab pill
+} else {
+  // morph + cross-fade only
+}
+----
+
+`@code-lens/vanilla` applies this automatically via the `el-glass-disabled` host class.
+
+Also honor `prefers-reduced-motion: reduce` (CSS and `prefersReducedMotion()`).
+
+== Native ports (guidance)
+
+When porting outside the DOM, map spec timings from `spec/ui.json5`:
+
+[cols="1,1",options="header"]
+|===
+| Spec field | Use
+| `glassSlideMs` | Tab pill slide duration
+| `glassBlockPassMs` | Block glass sweep duration
+| `glassBlurPx` | Blur radius for native APIs (peak of blur pass)
+|===
+
+Implement the block sweep on *every platform where blur is available* — do not skip native mobile/desktop targets because the reference is web-only.
+
+== Web framework adapters
+
+React, Vue, Svelte, Angular, Preact, Lit, and Solid should *embed* `<code-lens>` from `@code-lens/vanilla` (adapter layer). Only ship a separate port if embedding is impossible (e.g. SSR constraints).
+
+See xref:ecosystem.adoc[ecosystem.md].
+
+== Contributing
+
+1. Add a row to `spec/implementations.json5`.
+2. Mirror the row in link:https://github.com/dev-centr/code-lens/blob/main/implementations/REGISTRY.md[`implementations/REGISTRY.md`].
+3. Set `glassLens` to the tier you *probe or implement*, not a wish list — update when the port lands.
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
new file mode 100644
index 0000000..5d98d89
--- /dev/null
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -0,0 +1,65 @@
+= code-lens
+:navtitle: Introduction
+:description: One code snippet, multiple pedagogical lenses — portable JSON5 spec and web component with framework adapters.
+
+code-lens displays one aligned code example through multiple *pedagogical lenses*.
+Syntax and structure stay identical; only referential tokens change.
+Variable tokens cross-fade when switching lenses, with optional per-token sheen and a block-wide glass sweep over the code panel.
+
+== Live demo
+
+link:https://dev-centr.github.io/code-lens/[GitHub Pages demo] — SolidJS + `@code-lens/solid`.
+
+== Quick start
+
+[source,bash]
+----
+pnpm install
+pnpm dev    # SolidJS demo on port 5174
+----
+
+[source,javascript]
+----
+import "@code-lens/css";
+import { createCodeLens, registerCodeLens } from "@code-lens/vanilla";
+import { parseLensBlock, parseThemes, parseUi } from "@code-lens/core";
+
+registerCodeLens();
+const el = createCodeLens({
+  document: parseLensBlock(blockJson5),
+  themes: parseThemes(themesJson5),
+  ui: parseUi(uiJson5),
+}, "earth");
+document.body.appendChild(el);
+----
+
+[source,html]
+----
+<code-lens theme="earth" appearance="auto"></code-lens>
+----
+
+* `appearance`: `auto` | `light` | `dark` — independent of pedagogical color theme.
+* `slotHighlight`: `plain` | `box` — rounded highlight on changeable tokens (default `plain`).
+
+== Portable spec
+
+[cols="1,2",options="header"]
+[cols="1",options="header"]
+|===
+| ===
+| `spec/examples/*.json5` | Aligned token data per lens
+| `spec/themes.json5` | Color schemes (light/dark per theme)
+| `spec/ui.json5` | Interaction + animation
+| ===
+|===
+
+== Documentation map
+
+* xref:ecosystem.adoc[Delivery model] — what you install vs what we maintain
+* xref:specification.adoc[Specification] — normative behavior and spec files
+* xref:ai-reproduction-spec.adoc[AI reproduction spec] — porting detail for LLMs and native UI
+* xref:glass-lens-capabilities.adoc[Glass lens capabilities] — blur tiers and runtime probing
+* xref:editor-integrations.adoc[Editor integrations] — VS Code and Zed feasibility
+* xref:changelog.adoc[Changelog] — release history
+
+Source: link:https://github.com/dev-centr/code-lens[dev-centr/code-lens].
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/specification.adoc b/docs/modules/ROOT/pages/specification.adoc
new file mode 100644
index 0000000..9a6dcc6
--- /dev/null
+++ b/docs/modules/ROOT/pages/specification.adoc
@@ -0,0 +1,99 @@
+= code-lens Specification
+
+
+Version 0.3 — portable across web, desktop, and mobile implementations.
+
+== Overview
+
+*code-lens* displays one code example through multiple *pedagogical lenses*. Syntax and structure are identical across lenses; only referential tokens change. Variable tokens cross-fade when switching lenses, with optional per-token sheen and a block-wide glass sweep over the code panel.
+
+== Spec files
+
+[cols="1,1",options="header"]
+|===
+| File | Purpose
+| `spec/lens-block.schema.json5` | Schema for example documents
+| `spec/examples/*.json5` | Example content (aligned tokens per lens)
+| `spec/themes.json5` | Color schemes — each theme includes *light* and *dark* appearance modes (v2)
+| `spec/ui.json5` | Interaction model and animation constants
+| `spec/implementations.json5` | Implementation registry + glass lens tiers
+|===
+
+== Lens IDs (normative)
+
+[cols="1,1,1",options="header"]
+|===
+| ID | Label | Role
+| `didactic` | Didactic | Concept-labeled names
+| `schematic` | Schematic | Abstract placeholders
+| `contextual` | Contextual | Production-shaped names
+| `role` | Role-labeled | Structural role names
+|===
+
+== Appearance
+
+* Pedagogical *theme* (`earth`, `tropical`, …) sets lens panel tints and syntax palette.
+* *Appearance* (`auto` \| `light` \| `dark`) selects light or dark mode within that theme (`themes.json5` v2).
+* Web: `<code-lens appearance="auto" theme="earth">` or `CodeLensConfig.appearance`.
+
+== Meta copy
+
+Subtitle and description update *instantly* on lens preview/commit. There is no animated reflow of the concept paragraph in the reference web implementation.
+
+== Animation (`spec/ui.json5`)
+
+=== Code line layout
+
+* Each line: flex row, `align-items: baseline`, `white-space: pre`
+* Token spans: `flex-shrink: 0`
+
+=== Slotted token morph
+
+Variable slots (`slot` key with differing text across lenses):
+
+[cols="1,1",options="header"]
+|===
+| Phase | Behavior
+| At rest | `.el-slot` — `inline-block`, syntax-colored, no box, `width: auto`
+| Morph | `.el-slot.is-morphing` — same `inline-block`, `overflow: hidden`, width set to measured *incoming* text (px), no height pin
+| Layers | `.el-slot-in` (in flow) + `.el-slot-out` (absolute) opacity cross-fade (`fadeMs`, `fadeDelayMs`)
+| Sheen | `::after` gradient on morph shell, timed with `glassBlockPassMs`
+| Settle | Plain `.el-slot` text node, width cleared
+|===
+
+*Normative invariants* (see xref:ai-reproduction-spec.adoc[ai-reproduction-spec.md]):
+
+* No `display` flip between rest and morph
+* No `inline-grid` text stack
+* Measure token width via hidden probe on code panel, not inside clipped shell
+* No CSS width transition on morph shell (instant pin to final width)
+
+`widthMs` / `widthEasing` in `ui.json5` feed CSS variables; primary consumer is sheen easing (`--el-width-easing`). Diff padding/radius vars exist for tab fallback styling when glass is disabled.
+
+=== Block glass overlay (when supported)
+
+* Single overlay over the code panel when blur compositing works (not per token)
+* Pass duration: `glassBlockPassMs` (520ms)
+* Diagonal gradient sheens + brief backdrop blur; no line stagger
+* Runs *simultaneously* with slotted cross-fade
+* *Fallback:* cross-fade + sheen only — see xref:glass-lens-capabilities.adoc[glass-lens-capabilities.md]
+
+== Packages
+
+[source,none]
+----
+spec/               — JSON5 (portable data)
+@code-lens/css      — stylesheet (presentation)
+@code-lens/tailwind — utility skin (planned)
+@code-lens/core     — parse spec, themes, blur probe
+@code-lens/vanilla  — <code-lens> web component (runtime)
+@code-lens/solid    — Solid host (adapter — mounts vanilla CE)
+----
+
+Framework adapters *embed* the web component; they do not re-implement behavior. See xref:ecosystem.adoc[ecosystem.md].
+
+== Further reading
+
+* xref:ai-reproduction-spec.adoc[AI / LLM reproduction spec] — normative implementation detail for ports
+* xref:glass-lens-capabilities.adoc[Glass lens capabilities]
+* xref:editor-integrations.adoc[Editor integrations]
\ No newline at end of file
diff --git a/docs/specification.md b/docs/specification.md
deleted file mode 100644
index c59da6d..0000000
--- a/docs/specification.md
+++ /dev/null
@@ -1,91 +0,0 @@
-# code-lens Specification
-
-Version 0.3 — portable across web, desktop, and mobile implementations.
-
-## Overview
-
-**code-lens** displays one code example through multiple **pedagogical lenses**. Syntax and structure are identical across lenses; only referential tokens change. Variable tokens cross-fade when switching lenses, with optional per-token sheen and a block-wide glass sweep over the code panel.
-
-## Spec files
-
-| File | Purpose |
-|------|---------|
-| `spec/lens-block.schema.json5` | Schema for example documents |
-| `spec/examples/*.json5` | Example content (aligned tokens per lens) |
-| `spec/themes.json5` | Color schemes — each theme includes **light** and **dark** appearance modes (v2) |
-| `spec/ui.json5` | Interaction model and animation constants |
-| `spec/implementations.json5` | Implementation registry + glass lens tiers |
-
-## Lens IDs (normative)
-
-| ID | Label | Role |
-|----|-------|------|
-| `didactic` | Didactic | Concept-labeled names |
-| `schematic` | Schematic | Abstract placeholders |
-| `contextual` | Contextual | Production-shaped names |
-| `role` | Role-labeled | Structural role names |
-
-## Appearance
-
-- Pedagogical **theme** (`earth`, `tropical`, …) sets lens panel tints and syntax palette.
-- **Appearance** (`auto` \| `light` \| `dark`) selects light or dark mode within that theme (`themes.json5` v2).
-- Web: `<code-lens appearance="auto" theme="earth">` or `CodeLensConfig.appearance`.
-
-## Meta copy
-
-Subtitle and description update **instantly** on lens preview/commit. There is no animated reflow of the concept paragraph in the reference web implementation.
-
-## Animation (`spec/ui.json5`)
-
-### Code line layout
-
-- Each line: flex row, `align-items: baseline`, `white-space: pre`
-- Token spans: `flex-shrink: 0`
-
-### Slotted token morph
-
-Variable slots (`slot` key with differing text across lenses):
-
-| Phase | Behavior |
-|-------|----------|
-| At rest | `.el-slot` — `inline-block`, syntax-colored, no box, `width: auto` |
-| Morph | `.el-slot.is-morphing` — same `inline-block`, `overflow: hidden`, width set to measured **incoming** text (px), no height pin |
-| Layers | `.el-slot-in` (in flow) + `.el-slot-out` (absolute) opacity cross-fade (`fadeMs`, `fadeDelayMs`) |
-| Sheen | `::after` gradient on morph shell, timed with `glassBlockPassMs` |
-| Settle | Plain `.el-slot` text node, width cleared |
-
-**Normative invariants** (see [ai-reproduction-spec.md](./ai-reproduction-spec.md)):
-
-- No `display` flip between rest and morph
-- No `inline-grid` text stack
-- Measure token width via hidden probe on code panel, not inside clipped shell
-- No CSS width transition on morph shell (instant pin to final width)
-
-`widthMs` / `widthEasing` in `ui.json5` feed CSS variables; primary consumer is sheen easing (`--el-width-easing`). Diff padding/radius vars exist for tab fallback styling when glass is disabled.
-
-### Block glass overlay (when supported)
-
-- Single overlay over the code panel when blur compositing works (not per token)
-- Pass duration: `glassBlockPassMs` (520ms)
-- Diagonal gradient sheens + brief backdrop blur; no line stagger
-- Runs **simultaneously** with slotted cross-fade
-- **Fallback:** cross-fade + sheen only — see [glass-lens-capabilities.md](./glass-lens-capabilities.md)
-
-## Packages
-
-```
-spec/               — JSON5 (portable data)
-@code-lens/css      — stylesheet (presentation)
-@code-lens/tailwind — utility skin (planned)
-@code-lens/core     — parse spec, themes, blur probe
-@code-lens/vanilla  — <code-lens> web component (runtime)
-@code-lens/solid    — Solid host (adapter — mounts vanilla CE)
-```
-
-Framework adapters **embed** the web component; they do not re-implement behavior. See [ecosystem.md](./ecosystem.md).
-
-## Further reading
-
-- [AI / LLM reproduction spec](./ai-reproduction-spec.md) — normative implementation detail for ports
-- [Glass lens capabilities](./glass-lens-capabilities.md)
-- [Editor integrations](./editor-integrations.md)
diff --git a/extensions/vscode/README.md b/extensions/vscode/README.md
index c7cda89..1b187e1 100644
--- a/extensions/vscode/README.md
+++ b/extensions/vscode/README.md
@@ -35,7 +35,7 @@ Press F5 in VS Code (**Run Extension**) with this folder opened.
 
 ## Architecture
 
-See [docs/editor-integrations.md](../../docs/editor-integrations.md).
+See [Editor integrations](https://docs.devcentr.org/code-lens/editor-integrations.html).
 
 ## Roadmap
 
diff --git a/extensions/zed/README.md b/extensions/zed/README.md
index d62ca9d..236cde0 100644
--- a/extensions/zed/README.md
+++ b/extensions/zed/README.md
@@ -14,7 +14,7 @@ Zed does **not** currently offer a VS Code–style webview for embedding `@code-
 | Open external preview (`dev-centr.github.io/code-lens` or local static server) | Easy |
 | Native text overlays with morph animation | Blocked on editor APIs |
 
-See [docs/editor-integrations.md](../../docs/editor-integrations.md).
+See [Editor integrations](https://docs.devcentr.org/code-lens/editor-integrations.html).
 
 ## Recommended v1: code-lens LSP
 
diff --git a/implementations/REGISTRY.md b/implementations/REGISTRY.md
index e96c6ad..d8d6b70 100644
--- a/implementations/REGISTRY.md
+++ b/implementations/REGISTRY.md
@@ -1,6 +1,6 @@
 # Implementation Registry
 
-See [docs/ecosystem.md](../docs/ecosystem.md).
+See [Delivery model docs](https://docs.devcentr.org/code-lens/ecosystem.html).
 
 ## TypeScript / JS components
 
diff --git a/packages/core/src/capabilities.ts b/packages/core/src/capabilities.ts
index 55f8805..a7ac6a0 100644
--- a/packages/core/src/capabilities.ts
+++ b/packages/core/src/capabilities.ts
@@ -9,7 +9,7 @@ export type GlassLensTier =
 
 export type ImplementationStatus = "shipped" | "wip" | "planned";
 
-/** How this row fits the delivery stack — see docs/ecosystem.md */
+/** How this row fits the delivery stack — see docs.devcentr.org/code-lens/ecosystem.html */
 export type DeliveryLayer =
   | "spec"
   | "css"
diff --git a/packages/css/README.md b/packages/css/README.md
index 90fa072..ddc98cf 100644
--- a/packages/css/README.md
+++ b/packages/css/README.md
@@ -11,4 +11,4 @@ import { registerCodeLens, createCodeLens } from "@code-lens/vanilla";
 
 Same file as `@code-lens/vanilla/code-lens.css` — this package exists so apps can depend on **CSS only** when bundling or documenting the presentation layer separately.
 
-See [docs/ecosystem.md](../../docs/ecosystem.md).
+See [Delivery model docs](https://docs.devcentr.org/code-lens/ecosystem.html).
diff --git a/packages/react/README.md b/packages/react/README.md
index fd94bb5..26cfa1e 100644
--- a/packages/react/README.md
+++ b/packages/react/README.md
@@ -19,4 +19,4 @@ export function CodeLens(props: CodeLensProps) {
 }
 ```
 
-Copy the pattern from `@code-lens/solid`. See [docs/ecosystem.md](../../docs/ecosystem.md).
+Copy the pattern from `@code-lens/solid`. See [Delivery model docs](https://docs.devcentr.org/code-lens/ecosystem.html).
diff --git a/packages/solid/README.md b/packages/solid/README.md
index 49bddff..a3090e3 100644
--- a/packages/solid/README.md
+++ b/packages/solid/README.md
@@ -18,4 +18,4 @@ import { lensDocument, themes, ui } from "./spec";
 
 The GitHub Pages demo uses Solid + solid-ui for **page chrome** only; the lens block is still `@code-lens/vanilla` under the hood.
 
-React / Vue / Svelte: embed `@code-lens/vanilla` the same way — see [docs/ecosystem.md](../../docs/ecosystem.md).
+React / Vue / Svelte: embed `@code-lens/vanilla` the same way — see [Delivery model docs](https://docs.devcentr.org/code-lens/ecosystem.html).
diff --git a/packages/tailwind/README.md b/packages/tailwind/README.md
index c6b7401..1dbe886 100644
--- a/packages/tailwind/README.md
+++ b/packages/tailwind/README.md
@@ -21,4 +21,4 @@ import { registerCodeLens } from "@code-lens/vanilla";
 
 Works in Tailwind projects (including Solid + solid-ui demos). The lens block uses its own scoped `.el-*` classes; page chrome can stay Tailwind.
 
-See [docs/ecosystem.md](../../docs/ecosystem.md).
+See [Delivery model docs](https://docs.devcentr.org/code-lens/ecosystem.html).
diff --git a/spec/implementations.json5 b/spec/implementations.json5
index 7f1d9b7..2982204 100644
--- a/spec/implementations.json5
+++ b/spec/implementations.json5
@@ -1,4 +1,4 @@
-// Canonical implementation registry — see docs/ecosystem.md
+// Canonical implementation registry — see docs.devcentr.org/code-lens/ecosystem.html
 
 {
   glassLensTiers: {