@smartsoft001-mobilems/claude-plugins 2.88.0 → 2.90.0

package/plugins/mobilems/skills/mobilems-devops-config/scripts/verify-devops.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+#
+# verify-devops.sh <workspace-root> <NODE_VERSION>
+#
+# Post-condition check for mobilems-devops-config. Asserts the ops/deployment layer landed and that
+# the node version is consistent across .nvmrc, the Dockerfile, and the workflows.
+# Portable to macOS system bash (3.2). Exit 0 = all pass; exit 1 = one or more checks failed.
+set -eu
+
+ROOT="${1:?usage: verify-devops.sh <workspace-root> <NODE_VERSION> [SITE_HOST]}"
+NODE_VERSION="${2:?usage: verify-devops.sh <workspace-root> <NODE_VERSION> [SITE_HOST]}"
+# Optional: this project's expected site host, so a carried-over SITE_URL is caught. No project
+# host is hardcoded in this script.
+SITE_HOST="${3:-}"
+cd "$ROOT" 2>/dev/null || { echo "ERROR: no such dir: $ROOT" >&2; exit 2; }
+
+fail=0
+pass() { echo "  PASS: $1"; }
+bad()  { echo "  FAIL: $1" >&2; fail=1; }
+exists() { [ -e "$1" ] && pass "$1" || bad "$1 missing"; }
+
+echo "== Docker =="
+exists apps/web/Dockerfile
+[ -f apps/web/Dockerfile ] && grep -q "server/server.mjs" apps/web/Dockerfile && pass "Dockerfile starts SSR server" || bad "Dockerfile CMD node server/server.mjs"
+
+echo "== GitHub Actions =="
+exists .github/actions/cached-deps/action.yml
+exists .github/workflows/development.yml
+exists .github/workflows/e2e.yml
+exists .github/workflows/push-to-client.yml
+exists .github/workflows/ai-plan.yml
+exists .github/workflows/ai-impl.yml
+exists .github/workflows/ci.yml.disabled
+# secrets are referenced, not hardcoded
+[ -f .github/workflows/development.yml ] && grep -q "secrets.GITLAB_TOKEN" .github/workflows/development.yml && pass "development.yml uses secrets" || bad "development.yml secrets.GITLAB_TOKEN"
+
+echo "== .github hygiene (references/github-hygiene.md) =="
+# agent config belongs in .claude/, not .github/ (Nx's Copilot-format scaffolding leftovers)
+STRAY=""
+for d in skills agents prompts instructions chatmodes copilot-instructions.md; do
+  [ -e ".github/$d" ] && STRAY="$STRAY .github/$d"
+done
+if [ -n "$STRAY" ]; then
+  bad "agent config left in .github (delete plugin duplicates, git mv bespoke ones to .claude/):$STRAY"
+else
+  pass ".github holds only workflows/actions/GitHub metadata"
+fi
+
+echo "== Update tooling =="
+exists tools/scripts/update.js
+grep -q '"update"' package.json && pass "npm update script" || bad 'package.json "update" script'
+# husky install via postinstall OR prepare
+if grep -qE '"(postinstall|prepare)"[[:space:]]*:[[:space:]]*"husky install"' package.json; then
+  pass "husky install hook"
+else
+  bad 'package.json postinstall/prepare = "husky install"'
+fi
+
+echo "== Env / lint / node =="
+exists .env.dev
+[ -f .env.dev ] && grep -q "MULTIMEDIA_URL" .env.dev && pass ".env.dev has MULTIMEDIA_URL" || bad ".env.dev MULTIMEDIA_URL"
+# SITE_URL drives og:url / sitemap.xml / robots.txt, so a value carried over from another project
+# ships that project's domain in this app's SEO. Pass this project's expected host as $3 to check it.
+if [ -n "${SITE_HOST:-}" ] && [ -f .env.dev ]; then
+  if grep -qE "^SITE_URL=https?://$SITE_HOST" .env.dev; then
+    pass "SITE_URL points at $SITE_HOST"
+  else
+    bad "SITE_URL does not point at the expected host ($SITE_HOST)"
+  fi
+fi
+# unreplaced template placeholders are worse than wrong values: the build silently ships '{{...}}'
+if [ -f .env.dev ] && grep -q "{{" .env.dev; then
+  bad ".env.dev still contains {{...}} placeholders"
+else
+  pass ".env.dev placeholders replaced"
+fi
+exists .eslintignore
+exists .nvmrc
+
+echo "== Node version consistency (expected: $NODE_VERSION) =="
+NVMRC="$(tr -d '[:space:]' < .nvmrc 2>/dev/null || true)"
+[ "$NVMRC" = "$NODE_VERSION" ] && pass ".nvmrc = $NODE_VERSION" || bad ".nvmrc is '$NVMRC', expected '$NODE_VERSION'"
+[ -f apps/web/Dockerfile ] && grep -q "node:$NODE_VERSION-alpine" apps/web/Dockerfile && pass "Dockerfile base image node:$NODE_VERSION" || bad "Dockerfile base image not node:$NODE_VERSION-alpine"
+# every workflow that pins a node-version should pin THIS version
+DRIFT=""
+for wf in .github/workflows/development.yml .github/workflows/e2e.yml; do
+  [ -f "$wf" ] || continue
+  if grep -qE "node-version:" "$wf" && ! grep -qE "node-version:[[:space:]]*'?${NODE_VERSION}'?" "$wf"; then
+    DRIFT="$DRIFT $wf"
+  fi
+done
+if [ -n "$DRIFT" ]; then bad "workflow node-version drift:$DRIFT"; else pass "workflow node-version matches $NODE_VERSION"; fi
+
+echo
+if [ "$fail" = 0 ]; then echo "VERIFY: all checks passed."; else echo "VERIFY: FAILED — fix the items above and re-run." >&2; fi
+exit "$fail"

