@keenmate/web-components-devkit 1.0.0-rc01 → 1.0.0-rc03

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## [1.0.0-rc03] - 2026-11-01 [PUBLISHED]
+
+### Fixed
+
+- **Example pages no longer widen the page on a phone** — on screens ≤ 768 px a
+  `.reference-table` scrolls inside its card, a long `.controls` label (or `<code>` in it)
+  wraps and a `.controls` select is capped at the row, instead of overflowing. Besides the sideways scroll, an over-wide page made mobile
+  browsers grow the layout viewport (a 390 px phone reporting ~600 px), so pages that
+  demo device / breakpoint detection showed the wrong class.
+- **The scaffold's component CSS no longer sets `box-sizing` on the host page** — the
+  `*, *::before, *::after { box-sizing: inherit }` reset in `templates/new/src/css/base.css`
+  (also in the `--minimal` scaffold and the playground) reached the page through the light-DOM stylesheet, in a layer that beats
+  `@layer kmwc`, so every page control rendered content-box (the spotlight input overflowed, a
+  36 px input came out 38 px). It is scoped to `:host *` now; components scaffolded with an
+  earlier devkit should make the same one-line change. A unit test now rejects any universal or
+  bare-element selector in the scaffold CSS.
+
+### Added
+
+- **Form controls: one look for native inputs on every example page** — text fields, selects
+  and list boxes, textareas, checkboxes (incl. indeterminate), radios, switches
+  (`<input type="checkbox" role="switch">`), ranges, colour and file inputs and fieldsets are
+  styled without a class, modelled on pure-admin's forms: inputs, selects and buttons share
+  `--kmwc-control-height`, so a row of them lines up in any container (not only `.controls`);
+  the focus border and halo, placeholder, disabled tone, the checkbox size and the
+  `--base-icon-check` / `-indeterminate` tick read the `--base-*` contract. Rules are
+  zero-specificity (`:where()`); `kmwc-native` on an element or an ancestor keeps the
+  browser's own controls. Outline buttons are as tall as filled ones now (transparent border).
+  The playground's new `examples-forms.html` shows them all.
+- **Tables: every `<table>` on an example page is styled** — a header fill, row lines, hover
+  tint, caption and footer, as pure-admin's `.pa-table`. `.reference-table` looks as before;
+  new modifiers combine with it or a bare table: `.table-full`, `.table-bordered`,
+  `.table-striped`, `.table-compact` (tighter cells, and the inputs / selects / buttons in it
+  shrink with them via `--kmwc-control-height`), plus `tr.is-highlight` on any table and a
+  `.num` cell (right-aligned, tabular figures). Every table, not only `.reference-table`,
+  scrolls inside its card on a phone. Pages no longer need their own table CSS with fixed light
+  colours (core's `.rs-table`, which breaks in dark mode). New playground page
+  `examples-tables.html`.
+- **Spotlight: Ctrl/⌘+K chapter search across every example page** — matches a chapter whose
+  section code or heading text contains the query (`th7` finds `TH07`; uncoded `Summary` /
+  reference sections by title), grouped by page with the current page first; Enter jumps,
+  Ctrl/⌘+Enter opens a new tab. The Vite plugin builds the index (`virtual:kmwc-chapters`)
+  from every page's `<h2>`s; `kmwc.examples.isSpotlightEnabled: false` turns it off. It mirrors
+  web-commandpalette's markup, matching, keyboard map, open/close and CSS without depending on
+  it — `npm run check:spotlight-mirror` lists what changed there since the last alignment.
+  New page tokens `--kmwc-overlay-bg` and `--kmwc-focused-bg` / `-text-color` / `-outline`
+  read the same `--base-*` hooks as wcp, so both look alike under a theme.
+- **Short chapter links** — `#th07`, `#th7` or the slug of an uncoded heading scroll to that
+  chapter on arrival.
+- **`make dev` (and `kill-port`, `build-examples`, `preview-examples`) at the repo root** — the
+  standard targets, run against the playground; `make playground` is gone.
+- **`kmwc doctor` runs the rulebook's new `example-pages` suite** — every example `<h2>`
+  carries a permanent section code (`TH07 · Title`), a prefix belongs to one page, no code
+  is used twice. The generated CLAUDE.md block points at the rule. The convention was
+  already in the scaffold and the playground but written down nowhere, so sessions
+  building new pages didn't know it.
+
+### Known issues
+
+- **Opening the spotlight shifts the page sideways** on systems with classic scrollbars: the
+  mirrored core `lockBodyScroll()` only sets `overflow: hidden`, so the scrollbar disappears
+  (wcp has the same jump). pure-admin / pure-css avoid it with a `position: fixed` lock and
+  width compensation; the proposal to bring that into core is in web-commandpalette's CLAUDE.md.
+
+## [1.0.0-rc02] - 2026-10-31 [PUBLISHED]
+
+### Added
+
+- **`kmwc new --adopt`** for migrating a component that is already in the registry:
+  the same scaffold, with the entry's port block and prefix (or `--prefix` when the
+  entry has none), no npm-name check (the package may exist) and no registry edit.
+  Scaffold into a scratch `--dir`, then move the component's code into it — how
+  web-editor's one-package monorepo was flattened.
+
+- **`npm run check:contract`** — `base-contract-check` (from `@keenmate/base-css-variables`,
+  a devDependency) over the kit, the scaffold templates and the playground: every `--base-*`
+  read or set exists in the contract, input fallbacks equal its defaults, derived ones are its
+  formulas. Deliberate differences go in `contract-check.json` (the scaffolds' `inherit` font).
+
+### Fixed
+
+- **Kit and scaffolds read the 2.0 `--base-*` names.** `--base-accent-color*`,
+  `--base-text-color-on-accent` and `--base-input-color` were removed in base-css-variables
+  2.0.0, so a theme's primary never reached the example pages or a new component. Now
+  `--base-primary-color` / `-hover` / `-active`, `--base-primary-bg-subtle(-hover)`,
+  `--base-on-primary-text-color` and `--base-input-text-color`; the theming pages and docs set
+  `--base-primary-color`. Fallbacks are the contract's: example pages default to the blue-500
+  primary (was purple `#667eea`; the header gradient end now follows the accent), slate surfaces
+  (dark main `#1e293b`, page `#f8f9fa` / `#0f172a`) and the contract text, border, hover, shadow
+  and font values. The kit's status colours read `--base-<role>-text-color`; the danger button
+  fills with `--base-danger-color` and its text is `--base-on-danger-text-color`. The secondary
+  button and the index "new" badge compute their text from their own fill, so a light primary
+  no longer turns them black.
+- **`kmwc doctor` skipped every rulebook suite once the devkit came from npm.** The
+  rulebook was looked up at a fixed path from the devkit (`<devkit>/../../BlissFramework`),
+  which lands inside `node_modules` for an installed package. It is now the nearest
+  `BlissFramework/guidelines/web-components` above the component (then above the
+  devkit); `kmwc.rulebook.path` resolves against the component root.
+- **Fragment pages: a `<style>` or `<link>` inside a `<script>` stays put.** Shadow-DOM
+  styles and an SVG's own `<style>` written into a script were moved into `<head>`; they
+  are strings there, not page elements.
+
+### Migrated
+
+- **web-editor** — flattened from a one-package npm-workspaces monorepo; registry entry
+  now carries its prefix (`km`) and no longer says monorepo.
+- **pure-css** (library, 15200) and **base-css-variables** (library, 15300) added to the
+  registry.
+
+### Internal
+
+- **Root `Makefile`** for the devkit's own tasks: test, readme / contract checks, and
+  `publish` / `publish-rc` gated on `kmwc check-release`.
+
 ## [1.0.0-rc01] - 2026-10-12 [PUBLISHED]
 
 First release of `@keenmate/web-components-devkit`, plus the component catalogue.

package/README.md

@@ -19,15 +19,21 @@ them in the same shape: `@keenmate/web-components-devkit`.
 > positioning) lives in [`@keenmate/web-components-core`](../web-components-core).
 > Nothing here ships inside a component's bundle.
 
