@keenmate/web-components-devkit 1.0.0-rc10 → 1.0.0-rc11

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [1.0.0-rc11] - 2026-11-06 [PUBLISHED]
+
+### Added
+
+- **Doctor understands monorepos: `kmwc.packages`.** Doctor assumed the repo root was the package.
+  In web-dropzone (npm workspaces: a private root holding the example site,
+  `packages/web-dropzone` the component, `packages/web-dropzone-core` a headless library) that gave
+  113 errors that said little: `npm pack` on the private root "leaked" 101 files npm never publishes,
+  six rulebook suites couldn't find a component at the root, the overlay suite scanned
+  `node_modules`, and the loader check silently skipped — while the component's real findings
+  (129 non-BEM classes, no Custom Elements Manifest setup …) never showed. `"packages": [{ "path",
+  "kind": "component" | "library" }]` lists what the repo publishes: doctor packs each package, runs
+  the rulebook suites for its kind inside it (`rulebook:<suite>@<path>`; publish-command and
+  example-pages stay repo-wide at the root), and checks the loader class per component package.
+  Doctor warns when npm workspaces aren't all listed, errors on a listed path without a
+  package.json, and never packs a private workspace root. Without `packages` a repo is one package
+  at its root, as before.
+- **Every example page gets the footer.** Only the index had one ("Created by Keenmate s.r.o. |
+  GitHub | web-components-devkit vX"); the other pages just ended. The kit now appends the same
+  line to every page but the index (`mountPageFooter()`, `.kmwc-page-footer`), inside the layout's
+  container. The index and the page footer render it from one function (`renderFooterLineHtml()`),
+  so they can't drift.
+
 ## [1.0.0-rc10] - 2026-11-05 [PUBLISHED]
 
 ### Added

package/README.md

@@ -19,6 +19,11 @@ 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-rc11
+
+- **Doctor — monorepos: `kmwc.packages` lists what the repo publishes** — Doctor used to assume the repo root was the package. In web-dropzone (npm workspaces: a private root that holds the example site, the component in `packages/web-dropzone`, a headless library in `packages/web-dropzone-core`) that produced 113 errors that said little. `npm pack` on the private root "leaked" 101 files npm never publishes, six rulebook suites found no component at the root, and the overlay suite scanned `node_modules`. Meanwhile the component's real findings never showed. Now `"packages": [{ "path", "kind": "component" | "library" }]` in `package.json#kmwc` lists the published packages. Doctor packs each one and runs the rulebook suites for its kind inside it (reported as `rulebook:<suite>@<path>`). The publish-command and example-pages suites stay repo-wide, and the loader check runs per component package. Doctor warns when npm workspaces aren't all listed, errors on a listed path without a `package.json`, and never packs a private workspace root. A repo without `packages` is still one package at its root.
+- **Examples kit — every example page ends with the footer** — Only the index page had the "Created by Keenmate s.r.o. | GitHub | web-components-devkit vX" footer; the other example pages just stopped. The kit now appends the same line to every page except the index (`mountPageFooter()`, `.kmwc-page-footer`), at the end of the layout's container. The index footer and the page footer are rendered by one function, `renderFooterLineHtml()`, so they can't drift apart. The index keeps its own extra links (README, API docs); the page footer carries Keenmate, the repo's GitHub link and the devkit version.
+
 ## What's New in v1.0.0-rc10
 
 - **Doctor — runs the variable-manifest check** — `kmwc check-vars` only ran inside `npm run build`, so a red manifest stayed invisible until someone built. During the devkit pass, web-treeview's `check:vars` failed on core's `--base-accent-color` (a name outside the base-variables contract) while `kmwc doctor` reported nothing. Doctor now reports the same verdict under `vars`: `--base-*` reads missing from the manifest, manifest entries the CSS no longer reads, and dead `--<prefix>-*` entries are errors; undocumented `--<prefix>-*` variables are a warning. Both commands share one function, `loadManifestVerdict()`, so they can't disagree.
@@ -28,11 +33,6 @@ them in the same shape: `@keenmate/web-components-devkit`.
 - **Examples kit — inline code readable in light mode** — Inline `code` used the raw accent colour on its pale chip, which read at about 3.3:1 for the default accent. The text keeps the accent's hue at no more than 0.5 lightness. The e2e spec checks five accents in both themes for at least 4.5:1.
 - **Devkit tests — the critical paths** — The suite now runs a real library build of the playground and checks that the emitted files, the UMD global and every export `index.d.ts` declares are exactly what package.json and doctor expect. It also checks that `kmwc new` scaffolds a repo doctor finds clean, that `kmwc sync` never rewrites a local file or an existing script, and that `check-release` keeps an rc off `latest`. Doctor itself is tested end to end on fixture repos.
 
-## What's New in v1.0.0-rc09
-
-- **check-pages — page CSS that can't reach into a shadow root** — web-treeview's custom-layout and responsive pages styled the rows their `renderNodeCallback` draws with page CSS (`.file-icon`, `.node-badge`, `.isco-row`, `.dev-badge` …, 18 rules). Those rows live in the tree's shadow root, and page CSS stops at the shadow boundary, so none of the rules ever applied. Nothing in the source shows where a render callback's output ends up, so this needs the loaded page. `kmwc check-pages` now reads the page's own rules (its `<style>` blocks and `examples-local.css`) and finds what each one styles: the last part of the selector, without pseudo-classes. It reports a rule when that element exists nowhere in the document but does exist inside a component's shadow root, and names the component. Run against treeview's pages from before its fix, it lists exactly those 18 rules. The fix is a CSS variable, `::part`, or the component's styles hook (`getCustomStylesCallback`).
-- **Examples kit — the grey secondary button in dark mode** — `button.secondary` / `.btn-secondary` had white text on `#9ca3af` in dark mode, at 2.54:1. That grey sits just under the 0.34 luminance switch in the formula that picks a button's text colour, so the formula chose white. It showed on 9 web-treeview pages ("Clear", "Reset", "Move up" …) and on every other component site's grey buttons. The button now has its own fill, `--kmwc-neutral-fill-color` (`#6b7280` light / `#4b5563` dark), plus a hover token, so white text stays at 4.5:1 or better in both themes, hovered too. Muted status dots and pills keep the lighter `--kmwc-neutral-color`. An e2e spec checks the contrast in both themes.
-
 ## Catalogue
 
 <!-- kmwc:catalogue:start — generated by `npm run readme`, do not edit inside -->
@@ -44,7 +44,7 @@ them in the same shape: `@keenmate/web-components-devkit`.
 | **web-daterangepicker** | `@keenmate/web-daterangepicker` | `drp` | 12200 | [repo](https://github.com/keenmate/web-daterangepicker) · [docs](https://web-daterangepicker.keenmate.dev) · `web-daterangepicker-showcase` | ✅ | Lightweight date picker web component with excellent keyboard navigation and range selection |
 | **web-treeview** | `@keenmate/web-treeview` | `wtv` | 12300 | [repo](https://github.com/keenmate/web-treeview) · `web-treeview-showcase` | ✅ | Lightweight treeview web component with hierarchical data display, search, expand/collapse, drag-drop, and… |
 | **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-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` | `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… |
@@ -106,7 +106,7 @@ in `package.json#kmwc`, and gets the rest.
 | Piece | Import / command | Replaces |
 |---|---|---|
 | Vite preset | `@keenmate/web-components-devkit/vite` → `defineComponentConfig()` | per-repo `vite.config.ts`, `vite.examples.config.ts` |
-| Examples kit (auto-injected) | shared styles, chapter nav, copy-link buttons, theme switch, version badge, analytics | `examples-shared.css`, `examples-chapter-nav.js`, `examples-copy-link.js`, `plausible-snippet.html`, Dockerfile `sed` |
+| Examples kit (auto-injected) | shared styles, chapter nav, copy-link buttons, theme switch, version badge, page footer, analytics | `examples-shared.css`, `examples-chapter-nav.js`, `examples-copy-link.js`, `plausible-snippet.html`, Dockerfile `sed` |
 | Fragment pages | `<meta name="kmwc:title">` pages + `<kmwc-include>` partials + `<kmwc-demo>` (live markup = snippet) | the head / header / container boilerplate copied into every page, hand-copied `.code-block` snippets |
 | Examples helpers | `@keenmate/web-components-devkit/examples` → `attachControlsPersistence`, `renderExamplesIndex`, `mountExamplesKit` | `examples-controls-store.js`, 150 lines of inline index-page CSS |
 | Playwright preset | `@keenmate/web-components-devkit/playwright` → `definePlaywrightConfig()` | per-repo `playwright.config.ts` |
@@ -179,7 +179,11 @@ Every field is optional. Defaults are derived from the package.
                                                  // BlissFramework checkout above it. env KMWC_RULEBOOK_PATH wins
     "skippedChecks": []                          // e.g. ["responsive-overlay"]
   },
-  "sync": { "skippedFiles": [] }                 // e.g. ["Makefile"] to opt a file out
+  "sync": { "skippedFiles": [] },                // e.g. ["Makefile"] to opt a file out
+  "packages": [                                  // monorepos only (npm workspaces): what doctor checks
+    { "path": "packages/web-dropzone", "kind": "component" },
+    { "path": "packages/web-dropzone-core", "kind": "library" }
+  ]
 }
 ```
 
@@ -193,6 +197,16 @@ manifest check (no `check:vars` script, `kmwc check-vars` skips), for variables
 the checker can't see, such as names built by string interpolation. Doctor runs
 only the rulebook suites that apply to a library (see below).
 
+**A monorepo** (npm workspaces, e.g. web-dropzone: a private root with the example
+site, `packages/web-dropzone` + `packages/web-dropzone-core`) lists its published
+packages in `kmwc.packages`, each with its kind. The root keeps the devkit's
+example site, generated files, ports and registry checks; doctor packs each
+package (`npm pack`), runs the rulebook suites for its kind *in* the package
+(reported as `rulebook:<suite>@<path>`), and checks the loader class in each
+component package. publish-command and example-pages stay repo-wide, at the root.
+Without `packages` the root is the one package — doctor warns when npm workspaces
+exist but aren't listed, and doesn't pack a private workspace root.
+
 ### Vite preset
 
 ```ts
@@ -336,6 +350,9 @@ doctor` lists the ones still repeating the head/header boilerplate.
   shows `v1.2.3`, or `v1.2.3 (built …)` in a built site.
 - **Landing page**: `renderExamplesIndex({ pages })` renders the header, cards,
   footer and cross-page nav from the registry plus `kmwc` config.
+- **Page footer**: every other example page ends with the same line as the
+  index footer — Keenmate, the repo's GitHub link, the devkit version — inside
+  the layout's container (`.kmwc-page-footer`).
 - **Late content**: the kit mounts one task after DOM-ready. Pages that render
   sections after a fetch call `mountExamplesKit()`.
 - **Analytics**: the Plausible snippet goes into **built** pages only, and only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keenmate/web-components-devkit",
-  "version": "1.0.0-rc10",
+  "version": "1.0.0-rc11",
   "description": "Shared dev, example-site and build infrastructure for Keenmate web components: Vite preset, examples kit (chapter nav, copy-link, controls store, shared styles), Playwright preset and the `kmwc` CLI (sync, doctor, check-vars, new, readme).",
   "type": "module",
   "license": "MIT",

package/src/cli/commands/doctor.js

@@ -14,7 +14,7 @@
  * Errors fail (exit 1); warnings don't.
  */
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { getKmwcConfig, getPortsForBlock, getRegistry, LEGACY_FILES, NON_PAGE_HTML_FILES, PACKAGE_LEAK_RULES, PACKAGE_FILES_EXCLUSIONS } from '../../config.js';
 import { getSyncPlan, getScriptsPlan, CLAUDE_BLOCK_START } from '../sync-plan.js';
@@ -66,8 +66,9 @@ export const RULEBOOK_SUITES = [
   { name: 'readme-structure', isPrefixed: false, isComponentOnly: false },
   { name: 'custom-elements-manifest', isPrefixed: false, isComponentOnly: true },
   { name: 'responsive-overlay', isPrefixed: true, isComponentOnly: true },
-  { name: 'publish-command', isPrefixed: false, isComponentOnly: false },
-  { name: 'example-pages', isPrefixed: false, isComponentOnly: false },
+  // Repo-wide: one /publish command and one example site per repo, checked at its root.
+  { name: 'publish-command', isPrefixed: false, isComponentOnly: false, isRepoWide: true },
+  { name: 'example-pages', isPrefixed: false, isComponentOnly: false, isRepoWide: true },
 ];
 
 const LIBRARY_KIND = 'library';
@@ -122,9 +123,9 @@ export function getBashPath({ platform = process.platform, env = process.env, ch
   return gitRoots.map((gitRoot) => join(gitRoot, GIT_BASH_RELATIVE_PATH)).find((bashPath) => checkExists(bashPath)) || 'bash';
 }
 
-function runRulebookSuite(config, suite) {
+function runRulebookSuite(config, suite, checkedRoot) {
   const scriptPath = join(config.rulebook.path, `${suite.name}.checks.sh`).replace(/\\/g, '/');
-  const scriptArgs = [scriptPath, config.root.replace(/\\/g, '/')];
+  const scriptArgs = [scriptPath, checkedRoot.replace(/\\/g, '/')];
   if (suite.isPrefixed && config.prefix) scriptArgs.push(config.prefix);
   return spawnSync(getBashPath(), scriptArgs, { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
 }
@@ -302,8 +303,15 @@ export function checkComponent(config, doctorConfig = {}) {
     if (!outputMismatches.length) addPass('library', 'package.json targets match the library build outputs');
   }
 
+  // ── monorepo: the workspace packages doctor checks ───────────────────────
+  checkWorkspacePackages(config, { addPass, addWarning, addError });
+
   // ── core's default loader class ──────────────────────────────────────────
-  if (config.prefix && config.kind !== LIBRARY_KIND) checkLoaderClass(config, { addPass, addWarning, addError });
+  if (config.prefix && config.kind !== LIBRARY_KIND) {
+    for (const checkedPackage of config.packages.filter((packageEntry) => packageEntry.kind === 'component')) {
+      checkLoaderClass(config, checkedPackage, { addPass, addWarning, addError });
+    }
+  }
 
   // ── variable manifest (what `kmwc check-vars` checks; it only runs in the build) ──
   if (config.hasPackageConfig) checkVariableManifest(config, { addPass, addWarning, addError });
@@ -320,7 +328,9 @@ export function checkComponent(config, doctorConfig = {}) {
   } else if (plausibleSiteId) addPass('analytics', `Plausible site id ${plausibleSiteId} is this repo's own`);
 
   // ── package contents ─────────────────────────────────────────────────────
-  if (doctorConfig.shouldCheckPackage !== false) checkPackageContents(config, { addPass, addWarning, addError });
+  if (doctorConfig.shouldCheckPackage !== false) {
+    for (const checkedPackage of config.packages) checkPackageContents(checkedPackage, { addPass, addWarning, addError });
+  }
 
   // ── rulebook suites ──────────────────────────────────────────────────────
   if (doctorConfig.shouldRunRulebook !== false) checkRulebook(config, { addPass, addWarning, addError });
@@ -361,11 +371,15 @@ function checkPorts(config, portBlock, registry, { addPass, addWarning, addError
  * before (or after) the core bump leaves the default loader unstyled, and no rulebook
  * check sees that (a VALIDATION-NOTES `## C-NC-8` even hides a leftover old class).
  */
-function checkLoaderClass(config, { addPass, addWarning, addError }) {
-  const coreLoader = loadCoreLoader(config.root);
+function checkLoaderClass(config, checkedPackage, { addPass, addWarning, addError }) {
+  const coreLoader = loadCoreLoader(checkedPackage.root);
   if (!coreLoader?.separator) return;
   const coreClassName = `${config.prefix}${coreLoader.separator}loader`;
-  const { isCoreClassStyled, renamedClasses, collidingClasses } = getLoaderClassVerdict(coreLoader.separator, loadStyledLoaderClasses(config.root, config.prefix));
+  const styledLoaderClasses = loadStyledLoaderClasses(checkedPackage.root, config.prefix).map((styledClass) => ({
+    ...styledClass,
+    file: getPackageFilePath(checkedPackage, styledClass.file),
+  }));
+  const { isCoreClassStyled, renamedClasses, collidingClasses } = getLoaderClassVerdict(coreLoader.separator, styledLoaderClasses);
   for (const { file, className } of collidingClasses) {
     addWarning(
       'loader',
@@ -418,10 +432,56 @@ export function getPackageLeaks(packedPaths) {
     });
 }
 
+/** `src/x.css` in a workspace package → `packages/web-x/src/x.css`; unchanged at the repo root. */
+function getPackageFilePath(checkedPackage, filePath) {
+  return checkedPackage.path === '.' ? filePath : `${checkedPackage.path.replace(/\\/g, '/').replace(/\/$/, '')}/${filePath}`;
+}
+
+/** The workspace directories package.json declares (`packages/*` → each subdirectory with a package.json). */
+function getWorkspaceRoots(config) {
+  const workspaces = config.packageJson.workspaces;
+  const workspacePatterns = Array.isArray(workspaces) ? workspaces : workspaces?.packages || [];
+  return workspacePatterns.flatMap((pattern) => {
+    if (!pattern.endsWith('/*')) return [resolve(config.root, pattern)];
+    const parentPath = resolve(config.root, pattern.slice(0, -2));
+    if (!existsSync(parentPath)) return [];
+    return readdirSync(parentPath)
+      .map((entryName) => join(parentPath, entryName))
+      .filter((entryPath) => existsSync(join(entryPath, 'package.json')));
+  });
+}
+
+/**
+ * A monorepo lists its packages in kmwc.packages, or doctor checks only the root (which a
+ * private workspace root never publishes). Every workspace package is listed; every listed one exists.
+ */
+function checkWorkspacePackages(config, { addPass, addWarning, addError }) {
+  for (const checkedPackage of config.packages) {
+    if (!existsSync(join(checkedPackage.root, 'package.json'))) addError('packages', `kmwc.packages lists ${checkedPackage.path}, which has no package.json`, 'fix the path');
+  }
+  const workspaceRoots = getWorkspaceRoots(config);
+  if (!workspaceRoots.length) return;
+  const toRepoPath = (absolutePath) => relative(config.root, absolutePath).replace(/\\/g, '/');
+  if (!config.packageJson.kmwc?.packages) {
+    addWarning(
+      'packages',
+      `npm workspaces (${workspaceRoots.map(toRepoPath).join(', ')}) but no kmwc.packages — doctor checks the root as the package`,
+      `list them: "packages": [${workspaceRoots.map((workspaceRoot) => `{ "path": "${toRepoPath(workspaceRoot)}", "kind": "component" | "library" }`).join(', ')}]`
+    );
+    return;
+  }
+  const listedRoots = new Set(config.packages.map((checkedPackage) => checkedPackage.root));
+  const unlistedRoots = workspaceRoots.filter((workspaceRoot) => !listedRoots.has(workspaceRoot));
+  for (const workspaceRoot of unlistedRoots) {
+    addWarning('packages', `workspace package ${toRepoPath(workspaceRoot)} is not in kmwc.packages — doctor doesn't check it`, `add { "path": "${toRepoPath(workspaceRoot)}", "kind": … }`);
+  }
+  if (!unlistedRoots.length) addPass('packages', `kmwc.packages lists every workspace package (${config.packages.map((checkedPackage) => `${checkedPackage.path} ${checkedPackage.kind}`).join(', ')})`);
+}
+
 /** The file list `npm publish` would ship (no lifecycle scripts, nothing written). */
-function getPackedPaths(config) {
+function getPackedPaths(packageRoot) {
   const packResult = spawnSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], {
-    cwd: config.root,
+    cwd: packageRoot,
     encoding: 'utf8',
     shell: process.platform === 'win32',
   });
@@ -430,26 +490,37 @@ function getPackedPaths(config) {
   return packReport[0].files.map((file) => file.path);
 }
 
-function checkPackageContents(config, { addPass, addWarning, addError }) {
+/**
+ * One package's `npm pack` list. A private workspace root is skipped: npm never publishes it and,
+ * having no `files`, it would "leak" everything (list the packages in kmwc.packages). A private
+ * single package (the devkit playground) is still checked — it stands in for a real one.
+ */
+function checkPackageContents(checkedPackage, { addPass, addWarning, addError }) {
+  const packageLabel = checkedPackage.path === '.' ? '' : `${checkedPackage.path}: `;
+  const packageJson = JSON.parse(readFileSync(join(checkedPackage.root, 'package.json'), 'utf8'));
+  if (packageJson.private && packageJson.workspaces) {
+    addPass('package', `${packageLabel}private workspace root — never published, contents not checked`);
+    return;
+  }
   let packedPaths;
   try {
-    packedPaths = getPackedPaths(config);
+    packedPaths = getPackedPaths(checkedPackage.root);
   } catch {
     packedPaths = null;
   }
   if (!packedPaths) {
-    addWarning('package', 'npm pack --dry-run failed — package contents not checked');
+    addWarning('package', `${packageLabel}npm pack --dry-run failed — package contents not checked`);
     return;
   }
   const packageLeaks = getPackageLeaks(packedPaths);
   for (const packageLeak of packageLeaks) {
     addError(
       'package',
-      `${packageLeak.path} would be published (${packageLeak.label})`,
-      `exclude it in package.json "files" (e.g. ${PACKAGE_FILES_EXCLUSIONS.map((exclusion) => `"${exclusion}"`).join(', ')}) or narrow the glob`
+      `${getPackageFilePath(checkedPackage, packageLeak.path)} would be published (${packageLeak.label})`,
+      `exclude it in ${packageLabel ? `${checkedPackage.path}/` : ''}package.json "files" (e.g. ${PACKAGE_FILES_EXCLUSIONS.map((exclusion) => `"${exclusion}"`).join(', ')}) or narrow the glob`
     );
   }
-  if (!packageLeaks.length) addPass('package', `${packedPaths.length} packed file(s), no dev-only files`);
+  if (!packageLeaks.length) addPass('package', `${packageLabel}${packedPaths.length} packed file(s), no dev-only files`);
 }
 
 function checkRulebook(config, { addPass, addWarning, addError }) {
@@ -458,21 +529,32 @@ function checkRulebook(config, { addPass, addWarning, addError }) {
     return;
   }
   const skippedSuites = new Set(config.rulebook.skippedChecks);
-  const acceptedCheckIds = loadAcceptedCheckIds(config.root);
-  const suites = getRulebookSuites(config.kind);
-  if (suites.length < RULEBOOK_SUITES.length) {
-    const componentOnlySuiteNames = RULEBOOK_SUITES.filter((suite) => !suites.includes(suite)).map((suite) => suite.name);
-    addPass('rulebook', `${config.kind}: component-only suites not run (${componentOnlySuiteNames.join(', ')})`);
+  const isMonorepo = config.packages.some((checkedPackage) => checkedPackage.path !== '.');
+  // [{ suite, checkedRoot, checkName, acceptedCheckIds }]: a package's suites run in the package
+  // (for its kind), the repo-wide ones once at the root. A single-package repo runs all at the root.
+  const suiteRuns = [];
+  for (const checkedPackage of config.packages) {
+    const suites = getRulebookSuites(checkedPackage.kind).filter((suite) => !isMonorepo || !suite.isRepoWide);
+    const packageSuffix = isMonorepo ? `@${checkedPackage.path}` : '';
+    if (suites.length < RULEBOOK_SUITES.filter((suite) => !isMonorepo || !suite.isRepoWide).length) {
+      const componentOnlySuiteNames = RULEBOOK_SUITES.filter((suite) => suite.isComponentOnly).map((suite) => suite.name);
+      addPass(`rulebook${packageSuffix}`, `${checkedPackage.kind}: component-only suites not run (${componentOnlySuiteNames.join(', ')})`);
+    }
+    const acceptedCheckIds = new Set([...loadAcceptedCheckIds(config.root), ...loadAcceptedCheckIds(checkedPackage.root)]);
+    for (const suite of suites) suiteRuns.push({ suite, checkedRoot: checkedPackage.root, checkName: `rulebook:${suite.name}${packageSuffix}`, acceptedCheckIds });
+  }
+  if (isMonorepo) {
+    const acceptedCheckIds = loadAcceptedCheckIds(config.root);
+    for (const suite of RULEBOOK_SUITES.filter((repoSuite) => repoSuite.isRepoWide)) suiteRuns.push({ suite, checkedRoot: config.root, checkName: `rulebook:${suite.name}`, acceptedCheckIds });
   }
-  for (const suite of suites) {
+  for (const { suite, checkedRoot, checkName, acceptedCheckIds } of suiteRuns) {
     if (skippedSuites.has(suite.name)) continue;
     if (!existsSync(join(config.rulebook.path, `${suite.name}.checks.sh`))) continue;
-    const suiteResult = runRulebookSuite(config, suite);
+    const suiteResult = runRulebookSuite(config, suite, checkedRoot);
     if (suiteResult.error) {
       addWarning('rulebook', `cannot run bash (${suiteResult.error.code}) — rulebook checks skipped`, 'install Git Bash / run from a POSIX shell');
       return;
     }
-    const checkName = `rulebook:${suite.name}`;
     const failures = getSuiteFailures(suiteResult.stdout);
     // A suite passes with exit 0 and fails with exit 1 + FAIL lines. Anything else (2 = usage,
     // 127 = the script wasn't found — WSL's bash on a C:/ path) means it never ran: say so,

package/src/config.d.ts

@@ -73,6 +73,19 @@ export interface KmwcPackageConfig {
     skippedChecks?: string[];
   };
   sync?: { skippedFiles?: string[] };
+  /**
+   * The packages this repo publishes, for a monorepo whose root is not the package (npm
+   * workspaces): doctor runs the package-contents check and the rulebook suites for each one's
+   * kind there. Default: one package, the repo root, with the repo's kind.
+   */
+  packages?: Array<{ path: string; kind: 'component' | 'library' }>;
+}
+
+/** One package doctor checks: `path` as configured, `root` resolved. */
+export interface KmwcPackage {
+  path: string;
+  root: string;
+  kind: 'component' | 'library';
 }
 
 export interface KmwcConfig {
@@ -131,6 +144,7 @@ export interface KmwcConfig {
   };
   rulebook: { path: string; skippedChecks: string[] };
   sync: { skippedFiles: string[] };
+  packages: KmwcPackage[];
 }
 
 export const DEVKIT_ROOT: string;

package/src/config.js

@@ -183,6 +183,23 @@ export function getKmwcConfig(root = process.cwd()) {
   return mapKmwcConfig(getJsonFile(packageJsonPath), root);
 }
 
+const PACKAGE_KINDS = ['component', 'library'];
+
+/**
+ * `kmwc.packages` → [{ path, root, kind }]; without it, one package at the repo root with the
+ * repo's kind (a showcase / docs / test repo checks as a component, as before).
+ */
+function mapPackages(packageEntries, root, repoKind) {
+  if (!packageEntries) return [{ path: '.', root, kind: repoKind === 'library' ? 'library' : 'component' }];
+  if (!Array.isArray(packageEntries) || !packageEntries.length) throw new Error('kmwc.packages: expected a non-empty array of { path, kind }');
+  return packageEntries.map((packageEntry) => {
+    if (!packageEntry?.path || !PACKAGE_KINDS.includes(packageEntry.kind)) {
+      throw new Error(`kmwc.packages: ${JSON.stringify(packageEntry)} needs a "path" and a "kind" (${PACKAGE_KINDS.join(' | ')})`);
+    }
+    return { path: packageEntry.path, root: resolve(root, packageEntry.path), kind: packageEntry.kind };
+  });
+}
+
 /** Map a parsed package.json to the resolved config (pure — used by tests). */
 export function mapKmwcConfig(packageJson, root = process.cwd()) {
   const packageConfig = packageJson.kmwc || {};
@@ -199,6 +216,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
   const cssVariables = packageConfig.cssVariables === false ? { checkMode: 'off' } : packageConfig.cssVariables || {};
   const rulebook = packageConfig.rulebook || {};
   const devPort = ports.dev ?? 5173;
+  const kind = packageConfig.kind || getRegistryKind(id);
 
   return {
     root,
@@ -206,7 +224,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
     packageJson,
     id,
     packageName: packageJson.name || id,
-    kind: packageConfig.kind || getRegistryKind(id),
+    kind,
     version: packageJson.version || '0.1.0',
     title: packageConfig.title || mapToTitleCase(id),
     tagline: packageConfig.tagline || packageJson.description || '',
@@ -275,6 +293,7 @@ export function mapKmwcConfig(packageJson, root = process.cwd()) {
     sync: {
       skippedFiles: packageConfig.sync?.skippedFiles || [],
     },
+    packages: mapPackages(packageConfig.packages, root, kind),
   };
 }
 

package/src/examples/constants.js

@@ -97,6 +97,12 @@ export const INDEX_PAGE_CLASSES = {
   devkit: 'kmwc-index__devkit',
 };
 
+/** The footer the kit appends to every example page but the index (page-footer.js). */
+export const PAGE_FOOTER_CLASSES = {
+  root: 'kmwc-page-footer',
+  devkit: 'kmwc-page-footer__devkit',
+};
+
 /** <kmwc-demo> output (rendered at build time by page-composer.js) + the kit's copy button. */
 export const DEMO_CLASSES = {
   root: 'kmwc-demo',

package/src/examples/css/page-footer.css

@@ -0,0 +1,19 @@
+/* ==============================================================================
+   EXAMPLES KIT — PAGE FOOTER
+   ==============================================================================
+   The footer the kit appends to every example page but the index
+   (page-footer.js); the same line as the index footer. */
+@layer kmwc {
+    .kmwc-page-footer {
+        text-align: center;
+        margin-top: 3rem;
+        padding: 1.5rem 0 1rem;
+        border-top: 1px solid var(--kmwc-border-color);
+        color: var(--kmwc-text-color-3);
+        font-size: 0.875rem;
+    }
+
+    .kmwc-page-footer p {
+        margin: 0;
+    }
+}

package/src/examples/css/style.css

@@ -31,3 +31,4 @@
 @import './spotlight.css';
 @import './theme-switch.css';
 @import './index-page.css';
+@import './page-footer.css';

package/src/examples/index-page.js

@@ -19,6 +19,7 @@
 import { getPageConfig } from './page-config.js';
 import { getVersionLabel } from './version-badge.js';
 import { INDEX_PAGE_CLASSES } from './constants.js';
+import { renderFooterLineHtml } from './page-footer.js';
 
 const HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
 const mapToEscapedHtml = (text) => String(text ?? '').replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
@@ -32,10 +33,6 @@ export function renderExamplesIndex(indexConfig) {
   const pages = indexConfig.pages || [];
   const title = indexConfig.title ?? pageConfig.title;
   const tagline = indexConfig.tagline ?? pageConfig.tagline;
-  const footerLinks = [
-    ...(pageConfig.repository ? [{ label: 'GitHub', href: pageConfig.repository }] : []),
-    ...(indexConfig.links || []),
-  ];
   const classes = INDEX_PAGE_CLASSES;
 
   document.body.classList.add(classes.body);
@@ -63,13 +60,7 @@ export function renderExamplesIndex(indexConfig) {
         .join('')}
     </div>
     <footer class="${classes.footer}">
-      <p>Created by <a href="https://github.com/keenmate" target="_blank" rel="noopener">Keenmate s.r.o.</a>${footerLinks
-        .map((link) => ` | <a href="${mapToEscapedHtml(link.href)}" target="_blank" rel="noopener">${mapToEscapedHtml(link.label)}</a>`)
-        .join('')}${
-        pageConfig.devkitVersion
-          ? ` | <a class="${classes.devkit}" href="${mapToEscapedHtml(pageConfig.devkitHomepage)}" target="_blank" rel="noopener">web-components-devkit v${mapToEscapedHtml(pageConfig.devkitVersion)}</a>`
-          : ''
-      }</p>
+      ${renderFooterLineHtml(pageConfig, { links: indexConfig.links, devkitClass: classes.devkit })}
     </footer>`;
   containerEl.prepend(pageElement);
 

package/src/examples/index.d.ts

@@ -11,7 +11,7 @@ export interface KmwcPageConfig {
   isSpotlightEnabled: boolean;
   repository: string;
   homepage: string;
-  /** The @keenmate/web-components-devkit version that built the page (shown in the index footer). */
+  /** The @keenmate/web-components-devkit version that built the page (shown in the page footers). */
   devkitVersion: string;
   devkitHomepage: string;
 }
@@ -93,6 +93,10 @@ export function renderVersionBadges(root?: ParentNode): void;
 export function attachDemoCopyButtons(root?: ParentNode): void;
 export function getVersionLabel(pageConfig?: KmwcPageConfig): string;
 
+/** Append the footer (Keenmate | GitHub | devkit version) to an example page; none on the index. */
+export function mountPageFooter(): HTMLElement | null;
+/** The footer line the index and the page footer share. */
+export function renderFooterLineHtml(pageConfig: KmwcPageConfig, footerConfig: { links?: Array<{ label: string; href: string }>; devkitClass: string }): string;
 export function mountThemeSwitch(): { unmount(): void };
 export function applyTheme(theme: Theme): void;
 export function getSavedTheme(): Theme;
@@ -118,6 +122,7 @@ export const SPOTLIGHT_FULLSCREEN_MEDIA: string;
 export const CHAPTER_CODE_PATTERN: RegExp;
 export const COPY_LINK_CLASSES: Record<string, string>;
 export const INDEX_PAGE_CLASSES: Record<string, string>;
+export const PAGE_FOOTER_CLASSES: { root: string; devkit: string };
 export const THEME_SWITCH_CLASSES: Record<string, string>;
 export const DEMO_CLASSES: Record<string, string>;
 export const THEMES: Theme[];

package/src/examples/index.js

@@ -15,6 +15,7 @@ export { searchChapters, checkMatchesAny, renderHighlightedText } from './chapte
 export { attachCopyLinks, copyText, getSectionUrl } from './copy-link.js';
 export { renderVersionBadges, getVersionLabel } from './version-badge.js';
 export { attachDemoCopyButtons } from './demo-code.js';
+export { mountPageFooter, renderFooterLineHtml } from './page-footer.js';
 export { mountThemeSwitch, applyTheme, getSavedTheme } from './theme-switch.js';
 export { ensureSectionAnchors, generateSlug, getHeadingLabel, getChapterCode, mapToCodeKey, findSectionByHash } from './sections.js';
 export { getPageConfig, attachDomReadyHandler } from './page-config.js';

package/src/examples/kit.js

@@ -5,15 +5,16 @@ import { attachCopyLinks } from './copy-link.js';
 import { renderVersionBadges } from './version-badge.js';
 import { mountThemeSwitch } from './theme-switch.js';
 import { attachDemoCopyButtons } from './demo-code.js';
+import { mountPageFooter } from './page-footer.js';
 import { INDEX_PAGE_CLASSES } from './constants.js';
 
 /**
  * (Re)mount the page-level helpers on the current DOM (copy-links, chapter
  * nav, short chapter links, spotlight, version badges, demo copy buttons,
- * theme switch). Runs automatically once per page; call it again after
+ * theme switch, page footer). Runs automatically once per page; call it again after
  * rendering sections asynchronously. Idempotent: copy-link / demo copy buttons
- * skip elements that already have one, the nav, spotlight and theme switch are
- * remounted.
+ * skip elements that already have one, the nav, spotlight, theme switch and
+ * footer are remounted.
  */
 export function mountExamplesKit() {
   // Copy-links before the nav: the nav strips the buttons back out when
@@ -26,4 +27,5 @@ export function mountExamplesKit() {
   renderVersionBadges();
   attachDemoCopyButtons();
   mountThemeSwitch();
+  mountPageFooter();
 }

package/src/examples/page-footer.js

@@ -0,0 +1,44 @@
+/**
+ * The footer every example page ends with — Keenmate, the repo, and the devkit
+ * that built the page. The index page renders the same line in its own footer
+ * (index-page.js); the other pages get it from the kit (mountPageFooter).
+ */
+import { getPageConfig } from './page-config.js';
+import { INDEX_PAGE_CLASSES, PAGE_FOOTER_CLASSES } from './constants.js';
+
+const HTML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+const mapToEscapedHtml = (text) => String(text ?? '').replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
+
+/**
+ * The footer line: "Created by Keenmate s.r.o. | GitHub | …links | web-components-devkit vX".
+ * @param {import('./index.js').KmwcPageConfig} pageConfig
+ * @param {{ links?: Array<{ label: string, href: string }>, devkitClass: string }} footerConfig
+ */
+export function renderFooterLineHtml(pageConfig, { links = [], devkitClass }) {
+  const footerLinks = [...(pageConfig.repository ? [{ label: 'GitHub', href: pageConfig.repository }] : []), ...links];
+  const linksHtml = footerLinks
+    .map((link) => ` | <a href="${mapToEscapedHtml(link.href)}" target="_blank" rel="noopener">${mapToEscapedHtml(link.label)}</a>`)
+    .join('');
+  const devkitHtml = pageConfig.devkitVersion
+    ? ` | <a class="${devkitClass}" href="${mapToEscapedHtml(pageConfig.devkitHomepage)}" target="_blank" rel="noopener">web-components-devkit v${mapToEscapedHtml(pageConfig.devkitVersion)}</a>`
+    : '';
+  return `<p>Created by <a href="https://github.com/keenmate" target="_blank" rel="noopener">Keenmate s.r.o.</a>${linksHtml}${devkitHtml}</p>`;
+}
+
+/**
+ * Append the footer to an example page — inside the layout's `.container`
+ * when there is one, else at the end of <body>. Remounting replaces it; the
+ * index page keeps its own footer and gets none.
+ * @returns {HTMLElement | null}
+ */
+export function mountPageFooter() {
+  document.querySelector(`.${PAGE_FOOTER_CLASSES.root}`)?.remove();
+  if (document.body.classList.contains(INDEX_PAGE_CLASSES.body)) return null;
+
+  const footerElement = document.createElement('footer');
+  footerElement.className = PAGE_FOOTER_CLASSES.root;
+  footerElement.innerHTML = renderFooterLineHtml(getPageConfig(), { devkitClass: PAGE_FOOTER_CLASSES.devkit });
+  const containerElement = document.querySelector('body > .container');
+  (containerElement || document.body).append(footerElement);
+  return footerElement;
+}