package/plugins/mobilems/skills/mobilems-events/SKILL.md

@@ -23,7 +23,33 @@ its own `shell/angular`.
 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`; the reference
-MobilEMS app uses `@msr`) and the reference repo path (same one init used).
+MobilEMS app defines its 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. `libs/shared/angular/README.md` — the app's own shared lib (built by `mobilems-project-init`)
+
+Events is a standalone booking module (no feature package of its own), so it leans on the framework
+hardest:
+
+| 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 on the list route only feeds it |
+| filter/search state and `query` building                     | `FiltersContext` via `FiltersBaseComponent` (or `QueryFilterService` for plain query strings)                                                |
+| confirm/cancel dialogs                                       | `ModalService.open()` + `ModalRef` (and the shared `confirmation-modal` service)                                                             |
+| media URLs, meta/OG tags, dictionaries, WCAG, contrast       | `FileUrlService`, `SeoService`/`MetaService`, `DictionaryService`, `WcagService`, `ContrastService`                                          |
+| a calendar/date-picker helper duplicated per page            | the shared lib's `calendar` component — built once, reused                                                                                   |
+
+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-events/references/module-and-routes.md

@@ -89,6 +89,30 @@ export const eventsRoutes: Route[] = [
 ];
 ```
 
+> **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-events-grid-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`).
+
 > Route order matters: the specific reservation sub-routes (`:id/potwierdzenie`, `:id/anulowanie`,
 > `:id/booking`) come before the generic `:id/:slug` and `:id` detail routes, and the bare list route
 > `''` comes last. Keep this order.

package/plugins/mobilems/skills/mobilems-events/scripts/verify-module.sh

@@ -54,6 +54,49 @@ echo "== Foundation deps =="
 grep -q "@smartsoft001-mobilems/angular" package.json && pass "@smartsoft001-mobilems/angular present" || bad "@smartsoft001-mobilems/angular missing"
 grep -q "@smartsoft001-mobilems/models" package.json && pass "@smartsoft001-mobilems/models present" || bad "@smartsoft001-mobilems/models missing"
 
+echo "== Framework first (packages/shared/angular/README.md) =="
+LIBDIR="libs/museum-events/shell/angular/src/lib"
+# 1. masonry belongs to the framework's MasonryGridComponent — no module-level instances
+MAS="$(grep -rlnE "new Masonry\(|MasonryInstance" libs apps/web/src 2>/dev/null || true)"
+if [ -n "$MAS" ]; then
+  bad "hand-rolled masonry — render grids with <smart-mobilems-masonry-grid> (MasonryGridComponent):"
+  printf '        %s\n' $MAS >&2
+else
+  pass "no hand-rolled masonry instances"
+fi
+# 2. the Masonry provider exists ONLY to feed MasonryGridComponent. Providing it without ever
+#    rendering the component means the grid was hand-rolled some other way (CSS columns, flex, …),
+#    which the `new Masonry(` grep above cannot see.
+if grep -rq "provide: Masonry" "$LIBDIR" 2>/dev/null; then
+  if grep -rq "smart-mobilems-masonry-grid" "$LIBDIR" 2>/dev/null; then
+    pass "grids render via <smart-mobilems-masonry-grid>"
+  else
+    bad "module provides Masonry but never renders <smart-mobilems-masonry-grid> — hand-rolled grid"
+  fi
+fi
+# 3. a list page must render through the framework grid
+LISTP="$(find "$LIBDIR/pages" -maxdepth 1 -type d -name 'list*' 2>/dev/null || true)"
+if [ -n "$LISTP" ]; then
+  if grep -rq "smart-mobilems-masonry-grid" $LISTP 2>/dev/null; then
+    pass "list page renders via <smart-mobilems-masonry-grid>"
+  else
+    bad "list page does not render <smart-mobilems-masonry-grid> (README.md#masonrygridcomponent)"
+  fi
+fi
+# 4. filters must EXTEND the framework base class — `context.` alone proves nothing, and a
+#    differently-named dir must not silently skip the check
+FILT="$(find "$LIBDIR/components" -maxdepth 1 -type d \( -name 'filters*' -o -name 'search*' -o -name 'facet*' \) 2>/dev/null || true)"
+if [ -n "$FILT" ]; then
+  if grep -rqE "FiltersBaseComponent|QueryFilterService" $FILT 2>/dev/null; then
+    pass "filters use the framework filter API"
+  else
+    bad "filters use neither FiltersBaseComponent nor QueryFilterService — no ad-hoc query building:"
+    printf '        %s\n' $FILT >&2
+  fi
+else
+  pass "no filters component in this module"
+fi
+
 echo
 if [ "$fail" = 0 ]; then echo "VERIFY: all checks passed."; else echo "VERIFY: FAILED — fix the items above and re-run." >&2; fi
 exit "$fail"

package/plugins/mobilems/skills/mobilems-object-collections/SKILL.md

@@ -19,7 +19,30 @@ Collections is a list/detail view backed by `PublicCollectionsSharedModule.forFe
 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/public-collections/README.md`](https://github.com/smartsoft001/mobilems-framework/blob/main/packages/public-collections/README.md) — this module's package catalog
+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<PublicCollection>` + its `FiltersContext` accessors (`searchText`, `keywords`, `cycles`, `page`, `sort`, …) |
+| list/detail plumbing (facade wiring, id-from-route)          | the `PublicCollectionsListComponent` / `PublicCollectionsItemComponent` base classes                                              |
+| media URLs, meta/OG tags, filter dictionaries, modals, WCAG  | `FileUrlService`, `SeoService`/`MetaService`, `DictionaryService`, `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
 
@@ -27,10 +50,16 @@ run `/mobilems:project-init` first. Hold `<PREFIX>` (from `tsconfig.base.json`;
    `@smartsoft001-mobilems/public-collections-shell-angular`,
    `@smartsoft001-mobilems/public-collections-shell-dtos` (match the installed mobilems line).
    Resolve versions at run time; do not `npm install` unless asked. No extra third-party viewer deps.
-2. **Library** — create `libs/museum-collections/{domain,shell/angular}` per `references/lib-contents.md`:
-   copy the domain entity (`MuseumCollection extends PublicCollection`) and the shell
-   (`MuseumCollectionsModule`, routes, `components/filters`, `pages/{list,item}`, `services`), thread
-   `<PREFIX>`. Add the two `tsconfig.base.json` paths and the `museum-collections` commit scope.
+2. **Library** — scaffold `libs/museum-collections` with this package's Nx generator (deterministic — do
+   NOT copy files by hand when the generator is available):
+   ```bash
+   npx nx g @smartsoft001-mobilems/public-collections-shell-angular:museum-module \
+     --referenceRoot=<reference-repo> --prefix=<PREFIX>
+   ```
+   It copies the lib from the reference, threads `@<PREFIX>/`, adds both `tsconfig.base.json`
+   paths, normalizes `project.json` paths and copies the module's translation groups (pl+en).
+   Fallback (older framework line without the generator): do the same by hand per
+   `references/lib-contents.md`. The `museum-collections` commit scope registers automatically from the `libs/` dir name.
 3. **Module + routes** — see `references/module-and-routes.md`: `MuseumCollectionsModule` wraps
    `PublicCollectionsSharedModule.forFeature({ routing: false, config: { type: MuseumCollection, apiUrl, entity: 'publicCollections' } })`
    with the `Masonry` SSR factory and the `CrudService → CollectionsService` provider. Add the lazy
@@ -40,20 +69,23 @@ run `/mobilems:project-init` first. Hold `<PREFIX>` (from `tsconfig.base.json`;
    `components/collections-grid-item` (it imports `public-collections-domain`) in the shared lib and
    export it from `components/index.ts`. Collections contributes no widget-map entry and no model type
    (those are objects-only).
-5. **Verify** — run `scripts/verify-module.sh <workspace-root> <PREFIX>`: asserts the lib +
+5. **Translations** — copy the module's translation groups (`COLLECTIONS`) from the reference
+   repo's `apps/web/public/translations.json` into the app's file, for BOTH `pl` and `en`.
+   Complete group = every reference key present; every key referenced in the module's code
+   must exist in both languages — a raw `GROUP.key` rendered in the UI is a defect.
+6. **Verify** — run `REF_ROOT=<reference-repo> scripts/verify-module.sh <workspace-root> <PREFIX>`: asserts the lib +
    `MuseumCollection` entity exist, the `forFeature` is wired, the `kolekcje` route is registered
    (top-level + search child), the `collections-grid-item` component is built and exported, and the
    three public-collections deps are present. Fix and re-run.
 
-## Known QA pitfalls (from live deployments — fix while copying, not after)
+## Known pitfalls (fix while copying, not after)
 
-Each of these was a real Linear bug on a museum project built with this skill (Ostrowiec MOB-961/994,
-Tomaszów MOB-956). The cross-cutting rules live in `mobilems-project-init`
+The cross-cutting rules live in `mobilems-project-init`
 `references/qa-hardening.md`; these are the collections-specific ones:
 
 - **One card component, reused everywhere.** The home page and the collection detail must render the
   SAME shared `collections-grid-item` / object card components as the list views — a second ad-hoc
-  card on the home page was a High-priority bug (MOB-994). Never fork a card per page.
+  card on the home page is a defect. Never fork a card per page.
 - **No hardcoded UI strings.** The detail heading was shipped as a literal `Zbiory {{ title }}` and
   stayed Polish in EN — every static label goes through a translation key (PL + EN in
   `translations.json`). The list page needs a VISIBLE translated heading (not only `sr-only`), and
@@ -64,10 +96,10 @@ Tomaszów MOB-956). The cross-cutting rules live in `mobilems-project-init`
   objects.
 - **Search debounce 250 ms** in the filters (`@debounce(250)`), total count + shared
   `NextPageComponent` on the list — consistent with objects/news.
-- **Keyword/cycle chips wrap on 360 px** — chips caused page-level horizontal scroll on mobile.
-- **Heading font must cover Polish diacritics** — collection card titles rendered in a fallback
-  font because the configured serif (Bacasime Antique) lacks `ą ć ę ł ń ś ź ż`; verify the Tailwind
-  heading `fontFamily` is non-empty and latin-ext complete (see qa-hardening).
+- **Keyword/cycle chips must wrap at 360 px** — unwrapped chips cause page-level horizontal scroll.
+- **Heading font must cover Polish diacritics** — a serif lacking `ą ć ę ł ń ś ź ż` renders card
+  titles in a silent fallback; verify the Tailwind heading `fontFamily` is non-empty and latin-ext
+  complete (see qa-hardening).
 - **Warning-clean templates:** remove needless `?.` on non-nullable signals (NG8107) after copying.
 
 ## Notes

package/plugins/mobilems/skills/mobilems-object-collections/references/lib-contents.md

@@ -74,3 +74,14 @@ export class MuseumCollection extends PublicCollection {
 The `components/filters` component renders the keyword/cycle facets exposed by the entity's
 `connections` block; the list/detail rendering itself comes from `PublicCollectionsSharedModule`.
 No third-party viewer deps are needed (unlike the objects 3D tab).
+
+It **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<PublicCollection> {}
+```
+
+Read filter state through the inherited `context` accessors (`searchText`, `keywords`, `cycles`,
+`page`, `sort`), never by assembling a `query` yourself. `scripts/verify-module.sh` fails the run if
+this component does not extend `FiltersBaseComponent`.

package/plugins/mobilems/skills/mobilems-object-collections/references/module-and-routes.md

@@ -68,6 +68,32 @@ import { CollectionsService } from './services';
 export class MuseumCollectionsModule {}
 ```
 
+> **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">
+      <smart-collections-grid-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 (shared-components.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`).
+
 ## `collections.routes.ts`
 
 Identical shape to the objects routes (`:id/:slug` → Item, `:id` → Item, `''` → List).