-## What's New in v1.0.0-rc01
+## What's New in v1.0.0-rc03
 
-- **Devkit — one shared toolchain for every Keenmate web component** — Each `web-*` repo used to carry its own copy of the example helpers, the shared stylesheet, the Vite/Playwright configs and the deploy files, and every session "fixed" its own copy until they drifted apart. `@keenmate/web-components-devkit` owns all of it now: a component describes itself once in `package.json#kmwc` (title, prefix, ports, accent colours, analytics, image) and `defineComponentConfig()`, `definePlaywrightConfig()` and the `kmwc` CLI read it from there. A shared concern is fixed once in the devkit and every component picks it up on the next install.
-- **Vite preset — dev, library and examples-site builds from one config** — `defineComponentConfig()` (Vite 7) runs the dev server on the repo's registry port with `strictPort`, builds the library (`es` + `umd`, `style.css` kept under its historical name, rolled-up `.d.ts`) and, with `--mode examples`, builds every root `*.html` into a static multi-page site in `dist-examples/` with relative asset URLs. The examples plugin injects the kit into each page and loads its stylesheet render-blocking, so pages don't flash unstyled on reload.
-- **Examples kit — one design system and set of page helpers instead of six forks** — The `@layer kmwc` stylesheet merges six diverged `examples-shared.css` copies; its `--kmwc-*` tokens read the rulebook's `--base-*` taxonomy with `light-dark()` fallbacks, so a theme-designer theme restyles the demo page together with the component. Every page gets a light / dark / auto theme switch (it sets `data-theme` on `<html>`, the signal components react to), a chapter nav and copy-link buttons that share one slug algorithm, a version badge with the build stamp, and build-only Plausible. `attachControlsPersistence()` and `renderExamplesIndex()` replace the per-repo controls store and the 150-line inline index page.
-- **Fragment pages — no more copied page boilerplate** — A page without `<html>` is a fragment: `<meta name="kmwc:title">` and friends drive the shared layout (head, entry script, header with back link, container), `<kmwc-include>` pulls parameterised partials (nesting, cycle detection), and `<kmwc-demo>` renders live markup plus a code block of exactly that markup, so a snippet can no longer drift from its demo. Full documents pass through untouched, so pages migrate one at a time.
-- **`kmwc` CLI — generate, check and gate instead of hand-edit** — `kmwc sync` writes the Dockerfile, nginx.conf, Makefile (repo targets in `Makefile.local`), .dockerignore and a managed CLAUDE.md block from templates. `kmwc doctor` runs the devkit checks, an `npm pack` contents check (no CLAUDE.md, tests or example pages in the package) and every BlissFramework rulebook `*.checks.sh` suite. `kmwc check-vars` replaces three diverged manifest scripts (declared or consumed mode), and `kmwc check-release` gates `make publish*` on the dist-tag ⇔ version rule.
-- **`kmwc new` — a rulebook-shaped component on the first commit** — The scaffold runs the rulebook intake (npm name free, CSS prefix 2–4 letters and not reserved, next free port block) and generates the Element / Logic / types / logger layers, the canonical eight-file CSS set with Strategy-B dark mode, a Custom Elements Manifest, README + `docs/`, CHANGELOG, `/publish`, fragment example pages and smoke + dark-mode e2e specs. It passes every rulebook suite as generated; `--minimal` gives an empty skeleton instead of the sample toggle.
-- **Catalogue and port registry — every component listed, no port collisions** — `components.json` registers every Keenmate repo with its CSS prefix and a 100-port block (dev = block, preview = +1, image = +10), numbered inside a range per kind (components 12100–14900, libraries 15000–, showcases 16000–, tests 17000–), so any number of repos run side by side. The README catalogue is generated from it, with a ✅ for each repo on the devkit; web-commandpalette is the first.
+- **Spotlight — Ctrl/⌘+K chapter search across every example page** — Example sites grew to dozens of chapters over several pages, and the per-page chapter nav only knew its own page. The Vite plugin now builds an index of every page's `<h2>`s (`virtual:kmwc-chapters`), coded and uncoded, and Ctrl/⌘+K opens a search that matches the section code or the heading text (`th7` finds `TH07`), grouped by page with the current one first. Enter jumps, Ctrl/⌘+Enter opens a new tab. It mirrors web-commandpalette's markup, matching, keyboard map and CSS without depending on it; `npm run check:spotlight-mirror` lists what changed there since the last alignment. Turn it off with `kmwc.examples.isSpotlightEnabled: false`.
+- **Form controls — one look for native inputs on every example page** — Pages styled their own selects and inputs, or got the browser default, so a select next to the kit's buttons came out shorter and in the platform's style (a `.controls` row was the only place the kit reached). Text fields, selects and list boxes, textareas, checkboxes, radios, `role="switch"` switches, ranges, colour and file inputs are now styled with no class, modelled on pure-admin's forms. Inputs, selects and buttons share `--kmwc-control-height`, so a mixed row lines up in any container. Focus, placeholder, disabled tone, checkbox size and the tick read the `--base-*` contract. The rules are zero-specificity, and `kmwc-native` opts an element out.
+- **Tables — every table styled, `.reference-table` plus modifiers** — Only `.reference-table` had a look; a bare table was unstyled and pages wrote their own table CSS with fixed light colours that break in dark mode. Any `<table>` now gets a header fill, row lines and a hover tint, and modifiers combine: `.table-full`, `.table-bordered`, `.table-striped`, and `.table-compact`, whose inputs and buttons shrink with the rows. Add `tr.is-highlight` and `.num` (tabular figures). Every wide table scrolls inside its card on a phone.
+- **Scaffold — component CSS no longer restyles the host page** — The `*, *::before, *::after { box-sizing: inherit }` reset in the `kmwc new` and `--minimal` templates also reached the page through the component's light-DOM stylesheet, in a layer that beats `@layer kmwc`, so page controls rendered content-box (a 36 px input came out 38 px). It is scoped to `:host *` now, and a unit test rejects any universal or bare-element selector in scaffold CSS. Components scaffolded on rc01/rc02 should make the same one-line change in `src/css/base.css`.
+- **Example pages — short chapter links, phones and the example-pages suite** — `#th07`, `#th7` or an uncoded heading's slug now scroll to that chapter on arrival. On a phone, example pages no longer grow wider than the screen, which made mobile browsers report a wrong viewport to pages that demo breakpoints. `kmwc doctor` runs the rulebook's new `example-pages` suite: every example `<h2>` carries a permanent section code.
+- **`make dev` at the devkit root** — the standard `dev` / `kill-port` / `build-examples` / `preview-examples` targets, run against the playground.
+
+## What's New in v1.0.0-rc02
+
+- **Theming — kit and scaffolds follow base-css-variables 2.0** — base-css-variables 2.0 dropped `--base-accent-color*`, `--base-text-color-on-accent` and `--base-input-color`, so a theme's primary colour silently stopped reaching the example pages and every newly scaffolded component. The `--kmwc-*` tokens in `src/examples/css/tokens.css` and the `templates/new*` `variables.css` now read `--base-primary-color` (with `-hover` / `-active` / `-bg-subtle`), `--base-on-primary-text-color` and `--base-input-text-color`, and the theming pages, docs and manifests set the new names. Standalone fallbacks are now the contract's own values, so a page looks the same with or without the contract loaded: a blue-500 primary instead of the old purple, slate surfaces, and on-colours computed from their fill. Re-run `kmwc new` output or diff your `variables.css` if you scaffolded on rc01.
+- **`npm run check:contract` — fallbacks can't drift from the contract** — `base-contract-check` from `@keenmate/base-css-variables` now runs over the kit, the scaffold templates and the playground. It fails when a `--base-*` read doesn't exist in the contract, when an input's fallback differs from the contract default, or when a derived token's fallback isn't the contract formula. Deliberate differences, such as the scaffolds inheriting the page font, are listed with a reason in `contract-check.json`. It's part of the gate before every kit or template change.
+- **`kmwc new --adopt` — migrate a component that's already registered** — Brings an existing repo onto the devkit with the same rulebook-shaped scaffold, using the registry entry's port block and CSS prefix, skipping the npm-name check (the package already exists) and leaving `components.json` untouched. Scaffold into a scratch `--dir` and move the component's code in. web-editor's one-package monorepo was flattened this way.
+- **`kmwc doctor` — rulebook suites run from an npm install** — With the devkit installed from npm instead of linked, doctor looked for the BlissFramework rulebook at a path relative to the devkit, which ended up inside `node_modules`, and silently skipped every suite. It now uses the nearest `BlissFramework/guidelines/web-components` above the component (then above the devkit), and `kmwc.rulebook.path` resolves against the component root.
 
 ## Catalogue
 
