@smartsoft001-mobilems/claude-plugins 2.88.0 → 2.90.0

package/plugins/mobilems/skills/mobilems-project-init/references/branding-reset.md

@@ -0,0 +1,112 @@
+# Branding + SEO reset — strip the reference museum's identity
+
+Reference mode copies a **different museum's** app. Its brand and SEO travel with the code and are
+invisible until QA (or the client) finds them: fonts named after the old project, its palette, its
+logo, its domain in `og:url`, its name in `<title>` and in the PL/EN translation strings.
+
+Run this **after** the shared lib + app shell are copied (steps 7–8) and **before** QA hardening.
+It is a **token/content** change only.
+
+## The invariant — re-skin, never re-build
+
+Allowed to change: colour/font/spacing **token values**, asset **files**, text **content**, site
+identity (name, domain, social image).
+
+Never change as part of this step:
+
+- layout or utility classes in templates (`smart-*`), DOM structure, component inputs/outputs
+- API field mapping, `baseQuery`/`query` keys, dictionary keys (lowercase — a rename breaks filters
+  with HTTP 409), route paths and slugs
+- translation **keys** (only their values), NgRx state shape, service contracts
+
+If a colour/font swap seems to require a template change, it is a design change — raise it with the
+user instead of doing it silently.
+
+## 1. Decide the mode (ask once, `AskUserQuestion`)
+
+- **Brand spec mode** — the user supplies fonts, palette, logo, social image, site name/domain.
+  Apply it, and still run every check below.
+- **Neutral mode (default)** — apply the generic token set in §2. The result is a deliberately plain
+  but complete, WCAG-clean skin the client's designer can replace later.
+
+## 2. Neutral token set (the default)
+
+| Token                | Value                                                                       |
+| -------------------- | --------------------------------------------------------------------------- |
+| Heading font         | **Playfair Display** (full latin-ext — covers `ą ć ę ł ń ś ź ż`)            |
+| Body / UI font       | **Inter** (fallback `system-ui, sans-serif`)                                |
+| Text on white        | `#1f2937` (≈ 15:1), secondary `#4b5563` (≈ 7.6:1) — never `#9ca3af` (2.5:1) |
+| Surfaces             | `#ffffff` page, `#f4f4f5` muted, `#e4e4e7` border                           |
+| Accent / primary     | `#3f5b76` with white text (≈ 5.6:1); active `#334a61`                       |
+| High-contrast (WCAG) | bg `#1d1d1d`, text `#ffed00`, links `#86d7be` (keep the framework's values) |
+| Logo / `no-image`    | Neutral placeholder SVG carrying the app name, no reference museum mark     |
+| Social image         | Locally generated `gfx/social-logo.jpg` 1200×550 with the app name          |
+
+Every generated text/background pair must be checked ≥4.5:1 before moving on.
+
+## 3. Carriers to reset — checklist
+
+**Styles**
+
+- `tailwind.config.js` — `theme.extend.colors.*` and `fontFamily.*`. Step 4 already wrote the neutral
+  values under role-based keys (`heading`, `body`, `ui`); in brand-spec mode swap the **values**, never
+  the keys. Delete any font token named after a typeface or another project that a copied file
+  re-added. If copied templates still use such class names, remap those classes onto the role tokens
+  or keep one clearly labelled remap block — never leave an unexplained legacy name. No `fontFamily`
+  entry may be `[]`.
+- `apps/web/src/styles.scss` — the typography header block, `@font-face` families and the metric
+  fallbacks (`* Fallback` / `* Fallback Android`) must name the new fonts; drop rules that target the
+  reference museum's own selectors.
+- Any hardcoded hex in copied shared components that duplicates a palette token → replace with the
+  token (do not restyle the component).
+
+**Assets** (`apps/web/public/gfx`, `apps/web/public`)
+
+- logo(s) (`main-logo`, footer/white variants), `no-image` placeholder, `social-logo.jpg`,
+  `favicon.ico` + 32×32 + 192×192 + `apple-touch-icon`, `manifest.webmanifest` name/icons.
+- Delete reference-only assets (partner/funding logos of the other museum, its banners). Serve each
+  image near its rendered size (oversized copies trigger `NG0913`).
+
+**SEO / identity**
+
+- `apps/web/src/index.html` — `<title>`, `description`, `og:title`/`og:description`/`og:url`/
+  `og:image`(+`:secure_url`,`:width`,`:height`,`:alt`), `twitter:*`. Absolute URLs come from the new
+  `SITE_URL`.
+- `museum-seo.service.ts` — default OG image, base title, locale map; no reference host anywhere.
+- `sitemap.xml` / `robots.txt` — dynamic `SITE_URL`-driven endpoints only (see `qa-hardening.md` §2).
+- `environment.ts` / `.prod.ts` / `.env.dev` — `apiUrl`, `multimediaUrl`, `siteUrl` of THIS museum.
+
+**Content**
+
+- `apps/web/public/translations.json` — museum name, base title (`MODEL.mainTitle`), skip-link
+  labels, footer/contact copy, static-page fallbacks — **both** PL and EN. Keys unchanged.
+- Footer/contact templates: no hardcoded reference address, phone, e-mail or socials (live data comes
+  from the CMS API).
+- Comments that name the origin project — rewrite or drop.
+
+## 4. Prove it — no leftovers
+
+Grep the workspace for the reference project's identity and fix every hit (case-insensitive; use the
+reference repo's own name, museum name and domain, plus its import prefix):
+
+```bash
+grep -rniE "<source-project-name>|<source-domain>|@<source-prefix>/" \
+  apps libs *.js *.json --include="*.ts" --include="*.html" --include="*.scss" \
+  --include="*.json" --include="*.js" | grep -v node_modules
+```
+
+Expected result: **no hits**.
+
+`verify-init.sh` independently asserts a narrower set: font tokens are role-named (`heading` / `body`
+/ `ui`, not named after a typeface or a project), no `{{...}}` placeholder survives, no workspace
+alias other than `@<PREFIX>/` is mapped, `fontFamily` has no empty entry, and a favicon exists.
+
+It hardcodes **no** project identity. In reference mode, pass the source project's slug or domain as
+its third argument and it will grep for that too:
+
+```bash
+scripts/verify-init.sh <workspace-root> <PREFIX> <source-project-slug>
+```
+
+That narrower set is not a substitute for the sweep above — it does not look at logos, `og:`/
+`twitter:` tags, the manifest, or contrast ratios. Run the full sweep yourself and report it.

package/plugins/mobilems/skills/mobilems-project-init/references/claude-config.md

@@ -29,6 +29,13 @@ permission / MCP allow-lists. **Extend, do not replace** the base file — keep
 > hosts (its own portal domain, project n8n/maia webhooks). Seed the generic-useful entries and let
 > the project grow its own.
 
+## Agent config lives in `.claude/`, never `.github/`
+
+The Nx scaffolding may have written `.github/skills/`, `.github/agents/`, `.github/prompts/` (the
+Copilot layout). Those duplicate the enabled `nx@nx-claude-plugins` plugin. `mobilems-devops-config`
+owns that cleanup (`references/github-hygiene.md`) — if you see them here, either run that skill or
+apply the same rule: delete plugin duplicates, `git mv` bespoke ones into `.claude/`.
+
 ## tools/specs + tools/prompts
 
 Seed pointers so the museum conventions are discoverable (the framework repo keeps the canonical

package/plugins/mobilems/skills/mobilems-project-init/references/config-providers.md

@@ -1,7 +1,7 @@
 # app.config.ts — the MobilEMS provider set
 
 Overwrite `apps/web/src/app/app.config.ts` with the providers below (the base shipped a minimal
-version). Thread `<PREFIX>` (reference uses `@msr`). `app.config.server.ts` and
+version). Thread `<PREFIX>`. `app.config.server.ts` and
 `app.routes.server.ts` stay as the base emitted them.
 
 The imports from `@<PREFIX>/angular` (`LanguageInterceptor`, `PreviewAuthInterceptor`,

package/plugins/mobilems/skills/mobilems-project-init/references/qa-hardening.md

@@ -1,26 +1,27 @@
-# QA hardening — lessons from live museum deployments
+# QA hardening
 
-Every item below is a **real defect reported in QA on production museum projects** (Linear: Muzeum
-Ostrowiec MOB-938…MOB-995, Muzeum Tomaszów Lubelski MOB-948…MOB-996). The foundation is copied from
-a reference repo, so the default failure mode is **reference-project leftovers** plus a handful of
+Every item below is a defect class that recurs on museum projects. The foundation is copied from a
+reference repo, so the default failure mode is **source-project leftovers** plus a handful of
 recurring SEO/i18n/WCAG gaps. Work through this checklist when applying the delta — each item is
-cheap to do during init and expensive to chase later in QA.
+cheap to do during init and expensive to chase later.
 
 ## 1. No reference-project leftovers (branding)
 
 The reference repo belongs to a _different museum_. Everything carrying that museum's identity must
-be replaced or generated for the target project:
-
-- **`sitemap.xml` + `robots.txt`** — never copy static files (QA found `zbiory.muzeum-orkana.pl`
-  URLs shipped to another museum). Implement them as **dynamic SSR endpoints** driven by the
-  `SITE_URL` env var — see section 2.
-- **`og:image` / `og:image:secure_url` / `twitter:image` / `og:url`** — must point at the target
-  museum's domain, not the reference deploy (QA found `mobilems-muzeum-swiatowid-qa.smartsoft.biz.pl/gfx/social-logo.jpg`).
-  Use `SITE_URL`/`siteUrl` to build absolute URLs; ship a local `gfx/social-logo.jpg` for this app.
+be replaced or generated for the target project. **`references/branding-reset.md` (step 9) is the
+full checklist — styles, fonts, palette, assets, translations — and runs before this one.** What
+follows are the SEO-side items:
+
+- **`sitemap.xml` + `robots.txt`** — never ship static files; a static copy hardcodes whatever
+  domain it was written with. Implement them as **dynamic SSR endpoints** driven by the `SITE_URL`
+  env var — see section 2.
+- **`og:image` / `og:image:secure_url` / `twitter:image` / `og:url`** — must point at this app's own
+  domain. Build absolute URLs from `SITE_URL`/`siteUrl`; ship a local `gfx/social-logo.jpg` for this
+  app rather than pointing at another deploy.
 - **Favicon** — the base often has none. Ship the full set: `favicon.ico`, 32×32 + 192×192 PNG,
-  `apple-touch-icon` (two projects opened QA bugs "Brak ikony").
+  `apple-touch-icon`.
 - **Skip links** — keep them (they are required), but rewrite their labels/targets for THIS app's
-  sections; copied skip links still said "Światowid". Localize them (PL/EN translation keys).
+  sections; a copied skip link still names the source project. Localize them (PL/EN translation keys).
 - **Footer / contact data** — target museum's phone, e-mail, socials; links come from the CMS API,
   not hardcode.
 - Local static assets (funding logos etc.) must be served near their rendered size — oversized
@@ -28,7 +29,7 @@ be replaced or generated for the target project:
 
 ## 2. Dynamic sitemap + robots endpoints (server.ts)
 
-Pattern proven in MOB-948 — put the logic in **pure, testable functions** in
+Put the logic in **pure, testable functions** in
 `apps/web/src/seo/seo-endpoints.ts` (`resolveSiteUrl`, `buildSitemapXml`, `buildRobotsTxt`), and
 wire thin routes in `server.ts`:
 
@@ -47,7 +48,7 @@ wire thin routes in `server.ts`:
 
 - `<meta name="description">` + complete OpenGraph (`og:title`, `og:description`, `og:image`,
   `og:url`) + Twitter Card on the home page, in **both** languages, re-set on language switch.
-- `og:locale` must follow the active language — a hardcoded `pl_PL` was a QA bug. In
+- `og:locale` must follow the active language; never hardcode `pl_PL`. In
   `museum-seo.service.ts` use a locale map (`pl → pl_PL`, `en → en_GB`) read from
   `translateService.currentLang` (fallback via `defaultLang` — `currentLang` can be `undefined`
   during SSR), and emit one `og:locale:alternate`.
@@ -67,22 +68,21 @@ wire thin routes in `server.ts`:
 
 ## 5. WCAG invariants
 
-- **Contrast:** the reference grey `#9ca3af` on white is 2.53:1 — fails AA and was flagged on menus
-  and breadcrumbs in two projects. Use ≥4.5:1 for text: `#6f6f6f` ≈ 5.0:1, `#4b5563` ≈ 7.6:1.
+- **Contrast:** light greys fail AA on white — `#9ca3af` is only 2.53:1. Use ≥4.5:1 for text:
+  `#6f6f6f` ≈ 5.0:1, `#4b5563` ≈ 7.6:1.
   Figma mockups themselves sometimes specify failing colours — match the design _intent_ with the
   nearest compliant shade instead of copying the hex blindly, and note the deviation.
-- **Headings:** exactly one `h1` per page; no skipped levels (an `h1 → h3` jump was a recurring
-  axe-core finding). Detail pages get an `h1` (the item title), image captions are NOT headings.
-- **alt text:** when the alt comes from a CMS title, strip HTML first (`smartRemoveHtml`) —
-  `alt="<p>Tytuł</p>"` shipped to QA.
+- **Headings:** exactly one `h1` per page; no skipped levels (an `h1 → h3` jump is an axe-core
+  finding). Detail pages get an `h1` (the item title), image captions are NOT headings.
+- **alt text:** when the alt comes from a CMS title, strip HTML first (`smartRemoveHtml`),
+  otherwise the alt reads `<p>Tytuł</p>`.
 - **Keyboard:** any card implemented as `role="link"`/`tabindex=0` must activate on Enter/Space
   (or better, be a real `<a href>`). Focus must be visible; labels should react to focus/hover the
   same way the rest of the card content does.
-- **Fonts must cover Polish diacritics.** Bacasime Antique, Prata and Italiana lack 16/18 of
-  `ą ć ę ł ń ś ź ż` (+ uppercase) — titles rendered in a fallback font and QA rejected it. Verified
-  full-latin-ext replacements: **Gilda Display** (closest to Bacasime) or **Playfair Display**.
-  Never leave a `tailwind.config.js` `fontFamily` entry as an empty array — it silently falls back
-  to system sans.
+- **Fonts must cover Polish diacritics.** Decorative serifs frequently lack `ą ć ę ł ń ś ź ż`
+  (+ uppercase), so titles render in a silent fallback. Check glyph coverage before adopting a face;
+  **Playfair Display** and **Gilda Display** are full-latin-ext. Never leave a `tailwind.config.js`
+  `fontFamily` entry as an empty array — it silently falls back to system sans.
 
 ## 6. Console hygiene (build + runtime must be warning-clean)
 
@@ -107,11 +107,11 @@ These conventions were enforced by QA across modules — bake them in from the s
 
 - **One card component per entity, reused everywhere.** The home page, module lists and search
   results must render the same shared `*-grid-item` / `*-list-item` components — a second ad-hoc
-  card implementation on the home page was a High-priority bug (MOB-994).
+  card implementation on the home page is a defect, not a variant.
 - **Full-text search inputs debounce 250 ms** (`@debounce(250)` from `lodash-decorators`) — in every
   module's filters (objects, collections, articles/news).
 - **Every list page shows the total result count** (`facade.totalCount()`), independent of
-  pagination (MOB-995/996).
+  pagination.
 - **"Next page" button** at the bottom of each list follows one shared pattern
   (`NextPageComponent`: `selectedPage`/`lastPageIndex` from `totalCount()` + limit, scroll-to-top on
   advance, hidden on the last page).

package/plugins/mobilems/skills/mobilems-project-init/references/shared-lib.md

@@ -1,10 +1,14 @@
 # Build the foundation shared library
 
 The shared library `libs/shared/angular` (alias `@<PREFIX>/angular`) holds the museum's shared
-Angular building blocks: the `App` shell, header, footer, the generic page renderer, filters,
-gallery, map, slider, carousels, content widgets, WCAG + SEO services, interceptors, pipes,
-directives, tools, models, and `configs.module.ts`. Build it by copying from the reference repo's
-`libs/shared/angular/src/lib` and threading `<PREFIX>` (the reference uses `@msr`).
+Angular building blocks: the `App` shell, header, footer, the generic page renderer, gallery, map,
+slider, carousels, content widgets, WCAG + SEO services, interceptors, pipes, directives, tools,
+models, and `configs.module.ts`. Build it by copying from the reference repo's
+`libs/shared/angular/src/lib` and threading `<PREFIX>` in place of that repo's own alias.
+
+Filter components are **not** on that list. Each module builds its own by extending the framework's
+`FiltersBaseComponent<T>` (see `SKILL.md` → "Framework first"); the shared lib holds no filter
+implementation to copy.
 
 The library starts as the base shell that exports only `environment` + `EnvironmentService` with
 empty `lib/` placeholder dirs — fill those dirs with the **foundation shared components**.
@@ -86,6 +90,29 @@ see `server-env.md`), and `configs.module.ts`. These are foundation code. Confir
 build-safety grep below; if any of these files imports a feature package on your reference, it is
 feature code and belongs to a module skill — leave it out.
 
+**Build each of these ONCE here — module skills reuse them and must never re-create a local copy.**
+Check the framework catalog (`node_modules/@smartsoft001-mobilems/angular/README.md`, in-repo
+[`packages/shared/angular/README.md`](https://github.com/smartsoft001/mobilems-framework/blob/main/packages/shared/angular/README.md))
+first: if the framework already exports it — `MasonryGridComponent` and `FiltersBaseComponent` /
+`FiltersContext` above all, plus `FileUrlService`, `SeoService`, `MetaService`, `DictionaryService`,
+`SearchService`, `WcagService`, `ContrastService`, `StyleService`, `ModalService`,
+`ClickOutsideDirective`, `HoverDirective`, `ScrollableDirective`, … — import it instead of copying
+the reference's version. The reference repo predates parts of the framework, so several of its shared
+components duplicate exports that now exist; copying those is the single most common defect in this
+step. The app-level set the framework does **not** provide, and that the module skills expect to find
+here:
+
+| Kind         | Expected members                                                                                                                   |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| pipes        | `altText`, `capitalize`, `fileUrl`, `truncateHtml`                                                                                 |
+| tools        | `isInternalLink`, `normalizeUrl`, `stripHtml` (+ the shared `tools.ts` helpers)                                                    |
+| directives   | `externalLink`                                                                                                                     |
+| interceptors | `language`, `preview-auth`, `ssr-timeout`                                                                                          |
+| services     | `museum-seo`, `filter-persistence`, `local-storage`, `orientation`, `confirmation-modal`, `contact`, `data`, `environment`, `wcag` |
+
+Adjust to what the reference actually ships, but keep the rule: one implementation, in this lib,
+exported from the barrel, documented in the app's own README so the module skills can find it.
+
 ## Barrels
 
 - `src/index.ts` — the full barrel: re-export `./lib/components`, `./lib/services`,
@@ -95,6 +122,16 @@ feature code and belongs to a module skill — leave it out.
   which holds `AppComponent`/`FooterComponent`/`HeaderComponent`). Module skills add their feature
   shared components' exports when they build them.
 
+## `libs/shared/angular/README.md` — required
+
+Write a README for the lib listing what it exports, in the same shape as the framework catalog:
+components, services, pipes, tools, directives, interceptors, models — one line each, saying what it
+is for. This is not decoration: the module skills read it to decide what to reuse, and it is the only
+place the app-level (non-framework) helpers are discoverable. Head it with a pointer to the framework
+catalog (`node_modules/@smartsoft001-mobilems/angular/README.md`) and the rule "framework first, then
+this lib, then — only if neither has it — new code". Update it whenever a module skill adds a shared
+component.
+
 ## Build-safety invariant
 
 The foundation library must build with no feature package installed. The check is positive and
@@ -122,4 +159,4 @@ copy those from the reference and normalize their `dest`/`coverageDirectory`/pat
 After copying, the only reference-prefix string left should be gone. Beyond the import statements,
 remember to thread `<PREFIX>` in `libs/shared/angular/package.json` `"name"` (it reads
 `@<reference-prefix>/angular` in the reference → set it to `@<PREFIX>/angular`). A workspace-wide grep
-for the reference prefix (`@msr/`) should return nothing.
+for the source repo's own prefix should return nothing.

package/plugins/mobilems/skills/mobilems-project-init/references/tailwind-styles.md

@@ -6,6 +6,10 @@ postcss, so scss and Tailwind coexist — no migration.
 
 ## 1. `tailwind.config.js` (workspace root — create verbatim, no placeholders)
 
+The token **values** below are the neutral default set (`references/branding-reset.md` §2) — a plain,
+WCAG-clean skin. The token **keys** are the structural contract the templates use; keep them exactly
+as written. Step 9 swaps the values for the client's brand spec if there is one.
+
 ```js
 /** @type {import('tailwindcss').Config} */
 module.exports = {
@@ -16,13 +20,14 @@ module.exports = {
     extend: {
       colors: {
         primary: {
-          DEFAULT: '#414141',
-          active: 'rgb(223 223 223)',
-          red: 'rgb(193 18 31)',
+          DEFAULT: '#1f2937',
+          active: '#e4e4e7',
+          accent: '#3f5b76',
+          red: '#b3261e',
         },
         dark: {
-          DEFAULT: '#100f0d',
-          yellow: '#ffff00',
+          DEFAULT: '#1d1d1d',
+          yellow: '#ffed00',
         },
       },
       gridTemplateColumns: {
@@ -33,22 +38,24 @@ module.exports = {
           '0px 5px 5px rgba(0, 0, 0, 0.2), 0 10px 10px rgba(0, 0, 0, 0.1), 0 20px 20px rgba(0, 0, 0, 0.15)',
       },
       fontFamily: {
-        satoshi: [
-          'Satoshi',
-          'Satoshi Fallback',
-          'Satoshi Fallback Android',
-          'sans-serif',
+        heading: [
+          'Playfair Display',
+          'Playfair Display Fallback',
+          'Playfair Display Fallback Android',
+          'serif',
         ],
-        oswald: [
-          'Oswald',
-          'Oswald Fallback',
-          'Oswald Fallback Android',
+        body: [
+          'Inter',
+          'Inter Fallback',
+          'Inter Fallback Android',
+          'system-ui',
           'sans-serif',
         ],
-        'fira-sans': [
-          'Fira Sans',
-          'Fira Sans Fallback',
-          'Fira Sans Fallback Android',
+        ui: [
+          'Inter',
+          'Inter Fallback',
+          'Inter Fallback Android',
+          'system-ui',
           'sans-serif',
         ],
       },
@@ -62,11 +69,14 @@ module.exports = {
 > The `content` globs already cover `libs/**`, so feature libs added later are picked up — no edit
 > needed when modules arrive. `darkMode` keys off `contrast-high` for the WCAG high-contrast toggle.
 
-> **QA gotcha (fonts):** when the project's design swaps in its own heading font, verify it covers
-> Polish diacritics (`ą ć ę ł ń ś ź ż` + uppercase). Bacasime Antique, Prata and Italiana lack them
-> — titles silently render in a fallback font and QA rejects it (verified replacements: Gilda
-> Display, Playfair Display). Never leave a `fontFamily` entry as an empty array — it falls back to
-> system sans. See `references/qa-hardening.md` §5.
+> **Font tokens are named by role** (`heading`, `body`, `ui`), never after a typeface or a project.
+> In reference mode the copied templates may use the source project's own token names — remap those
+> class names onto these three in step 9 rather than re-adding the old tokens.
+
+> **Fonts must cover Polish diacritics** (`ą ć ę ł ń ś ź ż` + uppercase). A heading face that lacks
+> them renders titles in a silent fallback. Check the glyph coverage of any face before adopting it;
+> the defaults above are chosen for full latin-ext support. Never leave a `fontFamily` entry as an
+> empty array — it falls back to system sans. See `references/qa-hardening.md` §5.
 
 ## 2. postcss
 

package/plugins/mobilems/skills/mobilems-project-init/scripts/verify-init.sh

@@ -8,8 +8,11 @@
 # Portable to macOS system bash (3.2). Exit 0 = all pass; exit 1 = one or more checks failed.
 set -eu
 
-ROOT="${1:?usage: verify-init.sh <workspace-root> <PREFIX>}"
-PREFIX="${2:?usage: verify-init.sh <workspace-root> <PREFIX>}"
+ROOT="${1:?usage: verify-init.sh <workspace-root> <PREFIX> [SOURCE_ID]}"
+PREFIX="${2:?usage: verify-init.sh <workspace-root> <PREFIX> [SOURCE_ID]}"
+# Optional: in reference mode, the source project's slug or domain, so branding leakage from it can
+# be checked. No project identity is hardcoded in this script.
+SOURCE_ID="${3:-}"
 cd "$ROOT" 2>/dev/null || { echo "ERROR: no such dir: $ROOT" >&2; exit 2; }
 
 fail=0
@@ -26,15 +29,56 @@ grep -q "multimediaUrl" apps/web/src/server.ts && pass "multimediaUrl in server.
 grep -q "/api/translations" apps/web/src/server.ts && pass "/api/translations endpoint" || bad "/api/translations in server.ts"
 
 echo "== QA hardening (references/qa-hardening.md) =="
-# dynamic sitemap/robots endpoints (static copies shipped another museum's domain in past projects)
+# dynamic sitemap/robots endpoints — a static copy hardcodes whatever domain it was written with
 grep -q "sitemap.xml" apps/web/src/server.ts && pass "dynamic /sitemap.xml endpoint" || bad "/sitemap.xml endpoint in server.ts (SITE_URL-driven, never a static copy)"
 grep -q "robots.txt" apps/web/src/server.ts && pass "dynamic /robots.txt endpoint" || bad "/robots.txt endpoint in server.ts (SITE_URL-driven, never a static copy)"
-if ls apps/web/public/favicon.ico apps/web/src/favicon.ico >/dev/null 2>&1; then pass "favicon present"; else bad "favicon.ico missing (QA bug 'Brak ikony' in two projects)"; fi
-# an empty fontFamily array silently falls back to system sans (QA-rejected typography)
-if grep -qE ":\s*\[\s*\]" tailwind.config.js 2>/dev/null; then bad "empty fontFamily array in tailwind.config.js (heading font falls back to system sans)"; else pass "no empty fontFamily entries"; fi
+if ls apps/web/public/favicon.ico apps/web/src/favicon.ico >/dev/null 2>&1; then pass "favicon present"; else bad "favicon.ico missing"; fi
+# an empty fontFamily array silently falls back to system sans
+if grep -qE ":[[:space:]]*\[[[:space:]]*\]" tailwind.config.js 2>/dev/null; then bad "empty fontFamily array in tailwind.config.js (heading font falls back to system sans)"; else pass "no empty fontFamily entries"; fi
 grep -q "./lib/components" libs/shared/angular/src/index.ts && pass "shared-lib components barrel populated" || bad "components barrel in shared-lib index.ts"
+[ -f libs/shared/angular/README.md ] && pass "shared-lib README (module skills read it)" || bad "libs/shared/angular/README.md missing — document the lib's components/services/pipes/tools/directives"
 [ -f .claude/settings.json ] && grep -q "flow@mobilems" .claude/settings.json && pass "flow@mobilems enabled" || bad "flow@mobilems in .claude/settings.json"
 
+echo "== Branding + SEO reset (references/branding-reset.md) =="
+# Font tokens are named by role, never after a typeface or a project. A token named after a
+# typeface means a copied file re-added the source project's naming.
+if grep -qE "fontFamily:" tailwind.config.js 2>/dev/null; then
+  if grep -qE "^[[:space:]]*(heading|body|ui):" tailwind.config.js 2>/dev/null; then
+    pass "role-named font tokens"
+  else
+    bad "font tokens are not role-named (expected heading/body/ui) — see branding-reset.md §3"
+  fi
+fi
+# unreplaced placeholders ship literal '{{...}}' to users
+PH="$(grep -rl "{{" tailwind.config.js apps/web/src/index.html apps/web/public/translations.json 2>/dev/null || true)"
+if [ -n "$PH" ]; then
+  bad "unreplaced {{...}} placeholders:"
+  printf '        %s\n' $PH >&2
+else
+  pass "no unreplaced placeholders"
+fi
+# In reference mode the app is copied from a source project, so its identity can travel with the
+# code. Pass that project's slug/domain as $3 to have it checked; omit it in foundation-only mode.
+if [ -n "${SOURCE_ID:-}" ]; then
+  LEAKID="$(grep -rilE "$SOURCE_ID" tailwind.config.js apps/web/src apps/web/public .env.dev 2>/dev/null || true)"
+  if [ -n "$LEAKID" ]; then
+    bad "source project identity ('$SOURCE_ID') still present — run step 9 (branding reset):"
+    printf '        %s\n' $LEAKID >&2
+  else
+    pass "no source project identity"
+  fi
+fi
+
+echo "== Framework first (packages/shared/angular/README.md) =="
+# masonry belongs to the framework's MasonryGridComponent — no app-level instances
+MAS="$(grep -rlnE "new Masonry\(|MasonryInstance" libs apps/web/src 2>/dev/null || true)"
+if [ -n "$MAS" ]; then
+  bad "hand-rolled masonry — use <smart-mobilems-masonry-grid> (MasonryGridComponent):"
+  printf '        %s\n' $MAS >&2
+else
+  pass "no hand-rolled masonry instances"
+fi
+
 echo "== Foundation scope (no feature modules yet) =="
 if ls -d libs/museum-* >/dev/null 2>&1; then bad "libs/museum-* present (feature modules are built by the module skills)"; else pass "no libs/museum-*"; fi
 # feature routes reference a museum-* lib; loadChildren + the import often span lines, so match museum- anywhere
@@ -70,10 +114,19 @@ else
 fi
 
 echo "== Prefix threaded =="
-if grep -rq "@msr/" libs/shared/angular/src apps/web/src 2>/dev/null && [ "$PREFIX" != "msr" ]; then
-  bad "stray @msr/ imports (prefix not fully threaded to @$PREFIX/)"
+# Derive the workspace's own aliases from tsconfig.base.json rather than naming any project's
+# prefix here. Anything mapped that is neither @$PREFIX/ nor a framework scope is a leftover.
+FOREIGN="$(grep -oE '"@[A-Za-z0-9_-]+/[A-Za-z0-9_*/-]*"' tsconfig.base.json 2>/dev/null |
+  tr -d '"' | grep -vE "^@smartsoft001" | grep -vE "^@$PREFIX/" | cut -d/ -f1 | sort -u || true)"
+if [ -n "$FOREIGN" ]; then
+  bad "tsconfig.base.json maps a foreign workspace alias (expected @$PREFIX/):"
+  printf '        %s\n' $FOREIGN >&2
+  for a in $FOREIGN; do
+    SRC="$(grep -rl "$a/" libs/shared/angular/src apps/web/src 2>/dev/null || true)"
+    [ -n "$SRC" ] && printf '          imported in: %s\n' $SRC >&2
+  done
 else