package/plugins/mobilems/skills/mobilems-object-collections/scripts/check-translations.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * check-translations.js "<GROUP GROUP …>" [reference-root]
+ *
+ * Run from the workspace root (verify-module.sh cd's there). Verifies the
+ * module's translation groups in apps/web/public/translations.json:
+ *   1. each group exists and is non-empty in BOTH pl and en,
+ *   2. every literal GROUP.* key referenced in libs/ or apps/web/src exists
+ *      in both languages (dead references = defect),
+ *   3. with a reference root: every reference key of the group exists in the
+ *      generated file — missing keys are listed (the module is incomplete).
+ * Prints PASS/FAIL lines in the verify-module.sh idiom; exit 1 on any FAIL.
+ */
+const fs = require("fs");
+
+const [groupsArg, refRoot] = process.argv.slice(2);
+const groups = (groupsArg || "").split(/\s+/).filter(Boolean);
+if (!groups.length) { console.log("  FAIL: no translation groups given"); process.exit(1); }
+
+const TRANS = "apps/web/public/translations.json";
+let fail = 0;
+const pass = (m) => console.log(`  PASS: ${m}`);
+const bad = (m) => { console.log(`  FAIL: ${m}`); fail = 1; };
+
+const flat = (obj, prefix) => Object.entries(obj || {}).flatMap(([k, v]) =>
+  v && typeof v === "object" ? flat(v, `${prefix}.${k}`) : [`${prefix}.${k}`]);
+
+const readTrans = (p) => { try { return JSON.parse(fs.readFileSync(p, "utf8")).data.translations; } catch { return null; } };
+
+const gen = readTrans(TRANS);
+if (!gen) { bad(`cannot read ${TRANS}`); process.exit(1); }
+
+// 1. groups present + non-empty in both languages
+const genKeys = { pl: new Set(), en: new Set() };
+for (const lang of ["pl", "en"]) {
+  for (const g of groups) {
+    const keys = flat(gen[lang]?.[g], g);
+    keys.forEach((k) => genKeys[lang].add(k));
+    if (keys.length) pass(`${g} present in ${lang} (${keys.length} keys)`);
+    else bad(`${g} missing or empty in ${lang}`);
+  }
+}
+
+// 2. dead references — literal GROUP.* keys used in sources must exist.
+// Dynamic tails (`GROUP.${x}`) don't match the literal regex, and a matched
+// PREFIX that is a parent of existing keys counts as present.
+const walk = (dir) => {
+  let out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+    const p = `${dir}/${e.name}`;
+    if (e.isDirectory()) out = out.concat(walk(p));
+    else if (/\.(ts|html)$/.test(e.name)) out.push(p);
+  }
+  return out;
+};
+let src = "";
+for (const d of ["libs", "apps/web/src"]) {
+  if (fs.existsSync(d)) src += walk(d).map((f) => { try { return fs.readFileSync(f, "utf8"); } catch { return ""; } }).join("\n");
+}
+const re = new RegExp(`\\b(?:${groups.join("|")})(?:\\.[A-Za-z0-9_]+)+`, "g");
+const used = new Set(src.match(re) || []);
+const dead = { pl: [], en: [] };
+for (const key of used) {
+  for (const lang of ["pl", "en"]) {
+    const ks = genKeys[lang];
+    if (!ks.has(key) && ![...ks].some((k) => k.startsWith(`${key}.`))) dead[lang].push(key);
+  }
+}
+for (const lang of ["pl", "en"]) {
+  if (dead[lang].length) bad(`${lang}: keys referenced in code but missing in ${TRANS}: ${dead[lang].slice(0, 8).join(", ")}${dead[lang].length > 8 ? ` (+${dead[lang].length - 8})` : ""}`);
+  else pass(`no dead ${lang} references (${used.size} literal keys checked)`);
+}
+
+// 3. completeness vs reference
+if (refRoot) {
+  const ref = readTrans(`${refRoot}/apps/web/public/translations.json`);
+  if (!ref) bad(`cannot read reference translations under ${refRoot}`);
+  else {
+    for (const lang of ["pl", "en"]) {
+      const missing = groups.flatMap((g) => flat(ref[lang]?.[g], g)).filter((k) => !genKeys[lang].has(k));
+      if (missing.length) bad(`${lang}: ${missing.length} reference keys missing: ${missing.slice(0, 8).join(", ")}${missing.length > 8 ? " …" : ""}`);
+      else pass(`${lang}: all reference keys covered`);
+    }
+  }
+} else {
+  console.log("  SKIP: no reference root given — completeness vs reference not checked");
+}
+
+process.exit(fail);