@@ -42,7 +48,7 @@ them in the same shape: `@keenmate/web-components-devkit`.
 | **web-commandpalette** | `@keenmate/web-commandpalette` | `cp` | 12400 | [repo](https://github.com/keenmate/web-commandpalette) · [examples](https://examples.web-commandpalette.keenmate.dev) | ✅ | Framework-agnostic command-palette web component — modes, multi-step commands, scoped + global search,… |
 | **web-dropzone** | `@keenmate/web-dropzone` | `dz` | 12500 | [repo](https://github.com/keenmate/web-dropzone) | — | Lightweight file dropzone web component with drag-drop, previews, validation, and multiple display modes. |
 | **web-grid** | `@keenmate/web-grid` | `wg` | 12600 | [repo](https://github.com/keenmate/web-grid) · [docs](https://web-grid.keenmate.com) · [showcase](https://web-grid.keenmate.com) | — | Framework-agnostic data grid web component with sorting, filtering, inline editing, and keyboard navigation |
-| **web-editor** | `@keenmate/web-editor` | — | 12700 | [examples](https://examples.web-editor.keenmate.dev) | — | KeenMate Web Editor monorepo — a framework-agnostic WYSIWYG / Markdown editor built on ProseMirror. |
+| **web-editor** | `@keenmate/web-editor` | `km` | 12700 | [examples](https://examples.web-editor.keenmate.dev) | ✅ | Keenmate Web Editor — a framework-agnostic WYSIWYG / Markdown editor built on ProseMirror. |
 | **web-switch** | `@keenmate/web-switch` | — | 12800 | [repo](https://github.com/keenmate/web-switch) | — | Framework-agnostic web component wrapper for @keenmate/svelte-switch. Works with React, Vue, Angular, or… |
 | **web-timepicker** | — | — | 12900 | — | — | Vanilla-JS prototypes (spiral / slider time pickers); no package yet. |
 | **web-wysiwyg** | — | — | 13000 | — | — | ProseMirror exploration; superseded by web-editor. |
@@ -53,6 +59,8 @@ them in the same shape: `@keenmate/web-components-devkit`.
 |---|---|---:|---|
 | **web-components-core** | `@keenmate/web-components-core` | 15000 | Runtime foundation: BlissElement, reactive input table, converters, logging, positioning, CEM preset. |
 | **web-components** | `@keenmate/web-components-devkit` | 15100 | This repo — dev/demo/build tooling (Vite preset, examples kit, kmwc CLI). |
+| **pure-css** | `@keenmate/pure-css` | 15200 | CSS framework mirroring the base-css-variables token contract (demo site + e2e on the dev port). |
+| **base-css-variables** | `@keenmate/base-css-variables` | 15300 | The shared --base-* token contract (base-variables.css) + base-contract-check; examples site + e2e on the dev port. |
 
 ### Showcases, docs & test harnesses
 
@@ -166,7 +174,8 @@ Every field is optional. Defaults are derived from the package.
     "checkMode": "declared"                      // or "consumed" (var() reads)
   },
   "rulebook": {
-    "path": "../../BlissFramework/guidelines/web-components", // default; env KMWC_RULEBOOK_PATH wins
+    "path": "../BlissFramework/guidelines/web-components", // relative to the component; default: the nearest
+                                                 // BlissFramework checkout above it. env KMWC_RULEBOOK_PATH wins
     "skippedChecks": []                          // e.g. ["responsive-overlay"]
   },
   "sync": { "skippedFiles": [] }                 // e.g. ["Makefile"] to opt a file out
@@ -257,10 +266,26 @@ doctor` lists the ones still repeating the head/header boilerplate.
   Re-theme a site with `kmwc.theme.accentColor`. The page vocabulary is
   unchanged from the old shared CSS — `.card`, `.example-section`, `.controls`,
   `.demo-area`, `.demo-card`, `.code-block`, `.note(.warning|.info|.success|.error)`,
-  `.grid`/`.card-grid`, `.reference-table`, `.log-panel`, `.pill`,
+  `.grid`/`.card-grid`, `.reference-table` (+ `.table-*` modifiers), `.log-panel`, `.pill`,
   `.status-dot`, `.control-group`, buttons (`.btn-secondary`, `.btn-outline`,
   `.btn-danger`) — while everything the kit **generates** is prefixed BEM
   (`kmwc-chapter-nav__item--active`, `kmwc-copy-link--copied`, …).
+- **Form controls** look the same on every page without a class: text fields,
+  selects and list boxes (`multiple` / `size`), textareas, checkboxes, radios,
+  switches (`<input type="checkbox" role="switch">`), ranges, colour and file
+  inputs, fieldsets — modelled on pure-admin's forms and read through the
+  `--base-input-*` / `--base-checkbox-*` / `--base-icon-check` contract. Inputs,
+  selects and buttons share `--kmwc-control-height`, so a row of them lines up
+  in any container, not only `.controls`. The rules are zero-specificity
+  (`:where()`); `kmwc-native` on an element or an ancestor keeps the browser's
+  own controls (a light-DOM component that draws its own inputs). The
+  playground's `examples-forms.html` shows them all.
+- **Tables:** any `<table>` gets a header fill, row lines and a hover tint;
+  `.reference-table` is the full-width, fully bordered API table. Modifiers
+  combine — `.table-full`, `.table-bordered`, `.table-striped`, `.table-compact`
+  (tighter cells; the controls in it shrink via `--kmwc-control-height`) — plus
+  `tr.is-highlight` and a `.num` cell (right-aligned, tabular figures). On a phone
+  a wide table scrolls inside its card. See the playground's `examples-tables.html`.
 - **Theme switch** (top right) cycles light → dark → auto and sets
   `data-theme` on `<html>` — the same signal components react to via
   `:host-context([data-theme])`, so every example page is a dark-mode smoke
@@ -268,6 +293,22 @@ doctor` lists the ones still repeating the head/header boilerplate.
 - **Chapter nav and copy-link** share one section/slug algorithm, so the
   jump-list hashes and copied links always match. Floating UI is bundled (no
   CDN). At the bottom of a short page, the last chapter gets highlighted.
+- **Spotlight (Ctrl/⌘+K)** searches every chapter of every example page: a
+  chapter matches when its section code or heading text contains the query
+  (`th7` finds `TH07`; uncoded `Summary` / reference sections are found by
+  title), results are grouped by page with the current page first, ↑↓ / PgUp
+  / PgDn / Home / End pick, Enter jumps, Ctrl/⌘+Enter opens a new tab. The
+  Vite plugin builds the index from every page's `<h2>`s (includes resolved)
+  as `virtual:kmwc-chapters`; the current page's chapters are read live, so
+  script-rendered sections count too. Off with
+  `kmwc.examples.isSpotlightEnabled: false` (a component that owns Ctrl+K
+  itself; a page handler calling `preventDefault()` also keeps the key). It
+  **mirrors** [web-commandpalette](https://github.com/keenmate/web-commandpalette)
+  — markup, matching, keyboard map, open/close, CSS — without depending on it;
+  see *Developing the devkit*.
+- **Short chapter links**: `examples-theming.html#th07` (or `#th7`, or the
+  slug of an uncoded heading, `#summary`) scrolls to that chapter on arrival
+  — the codes from the rulebook's `example-pages.md` work as URLs.
 - **Version badge**: any `[data-kmwc-version]` (or legacy `#version-badge`)
   shows `v1.2.3`, or `v1.2.3 (built …)` in a built site.
 - **Landing page**: `renderExamplesIndex({ pages })` renders the header, cards,
@@ -302,6 +343,7 @@ kmwc doctor [--json]          devkit checks + package contents + the rulebook's
 kmwc check-vars [--strict]    component-variables.manifest.json ⇔ CSS
 kmwc check-release --tag t    latest ⇔ release version, rc ⇔ -rcN, version not yet on npm
 kmwc new web-<name>           scaffold a component (--prefix, --title, --tag, --dir, --port, --minimal, --register)
+                              --adopt: scaffold an ALREADY registered component (its port/prefix) to migrate into
 kmwc readme [--check]         regenerate this README's catalogue (devkit repo only)
 ```
 
@@ -314,7 +356,7 @@ and the e2e suite before building and publishing.
 **`kmwc doctor` and the rulebook.** Doctor runs every suite in the rulebook
 (component-structure, naming-conventions, css-structure, theme-container,
 base-variables, color-scheme, readme-structure, custom-elements-manifest,
-responsive-overlay, publish-command) with `bash`, passing `kmwc.prefix`, and
+responsive-overlay, publish-command, example-pages) with `bash`, passing `kmwc.prefix`, and
 reports each `FAIL` as an error pointing at the matching `.checks.md` entry.
 When the rulebook isn't checked out (or there's no bash) the suites are
 skipped with a warning — the rulebook stays the single source of truth; the
@@ -366,6 +408,12 @@ command prints the reminder.
 
 `kmwc doctor` lists everything that's left, so run it after each step.
 
+**Repo in a different shape** (a one-package monorepo, a non-standard layout)?
+Don't teach the devkit the old shape: back the repo up, run `kmwc new web-<name>
+--adopt --dir <scratch>` (same files, with the registered port and prefix, no
+registry edits), and move the component's own code into that layout with
+`git mv`. web-editor was flattened this way.
+
 1. `npm i -D @keenmate/web-components-devkit vite@^7` (plus `@playwright/test`
    if the repo has e2e tests).
 2. Add `package.json#kmwc`. Take the port block (`ports.dev` = block,
@@ -404,8 +452,18 @@ npm install
 npm test                 # unit tests (config, registry, templates, sync, checks, intake, plugin, kit)
 npm run test:e2e         # playground: the kit + scaffold in a real browser, dev server AND built site
 npm run readme           # regenerate the catalogue
+npm run check:spotlight-mirror   # what changed in web-commandpalette since the spotlight was aligned
+make dev                 # the playground's dev server
 ```
 
+**The spotlight mirrors web-commandpalette.** `src/examples/spotlight.js`,
+`chapter-search.js` and `css/spotlight.css` keep wcp's structure block for
+block (devkit naming), each marked `mirrors <file> <function>`;
+[`scripts/spotlight-mirror.json`](scripts/spotlight-mirror.json) lists every
+pair and the wcp / core commit they're aligned to. A bug fixed in one gets
+ported to the other: run `npm run check:spotlight-mirror` (add `-- --diff`
+for the patches), port what applies, bump `alignedCommit`.
+
 [`playground/`](playground) is a real component scaffolded with `kmwc new` and
 linked to this checkout. It's the reference for "what a component looks like",
 the e2e target for every kit feature, and `npx kmwc doctor` inside it must