@smartsoft001-mobilems/claude-plugins 2.88.0 → 2.90.0

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

@@ -62,6 +62,30 @@ import { routes } from './objects.routes';
 export class MuseumObjectsModule {}
 ```
 
+> **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-objects-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`).
+
 ## `objects.routes.ts`
 
 ```ts

package/plugins/mobilems/skills/mobilems-objects/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-objects/scripts/verify-module.sh

@@ -8,6 +8,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
@@ -46,6 +47,58 @@ echo "== Deps =="
 grep -q "@smartsoft001-mobilems/objects-domain" package.json && pass "objects-domain dep" || bad "objects-domain dep missing"
 grep -q "online-3d-viewer" package.json && pass "online-3d-viewer dep" || bad "online-3d-viewer dep missing"
 
+echo "== Framework first (packages/shared/angular/README.md) =="
+LIBDIR="libs/museum-objects/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" $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" "OBJECTS DETAILS_PAGE GALLERY" "${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-partners/SKILL.md

@@ -23,7 +23,31 @@ REUSES the Articles shared module (like the thematic-paths module) but with its
 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) +
+   [`packages/objects/README.md`](https://github.com/smartsoft001/mobilems-framework/blob/main/packages/objects/README.md) — the packages 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<MuseumPartner>` + its `FiltersContext` accessors                                                     |
+| list/detail plumbing (facade wiring, id-from-route)          | the `ArticlesListComponent` / `ArticlesItemComponent` 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
 
@@ -48,7 +72,11 @@ run `/mobilems:project-init` first. Hold `<PREFIX>` (from `tsconfig.base.json`;
    `partnerzy` route to the `appRoutes` array in `apps/web/src/app/app.routes.ts` as a top-level
    route, and a matching child under the `wyszukaj/:text` search route (partners appears in site
    search).
-4. **Verify** — run `scripts/verify-module.sh <workspace-root> <PREFIX>`: asserts the lib + entity
+4. **Translations** — copy the module's translation groups (`PARTNERS`) 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.
+5. **Verify** — run `REF_ROOT=<reference-repo> scripts/verify-module.sh <workspace-root> <PREFIX>`: asserts the lib + entity
    exist, both tsconfig paths are added, `ArticlesSharedModule.forFeature` is wired with
    `entity: 'partners'` + `reducerFactory: getReducer`, the `+state/partners.reducer.ts` exports
    `getReducer`, the `components/{grid-item,list-item}` cards are present in the partners lib, the

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

@@ -66,6 +66,30 @@ import { SERVICES } from './services';
 export class MuseumPartnersModule {}
 ```
 
+> **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-partners-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`).
+
 > Contrast with `mobilems-objects` (`ObjectsSharedModule.forFeature` over `MsObject`, no
 > `reducerFactory`): here the module reuses `ArticlesSharedModule`, supplies `type: Article` with
 > `reducerFactory: getReducer`, and there is deliberately **no `baseQuery`** in the config.

package/plugins/mobilems/skills/mobilems-partners/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-partners/scripts/verify-module.sh

@@ -10,6 +10,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
@@ -54,6 +55,58 @@ grep -q "@smartsoft001-mobilems/articles-shell-angular" package.json && pass "ar
 grep -q "@smartsoft001-mobilems/articles-shell-dtos" package.json && pass "articles-shell-dtos dep" || bad "articles-shell-dtos dep missing"
 grep -q "@smartsoft001-mobilems/objects-domain" package.json && pass "objects-domain dep" || bad "objects-domain dep missing"
 