package/plugins/mobilems/skills/mobilems-object-collections/scripts/verify-module.sh

@@ -9,6 +9,7 @@ set -eu
 
 ROOT="${1:?usage: verify-module.sh <workspace-root> <PREFIX>}"
 PREFIX="${2:?usage: verify-module.sh <workspace-root> <PREFIX>}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 cd "$ROOT" 2>/dev/null || { echo "ERROR: no such dir: $ROOT" >&2; exit 2; }
 
 fail=0
@@ -39,6 +40,59 @@ grep -q "@smartsoft001-mobilems/public-collections-domain" package.json && pass
 grep -q "@smartsoft001-mobilems/public-collections-shell-angular" package.json && pass "public-collections-shell-angular dep" || bad "public-collections-shell-angular dep missing"
 grep -q "@smartsoft001-mobilems/public-collections-shell-dtos" package.json && pass "public-collections-shell-dtos dep" || bad "public-collections-shell-dtos dep missing"
 
+echo "== Framework first (packages/shared/angular/README.md) =="
+LIBDIR="libs/museum-collections/shell/angular/src/lib"
+# 1. masonry belongs to the framework's MasonryGridComponent — no module-level instances
+MAS="$(grep -rlnE "new Masonry\(|MasonryInstance" libs apps/web/src 2>/dev/null || true)"
+if [ -n "$MAS" ]; then
+  bad "hand-rolled masonry — render grids with <smart-mobilems-masonry-grid> (MasonryGridComponent):"
+  printf '        %s\n' $MAS >&2
+else
+  pass "no hand-rolled masonry instances"
+fi
+# 2. the Masonry provider exists ONLY to feed MasonryGridComponent. Providing it without ever
+#    rendering the component means the grid was hand-rolled some other way (CSS columns, flex, …),
+#    which the `new Masonry(` grep above cannot see.
+if grep -rq "provide: Masonry" "$LIBDIR" 2>/dev/null; then
+  if grep -rq "smart-mobilems-masonry-grid" "$LIBDIR" 2>/dev/null; then
+    pass "grids render via <smart-mobilems-masonry-grid>"
+  else
+    bad "module provides Masonry but never renders <smart-mobilems-masonry-grid> — hand-rolled grid"
+  fi
+fi
+# 3. the ITEM page renders its objects grid through the framework grid — in the
+#    reference the collections LIST is a plain grid; masonry lives on the item page
+ITEMP="$(find "$LIBDIR/pages" -maxdepth 1 -type d -name 'item*' 2>/dev/null || true)"
+if [ -n "$ITEMP" ]; then
+  if grep -rq "smart-mobilems-masonry-grid" $ITEMP 2>/dev/null; then
+    pass "item page renders via <smart-mobilems-masonry-grid>"
+  else
+    bad "item page does not render <smart-mobilems-masonry-grid> (README.md#masonrygridcomponent)"
+  fi
+fi
+# 4. filters must EXTEND the framework base class — `context.` alone proves nothing, and a
+#    differently-named dir must not silently skip the check
+FILT="$(find "$LIBDIR/components" -maxdepth 1 -type d \( -name 'filters*' -o -name 'search*' -o -name 'facet*' \) 2>/dev/null || true)"
+if [ -n "$FILT" ]; then
+  if grep -rqE "FiltersBaseComponent" $FILT 2>/dev/null; then
+    pass "filters use the framework filter API"
+  else
+    bad "filters do not extend FiltersBaseComponent — no ad-hoc query building:"
+    printf '        %s\n' $FILT >&2
+  fi
+else
+  pass "no filters component in this module"
+fi
+
+echo "== Translations (REF_ROOT=${REF_ROOT:-unset}) =="
+# Groups: present in pl+en, no dead references, complete vs the reference repo
+# (export REF_ROOT=<reference-repo-root> to enable the completeness diff).
+if node "$SCRIPT_DIR/check-translations.js" "COLLECTIONS" "${REF_ROOT:-}"; then
+  pass "translation groups complete"
+else
+  bad "translation gaps — fix the FAIL lines above"
+fi
+
 echo
 if [ "$fail" = 0 ]; then echo "VERIFY: all checks passed."; else echo "VERIFY: FAILED — fix the items above and re-run." >&2; fi
 exit "$fail"

package/plugins/mobilems/skills/mobilems-objects/SKILL.md

@@ -20,7 +20,30 @@ map, audio, 3D model, animation, virtual walk) backed by `ObjectsSharedModule.fo
 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/objects/README.md`](https://github.com/smartsoft001/mobilems-framework/blob/main/packages/objects/README.md) — this module's package catalog
+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 in step 3 only feeds it |
+| filter state / hand-built `query` arrays                     | `FiltersBaseComponent<MsObject>` + its `FiltersContext` accessors (`searchText`, `keywords`, `page`, `sort`, `onlyImage`, …)         |
+| list/detail plumbing (facade wiring, id-from-route, PDF)     | the `ObjectsListComponent` / `ObjectsItemComponent` base classes                                                                     |
+| media URLs, meta/OG tags, filter dictionaries, modals, WCAG  | `FileUrlService`, `SeoService`/`MetaService`, `DictionaryService`, `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
 
@@ -28,10 +51,16 @@ run `/mobilems:project-init` first. Hold `<PREFIX>` (from `tsconfig.base.json`;
    `@smartsoft001-mobilems/objects-shell-dtos` (match the installed mobilems line) and
    `online-3d-viewer` (the 3D tab; `leaflet`/`openseadragon`/`swiper` are already foundation deps).
    Resolve versions at run time; do not `npm install` unless asked.
-2. **Library** — create `libs/museum-objects/{domain,shell/angular}` per `references/lib-contents.md`:
-   copy the domain entity/enums and the shell (`MuseumObjectsModule`, routes, `components/*`,
-   `pages/{list,item}`, `services`), thread `<PREFIX>`. Add the two `tsconfig.base.json` paths and the
-   `museum-objects` commit scope.
+2. **Library** — scaffold `libs/museum-objects` with this package's Nx generator (deterministic — do
+   NOT copy files by hand when the generator is available):
+   ```bash
+   npx nx g @smartsoft001-mobilems/objects-shell-angular:museum-module \
+     --referenceRoot=<reference-repo> --prefix=<PREFIX>
+   ```
+   It copies the lib from the reference, threads `@<PREFIX>/`, adds both `tsconfig.base.json`
+   paths, normalizes `project.json` paths and copies the module's translation groups (pl+en).
+   Fallback (older framework line without the generator): do the same by hand per
+   `references/lib-contents.md`. The `museum-objects` commit scope registers automatically from the `libs/` dir name.
 3. **Module + routes** — see `references/module-and-routes.md`: `MuseumObjectsModule` wraps
    `ObjectsSharedModule.forFeature({ routing: false, config: { type: MsObject, apiUrl, entity: 'objects' } })`
    with the `Masonry` SSR factory. Add the lazy `obiekty` route to `appRoutes` in
@@ -40,15 +69,18 @@ run `/mobilems:project-init` first. Hold `<PREFIX>` (from `tsconfig.base.json`;
    `objects-list-item`, and the object gallery widget (`widget/gallery-object`) in the shared lib +
    export them; register the object gallery widget in the widget content-type map (`GALLERY_OBJECT`);
    and add `ISpecificObject` (extends `MsObject`) to `models/objects.model.ts`.
-5. **Verify** — run `scripts/verify-module.sh <workspace-root> <PREFIX>`: asserts the lib exists, the
+5. **Translations** — copy the module's translation groups (`OBJECTS`, `DETAILS_PAGE`, `GALLERY`) from the reference
+   repo's `apps/web/public/translations.json` into the app's file, for BOTH `pl` and `en`.
+   Complete group = every reference key present; every key referenced in the module's code
+   must exist in both languages — a raw `GROUP.key` rendered in the UI is a defect.
+6. **Verify** — run `REF_ROOT=<reference-repo> scripts/verify-module.sh <workspace-root> <PREFIX>`: asserts the lib exists, the
    `obiekty` route is registered (top-level + search child), the objects shared components are built
    and exported, the widget map registers the object gallery widget, and `ISpecificObject` is present.
    Fix and re-run.
 
-## Known QA pitfalls (from live deployments — fix while copying, not after)
+## Known pitfalls (fix while copying, not after)
 
-Each of these was a real Linear bug on a museum project built with this skill (Ostrowiec MOB-960/991,
-Tomaszów MOB-949/993). The cross-cutting rules live in `mobilems-project-init`
+The cross-cutting rules live in `mobilems-project-init`
 `references/qa-hardening.md`; these are the objects-specific ones:
 
 - **Search debounce.** The panel full-text search (`app-objects-searchbar variant="panel"`) must
@@ -63,7 +95,7 @@ Tomaszów MOB-949/993). The cross-cutting rules live in `mobilems-project-init`
   is valid; `Number('') === 0` — reject empty strings explicitly). Duplicating the predicate in two
   components caused a "map never renders" bug.
 - **Field labels match the client's field spec everywhere** — list card, detail and filters must use
-  the same names (QA rejected "Materiał" vs "Tworzywo", "Miejsca:" vs "Miejsce powstania").
+  the same names (e.g. do not render "Materiał" where the mockup says "Tworzywo").
 - **Keywords section** maps the API `tags[]` field (not `keywords[]`) and renders clickable links
   that filter the list.
 - **Warning-clean templates:** after copying, remove needless `?.` on non-nullable signals (NG8107)