-  pass "no stray reference-prefix imports"
+  pass "workspace aliases use @$PREFIX/"
 fi
 
 echo

package/plugins/mobilems/skills/mobilems-thematic-publications/SKILL.md

@@ -28,7 +28,31 @@ OWN domain entity, its OWN reducer (`getReducer`), and **no `baseQuery`**.
 Run `scripts/detect-init.sh <workspace-root>`. It confirms the MobilEMS foundation is present
 (`SharedModule.forRoot` in `app.config.ts`, a populated shared-lib barrel). If not, tell the user to
 run `/mobilems:project-init` first. Hold `<PREFIX>` (from `tsconfig.base.json`; reference uses
-`@msr`) and the reference repo path (same one init used).
+own) and the reference repo path (same one init used).
+
+## Framework first — MANDATORY
+
+Read these before writing ANY component, service, pipe, directive or helper, and reuse what they
+list — re-implementing framework code is a defect, not a shortcut:
+
+0. [**The Framework API index**](https://github.com/smartsoft001/mobilems-framework/blob/main/README.md#-framework-api) — the map of every package to
+   its catalog. Start here when you do not already know which package owns what.
+1. The framework API catalog — `packages/shared/angular/README.md` in this repo, installed as
+   `node_modules/@smartsoft001-mobilems/angular/README.md` in a museum app ([browse](https://github.com/smartsoft001/mobilems-framework/blob/main/packages/shared/angular/README.md)).
+   This is the path `scripts/verify-module.sh` names when it fails.
+2. [`packages/articles/README.md`](https://github.com/smartsoft001/mobilems-framework/blob/main/packages/articles/README.md) — the package this module reuses
+3. `libs/shared/angular/README.md` — the app's own shared lib (built by `mobilems-project-init`)
+
+| Do not hand-roll                                             | Use                                                                                                                        |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| a masonry grid (`new Masonry(...)`, per-page masonry JS/CSS) | `<smart-mobilems-masonry-grid>` (`MasonryGridComponent`) with a `#masonryContentTpl`; the `Masonry` provider only feeds it |
+| filter state / hand-built `query` arrays                     | `FiltersBaseComponent<MuseumThematicPath>` + its `FiltersContext` accessors                                                |
+| list/detail plumbing (facade wiring, id-from-route)          | the `ArticlesListComponent` / `ArticlesItemComponent` base classes                                                         |
+| a paged publication reader's content blocks                  | `WidgetComponent` + the `ArticleWidgetType` map                                                                            |
+| media URLs, meta/OG tags, modals, WCAG                       | `FileUrlService`, `SeoService`/`MetaService`, `ModalService`, `WcagService`                                                |
+
+Anything the framework genuinely lacks goes into `libs/shared/angular` **once** (and into its
+README) — never a per-module copy. `scripts/verify-module.sh` fails the run on hand-rolled masonry.
 
 ## Steps
 

package/plugins/mobilems/skills/mobilems-thematic-publications/references/lib-contents.md

@@ -32,6 +32,17 @@ libs/museum-thematic-paths/
 > There is **no `src/__mocks__/` dir** in this lib (objects had one; thematic-paths does not). Copy
 > only what the reference has.
 
+`components/filters` **must** extend the framework base class rather than build `query` arrays by
+hand — that base is what wires the debounced writes back through `CrudFacade`:
+
+```ts
+export class FiltersComponent extends FiltersBaseComponent<MuseumThematicPath> {}
+```
+
+Read filter state through the inherited `context` accessors (`searchText`, `keywords`, `page`,
+`sort`), never by assembling a `query` yourself. `scripts/verify-module.sh` fails the run if this
+component does not extend `FiltersBaseComponent`.
+
 ## Domain entity (verbatim — thread nothing; pure types)
 
 Unlike objects' `MuseumObject extends MsObject`, this entity `implements` the local interfaces — it

package/plugins/mobilems/skills/mobilems-thematic-publications/references/module-and-routes.md

@@ -69,6 +69,32 @@ import { routes } from './thematic-paths.routes';
 export class MuseumThematicPathsModule {}
 ```
 
+> **The `Masonry` provider exists only to feed the framework's `MasonryGridComponent`.** It is DI
+> plumbing, not a grid — never call `new Masonry(...)`, keep a `MasonryInstance`, or re-implement the
+> layout/`reloadItems` dance in a page component. A hand-rolled CSS-grid or column layout is the same
+> defect. `scripts/verify-module.sh` fails the run on both.
+
+The list page renders the grid like this — copy this shape, it is the required one:
+
+```html
+<smart-mobilems-masonry-grid [list]="list()" [options]="{ gutter: 24 }">
+  <ng-template #masonryContentTpl>
+    <div class="masonry-grid-sizer"></div>
+    @for (item of list(); track item.id) {
+    <div class="masonry-item">
+      <app-thematic-paths-list-item [item]="item" />
+    </div>
+    }
+  </ng-template>
+</smart-mobilems-masonry-grid>
+```
+
+`.masonry-grid-sizer` and `.masonry-item` are required — they are the component's default
+`columnWidth` / `itemSelector`. The card (lib-contents.md) is the only module-specific part. Inputs,
+public methods and the SSR provider are documented in the framework catalog,
+[`packages/shared/angular/README.md`](https://github.com/smartsoft001/mobilems-framework/blob/main/packages/shared/angular/README.md#masonrygridcomponent)
+(installed as `node_modules/@smartsoft001-mobilems/angular/README.md`).
+
 > Contrast with `mobilems-objects` (`ObjectsSharedModule.forFeature` over `MsObject`, no
 > `reducerFactory`): here the module reuses `ArticlesSharedModule`, supplies `reducerFactory: getReducer`,
 > and there is deliberately **no `baseQuery`** in the config.