+echo "== Framework first (packages/shared/angular/README.md) =="
+LIBDIR="libs/museum-partners/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" $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" "PARTNERS" "${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-project-init/SKILL.md

@@ -29,6 +29,42 @@ and `mobilems-thematic-publications`, each of which adds its own library, shared
 package, and routes. Keeping feature code out of the foundation is the layering rule that lets the
 foundation build standalone (its shared library imports no feature package).
 
+## Framework first — MANDATORY
+
+The museum app builds **on** the framework, not beside it. Before writing or copying any component,
+service, pipe, directive or helper, read:
+
+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-init.sh` names when it fails.
+2. The [models catalog](https://github.com/smartsoft001/mobilems-framework/blob/main/packages/shared/models/README.md).
+
+Reuse what they list. Re-implementing framework code is a defect, not a shortcut.
+
+This applies with force in **reference mode**: the reference repo predates parts of the framework, so
+some of its shared components duplicate framework exports. When a reference file re-implements
+something the catalog already provides, **use the framework export instead of copying the file**:
+
+| Reference pattern to drop                                                    | Framework export to use                                     |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| a hand-rolled masonry grid (`new Masonry(...)`, per-page `.masonry-item` JS) | `MasonryGridComponent` (`<smart-mobilems-masonry-grid>`)    |
+| bespoke filter state / hand-built `query` arrays                             | `FiltersBaseComponent<T>` + `FiltersContext<T>`             |
+| an ad-hoc media/thumbnail URL builder                                        | `FileUrlService.get(...)` (`'cache' \| 'big' \| 'noCache'`) |
+| local meta/OG tag writers                                                    | `SeoService` / `MetaService`                                |
+| a local dictionary fetcher for filters                                       | `DictionaryService` (lowercase keys)                        |
+| a local WCAG/contrast state store                                            | `WcagService` / `ContrastService` / `StyleService`          |
+| a bespoke modal host                                                         | `ModalService.open()` + `ModalRef`                          |
+| a static-page loader                                                         | `PageStaticComponent` base class                            |
+
+Everything the framework does **not** provide goes into the app's shared lib
+(`libs/shared/angular`) exactly once — pipes, tools, directives, interceptors (see
+`references/shared-lib.md`) — and every module reuses it from there. If you find a shared-lib item
+that clearly belongs in the framework, name it in the final report so it can be upstreamed.
+
 ## Steps
 
 ### 0. Precondition — confirm a scaffold-nx-workspace base
@@ -42,7 +78,8 @@ run `/smart:scaffold-nx-workspace` first — do not try to create the Nx workspa
 
 The base already derived/confirmed/threaded the import-alias prefix. Read it from
 `tsconfig.base.json` `paths` — the key `@<PREFIX>/angular`. Hold `<PREFIX>`; thread it into every
-copied file (the reference repo uses `@msr`, so replacing `@msr` → `@<PREFIX>` is the main rewrite).
+copied file (replacing the reference repo's own alias with `@<PREFIX>` is the main rewrite; read it
+from that repo's `tsconfig.base.json`).
 
 ### 2. Choose mode
 
@@ -100,11 +137,33 @@ the static pages (`home`, `page`, `contact`, `search`, `not-found`) + their reso
 catch-all). Each module skill adds its own feature route to the `appRoutes` array when it runs
 (`article-preview` is articles-coupled — `mobilems-articles` adds it, not the foundation).
 
-### 9. QA hardening — SEO, i18n, WCAG, branding
+### 9. Branding + SEO reset — strip the reference museum's identity
+
+**Mandatory in BOTH modes.** Step 4 already wrote the neutral token set, so a foundation-only app is
+brand-clean by construction and this step only applies the client's spec if there is one. In
+reference mode it does the real work: everything copied so far carries the _source project's_ brand
+— its fonts, palette, logos and social image, its SEO/meta strings and its domain. Apply
+`references/branding-reset.md` before QA hardening — it enumerates every carrier (styles, assets,
+SEO, translations, configs) and how to reset it.
+
+Ask the user (`AskUserQuestion`) once, up front:
+
+- **Brand spec available?** → apply it (fonts, palette, logos, social image, site name/domain).
+- **No spec (default)** → apply the **neutral token set**: full-latin-ext fonts (Playfair Display for
+  headings, Inter for body), a neutral grey/accent palette with every text pair ≥4.5:1, placeholder
+  logo + `no-image` + social image, generic site name/description keys.
+
+Either way this is a **token-only** change, and there are exactly two files that carry the tokens:
+`tailwind.config.js` (`theme.extend.colors` + `theme.extend.fontFamily`) and
+`apps/web/src/styles.scss` (`@font-face` + the metric-override fallbacks). There is no CSS-custom-property
+theme layer in this stack — do not go looking for one. Never touch layout classes, DOM structure,
+component inputs, API field mapping, dictionary keys or route paths. The app must look re-skinned,
+not re-built.
+
+### 10. QA hardening — SEO, i18n, WCAG, branding
 
-Apply `references/qa-hardening.md` — a checklist distilled from real QA bug reports on live museum
-deployments. The copied foundation carries the _reference museum's_ identity, so this step removes
-leftovers and closes the recurring gaps QA always finds:
+Apply `references/qa-hardening.md`. The copied foundation carries the _source project's_ identity,
+so this step removes leftovers and closes the recurring SEO/i18n/WCAG gaps:
 
 - dynamic `/sitemap.xml` + `/robots.txt` SSR endpoints driven by `SITE_URL` (never static copies —
   they shipped another museum's domain twice),
@@ -116,12 +175,12 @@ leftovers and closes the recurring gaps QA always finds:
 - warning-clean build & console (NG8107/NG8112/NG8113/NG0100/NG0913, Swiper loop, duplicate API
   calls).
 
-### 10. .claude extension
+### 11. .claude extension
 
 Apply `references/claude-config.md`: add `flow@mobilems` to `enabledPlugins`, grow the
 MobilEMS-specific permissions / MCP allow-lists, and seed `tools/specs` + `tools/prompts` pointers.
 
-### 11. Verify
+### 12. Verify
 
 Run `scripts/verify-init.sh <workspace-root> <PREFIX>`. It asserts the delta landed (Tailwind,
 multimediaUrl, MobilEMS providers, populated shared-lib barrel), the QA-hardening basics (sitemap +
@@ -135,7 +194,8 @@ robots endpoints, favicon, non-empty heading font), AND the foundation is self-c
 - **Reference mode (default):** copies the shared lib + pages from a real MobilEMS repo and threads
   the prefix. This is the only mode that regenerates the full foundation, because the shared lib is
   not in npm.
-- **Foundation-only (fallback):** do steps 1, 3, 4, 5, 9 (deps, Tailwind, env, .claude) and scaffold a
+- **Foundation-only (fallback):** do steps 1, 3, 4, 5, 9 and 11 (prefix, deps, Tailwind, env,
+  branding reset, .claude) and scaffold a
   reduced `app.config.ts` that does NOT import local shared-lib code (omit the interceptors + the
   `App` shell that need it). Leave a `MOBILEMS-FOUNDATION-TODO.md` listing what reference mode would
   have copied (shared lib, pages, full app.config, app shell) so the user can supply a reference