@smartsoft001-mobilems/claude-plugins 2.86.0 → 2.88.0

package/plugins/mobilems/skills/mobilems-project-init/references/app-shell.md

@@ -0,0 +1,115 @@
+# App shell + static pages + routes
+
+Build the root `App` component, the static pages, and the app routing by copying from the reference's
+`apps/web/src/app` and threading `<PREFIX>`. The foundation owns the shell, the static pages, and the
+routing table's static routes; each feature module skill adds its own routes.
+
+## App root — `app.ts` / `app.html` / `app.scss`
+
+Copy verbatim and thread `<PREFIX>`. The root component imports the `COMPONENTS` array +
+`SkipLinksComponent` from `@<PREFIX>/angular`, injects `ConfigsFacade` + `SeoService` (from
+`@smartsoft001-mobilems/angular`), `LocalStorageService` (shared lib) and `Router`; it inits the
+language, loads the global `Config` in `ngOnInit`, and focuses `#skip-links` on each `NavigationEnd`.
+
+> **QA gotcha (skip links):** the copied skip-link labels/targets describe the _reference_ museum's
+> sections — a project shipped skip links that still said "Światowid". Rewrite them for this app's
+> actual sections and localize them (PL/EN keys). See `references/qa-hardening.md` §1.
+> `app.html`:
+
+```html
+<app-skip-links></app-skip-links>
+<app-app [options]="options">
+  <header tabindex="-1"><app-header></app-header></header>
+  <footer><app-footer></app-footer></footer>
+</app-app>
+```
+
+## Static pages
+
+Copy `pages/{home,page,contact,search,not-found}` + the `home` and `page` resolvers, and thread
+`<PREFIX>`. These use only foundation shared components:
+
+- `home.component` uses the foundation carousels (`NewObjectsCarouselComponent`,
+  `NewsCarouselComponent`, `PartnersCarouselComponent`) and the `IObject`/`IArticle`/`IPartner` types
+  from the shared `models/` dir, plus the `DataService` home loaders — all foundation code (see
+  `references/shared-lib.md`). The home page renders fully; its carousels populate from the API at
+  runtime. **QA gotchas:** home sections must reuse the SAME shared card components as the module
+  list pages (an ad-hoc home card was a High bug); Swiper `loop` only when there are enough slides
+  for `slidesPerView` (else a console warning on every load); don't fire the same home API call
+  multiple times on load (`object-of-the-week` went out 3× — share/replay it). See
+  `references/qa-hardening.md` §6–7.
+- `search.component` renders results through a `<router-outlet>`; it has no feature import.
+
+Run a feature-package grep over the pages you copy as a guard. **Do not copy `article-preview`** — the
+reference's `article-preview` page imports `@smartsoft001-mobilems/articles-domain` (it previews an
+Article), so it is feature code, not foundation. The `mobilems-articles` skill builds it (and its
+route) when it adds an article module. If your reference has any other page that imports a feature
+package, leave it for the owning module skill too.
+
+## `app.routes.ts` — the app routing table
+
+Build `appRoutes` with the app's static routes — home, dynamic pages, contact, search, and the
+catch-all. Each feature module skill adds its own route (a lazy `loadChildren`) to this `appRoutes`
+array and a matching child under the `wyszukaj/:text` search route when it runs (and `mobilems-articles`
+adds the `article-preview` route).
+
+```ts
+import { Route } from '@angular/router';
+
+import { homeResolver } from './pages/home/home.resolver';
+import { pageResolver } from './pages/page/page.resolver';
+
+export const appRoutes: Route[] = [
+  { path: '', pathMatch: 'full', redirectTo: 'strona-glowna' },
+  {
+    path: 'strona/:id',
+    loadComponent: () =>
+      import('./pages/page/page.component').then((m) => m.PageComponent),
+    resolve: { pageData: pageResolver },
+  },
+  {
+    path: 'strona/:id/:slug',
+    loadComponent: () =>
+      import('./pages/page/page.component').then((m) => m.PageComponent),
+    resolve: { pageData: pageResolver },
+  },
+  {
+    path: 'strona-glowna',
+    loadComponent: () =>
+      import('./pages/home/home.component').then((m) => m.HomeComponent),
+    resolve: { pageData: homeResolver },
+  },
+  {
+    path: 'kontakt',
+    loadComponent: () =>
+      import('./pages/contact/contact.component').then(
+        (m) => m.ContactComponent,
+      ),
+  },
+  {
+    path: 'wyszukaj',
+    children: [
+      {
+        path: ':text',
+        loadComponent: () =>
+          import('./pages/search/search.component').then(
+            (m) => m.SearchComponent,
+          ),
+        children: [{ path: '', redirectTo: 'obiekty', pathMatch: 'full' }],
+      },
+    ],
+  },
+  {
+    path: '**',
+    loadComponent: () =>
+      import('./pages/not-found/not-found.component').then(
+        (m) => m.NotFoundComponent,
+      ),
+  },
+];
+```
+
+> The search view defaults to the objects results (`redirectTo: 'obiekty'`); the route resolves once
+> the objects module is present. A module skill adds its route by inserting a `loadChildren` entry
+> into `appRoutes` (top level) and into the `wyszukaj/:text` `children` array, immediately before the
+> `{ path: '', redirectTo: 'obiekty' }` default — see each module skill's `module-and-routes.md`.

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

@@ -0,0 +1,44 @@
+# .claude extension — flow@mobilems + MobilEMS perms
+
+The base seeded a generic `.claude/settings.json` (smart@smartsoft + nx plugins, safety/audit hooks,
+a generic allow-list). MobilEMS adds the `flow@mobilems` plugin and the museum-specific
+permission / MCP allow-lists. **Extend, do not replace** the base file — keep its hooks and `env`.
+
+## `.claude/settings.json`
+
+1. **`enabledPlugins`** — add `flow@mobilems` (keep the existing `smart@smartsoft` + `nx@nx-claude-plugins`):
+   ```json
+   "enabledPlugins": {
+     "flow@mobilems": true,
+     "smart@smartsoft": true,
+     "nx@nx-claude-plugins": true
+   }
+   ```
+2. **`permissions.allow`** — add the MobilEMS working set on top of the base git/nx/fs allows:
+   - Playwright MCP (`mcp__playwright__browser_*`) + accessibility-scanner MCP
+     (`mcp__accessibility-scanner__*`) — used by the UI / a11y skills.
+   - `WebSearch`, and `WebFetch(domain:…)` for `www.npmjs.com`, `github.com`,
+     `docs.anthropic.com`, `linear.app`, plus the project's own museum portal domain (ask the user
+     for it, or leave a placeholder comment) and `localhost`.
+   - `Bash(npm start)`, `Bash(nx:*)`, `Bash(lsof:*)`, `Bash(mkdir:*)` for serve/screenshot flows.
+   - Keep `permissions.ask` (`git commit`/`git push`/`gh pr create`) from the base.
+3. **`extraKnownMarketplaces`** — keep the base's `nx-claude-plugins`. The `mobilems` and `smart`
+   marketplaces are resolved from the installed `@smartsoft001*/claude-plugins` packages.
+
+> Don't copy the reference's full domain allow-list verbatim — it carries one museum's specific
+> hosts (its own portal domain, project n8n/maia webhooks). Seed the generic-useful entries and let
+> the project grow its own.
+
+## tools/specs + tools/prompts
+
+Seed pointers so the museum conventions are discoverable (the framework repo keeps the canonical
+copies under `tools/specs/{layers,styles,tests}.md` + `tools/prompts/*`). Either copy those files
+from the reference repo, or drop a short `tools/README.md` linking to them. These are documentation
+aids — not required for the build, so keep this light.
+
+## CLAUDE.md / AGENTS.md
+
+The base wrote a trimmed generic `CLAUDE.md` + the Nx `AGENTS.md`. Optionally append a short
+"MobilEMS" section to `CLAUDE.md` noting: feature modules are added by the `mobilems-<module>`
+skills, styling is Tailwind (`smart-` prefix) on scss, and runtime env adds `multimediaUrl`. Keep it
+brief — the authoritative guidance lives in the plugin skills.

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

@@ -0,0 +1,203 @@
+# 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
+`app.routes.server.ts` stay as the base emitted them.
+
+The imports from `@<PREFIX>/angular` (`LanguageInterceptor`, `PreviewAuthInterceptor`,
+`SsrTimeoutInterceptor`, `LocalStorageService`, `EnvironmentService`) come from the shared lib
+populated in step 7 — so in **foundation-only** mode, omit the three interceptor providers and the
+`@<PREFIX>/angular` interceptor imports (they don't exist yet).
+
+```ts
+import {
+  HTTP_INTERCEPTORS,
+  HttpClient,
+  provideHttpClient,
+  withFetch,
+  withInterceptorsFromDi,
+} from '@angular/common/http';
+import {
+  ApplicationConfig,
+  Injectable,
+  provideBrowserGlobalErrorListeners,
+  provideZonelessChangeDetection,
+  importProvidersFrom,
+  inject,
+  provideEnvironmentInitializer,
+  isDevMode,
+  provideAppInitializer,
+} from '@angular/core';
+import {
+  provideClientHydration,
+  withEventReplay,
+  withI18nSupport,
+} from '@angular/platform-browser';
+import { provideRouter, withInMemoryScrolling } from '@angular/router';
+import { EffectsModule, provideEffects } from '@ngrx/effects';
+import { provideStore, StoreModule } from '@ngrx/store';
+import { provideStoreDevtools } from '@ngrx/store-devtools';
+import {
+  InterpolatableTranslationObject,
+  TranslateModule,
+  TranslateService,
+} from '@ngx-translate/core';
+import {
+  AppService,
+  ErrorService,
+  NgrxSharedModule,
+  StyleService,
+} from '@smartsoft001/angular';
+import {
+  ISearchData,
+  SEARCH_CONFIG_TOKEN,
+  SharedModule,
+} from '@smartsoft001-mobilems/angular';
+import { MasonryModule } from '@thisissoon/angular-masonry';
+import { catchError, firstValueFrom, map, of, timeout } from 'rxjs';
+
+import {
+  environment,
+  EnvironmentService,
+  LanguageInterceptor,
+  LocalStorageService,
+  PreviewAuthInterceptor,
+  SsrTimeoutInterceptor,
+} from '@<PREFIX>/angular';
+
+import { appRoutes } from './app.routes';
+
+@Injectable()
+class NoOpAppService extends AppService {
+  override initTitle(): void {
+    // No-op: disable AppService.initTitle() which overrides
+    // page titles set by components via SeoService.updateTitle()
+  }
+}
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideClientHydration(withEventReplay(), withI18nSupport()),
+    provideBrowserGlobalErrorListeners(),
+    provideZonelessChangeDetection(),
+    provideRouter(
+      appRoutes,
+      withInMemoryScrolling({ scrollPositionRestoration: 'top' }),
+    ),
+    provideHttpClient(withFetch(), withInterceptorsFromDi()),
+    { provide: HTTP_INTERCEPTORS, useClass: LanguageInterceptor, multi: true },
+    {
+      provide: HTTP_INTERCEPTORS,
+      useClass: PreviewAuthInterceptor,
+      multi: true,
+    },
+    {
+      provide: HTTP_INTERCEPTORS,
+      useClass: SsrTimeoutInterceptor,
+      multi: true,
+    },
+    importProvidersFrom(
+      StoreModule.forRoot(
+        {},
+        {
+          runtimeChecks: {
+            strictStateImmutability: false,
+            strictActionImmutability: false,
+          },
+        },
+      ),
+      MasonryModule.forRoot(),
+      TranslateModule.forRoot(),
+      EffectsModule.forRoot([]),
+      NgrxSharedModule,
+      SharedModule.forRoot({
+        apiUrl: environment.apiUrl,
+        multimediaUrl: environment.multimediaUrl,
+        mainLogoPath: 'logo.png',
+        styleVariables: {},
+      }),
+    ),
+    { provide: StyleService, useClass: StyleService },
+    { provide: AppService, useClass: NoOpAppService },
+    {
+      provide: ErrorService,
+      useValue: {
+        log: (err: any) => {
+          console.error('Global error handler:', err);
+        },
+      },
+    },
+    provideEnvironmentInitializer(() => {
+      const envService = inject(EnvironmentService);
+      envService.init();
+    }),
+    provideStore(),
+    provideEffects(),
+    provideStoreDevtools({
+      maxAge: 25,
+      logOnly: !isDevMode(),
+      autoPause: true,
+      trace: true,
+      traceLimit: 75,
+    }),
+    {
+      provide: SEARCH_CONFIG_TOKEN,
+      useValue: {
+        apiUrl: environment.apiUrl,
+        searchMap: (txt: string, data: ISearchData) => {
+          return {
+            news: `${environment.apiUrl}search/Article/page/1?maxPerPage=1&filter[phrase]=${encodeURIComponent(txt)}&filter[template]=AKTUALNO%C5%9ACI`,
+            articles: `${environment.apiUrl}search/Article/page/1?maxPerPage=1&filter[phrase]=${encodeURIComponent(txt)}&filter[template]=POZOSTAŁE`,
+            partners: `${environment.apiUrl}dictionary/Department/search/page/1?maxPerPage=999&sort=random&_type=query&q=${encodeURIComponent(txt)}`,
+          };
+        },
+      },
+    },
+    provideAppInitializer(async () => {
+      const httpClient = inject(HttpClient);
+      const translateService = inject(TranslateService);
+      const localStorageService = inject(LocalStorageService);
+
+      // Initialize language before fetching translations so the
+      // language interceptor sends the correct Accept-Language header.
+      localStorageService.initLang();
+
+      async function fetchTranslations() {
+        const url = environment.production
+          ? environment.apiUrl + 'setting/theme'
+          : '/api/translations';
+
+        const translations = (await firstValueFrom(
+          httpClient.get<{ data: any }>(url).pipe(
+            timeout(5000),
+            map((response) => {
+              return response?.data?.translations ?? { en: {}, pl: {} };
+            }),
+            catchError(() => of(null)),
+          ),
+        )) as {
+          en: InterpolatableTranslationObject;
+          pl: InterpolatableTranslationObject;
+        } | null;
+
+        if (!translations || !translations.en || !translations.pl) {
+          console.warn('Translations are missing or malformed:', translations);
+          return;
+        }
+
+        translateService.setTranslation('en', translations.en);
+        translateService.setTranslation('pl', translations.pl);
+      }
+
+      await fetchTranslations();
+    }),
+  ],
+};
+```
+
+## Notes
+
+- `searchMap` is plain URL-string config — keep it verbatim even though it references `partners`
+  (out of scope) and `news`/`articles` (added later). It's runtime config, not an import dependency.
+- The `news`/`articles` template values (`AKTUALNO%C5%9ACI` = AKTUALNOŚCI, `POZOSTAŁE`) match the
+  `baseQuery` the `mobilems-articles` skill threads into `ArticlesSharedModule.forFeature`.

package/plugins/mobilems/skills/mobilems-project-init/references/npm-deps.md

@@ -0,0 +1,66 @@
+# npm dependencies — the MobilEMS foundation set
+
+Add these to the workspace root `package.json` `dependencies`. **Resolve every version at run
+time — never hardcode.** Anchor on the installed `@smartsoft001/angular` line (the same anchor
+`scaffold-nx-workspace` used): read its installed `package.json` version, or
+`npm view @smartsoft001/<pkg> version`. The `@smartsoft001*` libs move together; match their lines.
+
+## Add in project-init (foundation — used by the shared lib + app.config)
+
+**Framework (smartsoft001 + MobilEMS shared):**
+
+- `@smartsoft001/angular`
+- `@smartsoft001/crud-shell-angular`
+- `@smartsoft001/domain-core`
+- `@smartsoft001/models`
+- `@smartsoft001/utils`
+- `@smartsoft001-mobilems/angular` (provides `SharedModule`, `SeoService`, `ConfigsFacade`, `SEARCH_CONFIG_TOKEN`)
+- `@smartsoft001-mobilems/models` (provides `Config`, `Page`, `PageSlide`, `MsFile`)
+
+**State + i18n:**
+
+- `@ngrx/store`, `@ngrx/effects`, `@ngrx/store-devtools`, `@ngrx/signals`
+- `@ngx-translate/core`
+
+**Shared-UI / runtime libraries** (used by **generic** shared-lib components, so they are
+foundation deps — verified against the reference):
+
+- `@thisissoon/angular-masonry` + `masonry-layout` (masonry grids; `MasonryModule.forRoot()` in app.config)
+- `swiper` (generic `slider` component)
+- `leaflet` + `@types/leaflet` (generic `map` component + `styles.scss` `leaflet.css` import)
+- `openseadragon` + `@types/openseadragon` (generic `gallery/gallery-fullscreen` deep-zoom)
+- `@angular/cdk` (`BreakpointObserver` in the home carousels; the `orientation` service)
+- `moment` + `moment-timezone` (date handling across shared components)
+
+The runtime libraries go in `dependencies`; their `@types/*` packages (`@types/leaflet`,
+`@types/openseadragon`) go in `devDependencies`. Pin `@angular/cdk` to the workspace's Angular line
+(`@angular/core` version). `@angular/forms` is used by the shared filter components — it normally
+comes with the Angular base; ensure it's present (same Angular line) and add it if the base lacks it.
+
+> `express` + `dotenv` are already present from the base `server.ts` — verify, don't re-add.
+
+## Feature packages — added by the module skills, not here
+
+Each module skill adds its own feature packages when it builds that module:
+
+| Package(s)                                                                             | Added by                      |
+| -------------------------------------------------------------------------------------- | ----------------------------- |
+| `@smartsoft001-mobilems/objects-{domain,shell-angular,shell-dtos}`, `online-3d-viewer` | `mobilems-objects`            |
+| `@smartsoft001-mobilems/public-collections-{domain,shell-angular,shell-dtos}`          | `mobilems-object-collections` |
+| `@smartsoft001-mobilems/articles-{domain,shell-angular,shell-dtos}`                    | `mobilems-articles`           |
+
+Keep these out of the foundation: a feature package belongs with the feature shared components that
+use it, so the foundation library builds on its own.
+
+## Resolution recipe
+
+```bash
+# anchor line (e.g. 2.122.0 → use ^2.122.0 for @smartsoft001/*, the matching mobilems line for @smartsoft001-mobilems/*)
+npm view @smartsoft001/angular version
+npm view @smartsoft001-mobilems/angular version
+# third-party: take the current published line unless the base already pinned a compatible one
+npm view <pkg> version
+```
+
+Write `^<resolved>` ranges (matching the reference's style). Do not run `npm install` unless the
+user approves (skip during eval).

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

@@ -0,0 +1,124 @@
+# QA hardening — lessons from live museum deployments
+
+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
+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.
+
+## 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.
+- **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").
+- **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).
+- **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
+  copies trigger Angular `NG0913` warnings and hurt LCP.
+
+## 2. Dynamic sitemap + robots endpoints (server.ts)
+
+Pattern proven in MOB-948 — 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`:
+
+- Register `GET /sitemap.xml` and `GET /robots.txt` **after** `/api/translations` but **before**
+  `express.static` and the `'/**'` SSR catch-all — otherwise SSR answers with HTML and status 200
+  and the endpoints "work" only apparently.
+- Normalize `SITE_URL`: strip trailing `/`, prepend `https://` when the schema is missing; fall back
+  to the request host when the env var is unset.
+- Headers: `application/xml; charset=utf-8` / `text/plain; charset=utf-8`,
+  `Cache-Control: public, max-age=3600`.
+- Sitemap content: home + the module list pages (`/strona-glowna`, `/obiekty`, `/kolekcje`, …). Do
+  **not** include CMS static pages (`/strona/:id`) — their ids are CMS-assigned and go stale.
+- `robots.txt` points `Sitemap:` at the same `SITE_URL`.
+
+## 3. SEO meta (home + every routed page)
+
+- `<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
+  `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`.
+
+## 4. i18n invariants
+
+- **Default language is Polish.** A Polish museum site rendering English on first visit while
+  `<html lang="pl">` is a WCAG 3.1.1 violation and was a reported bug.
+- `<html lang>` must track the actually rendered language after every switch; `<title>`, meta
+  description and `og:title` retranslate with it.
+- **No hardcoded UI strings in templates.** QA repeatedly caught literals like `Zbiory {{ title }}`
+  untranslated in EN. Every static label goes through a translation key with both PL and EN values
+  in `translations.json`.
+- Dictionary keys for filter dictionaries are **lowercase** conventions of the framework:
+  `dictionaryKey="authors"` routes to `api/article/authors/...`; `"Author"` silently falls through
+  to `api/dictionary/Author/...` → HTTP 409 and an empty options list.
+
+## 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.
+  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.
+- **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.
+
+## 6. Console hygiene (build + runtime must be warning-clean)
+
+QA files bugs for compiler warnings, so treat them as errors after copying code:
+
+- `NG8107` — remove `?.` on receivers whose type excludes null/undefined (typical after copying
+  templates: `list()?.length`, `filter()?.searchText`).
+- `NG8112` — remove unused `@let` declarations.
+- `NG8113` — remove components from `imports: []` that the template doesn't use (copied tab
+  containers often import Model3d/Map/VirtualWalk tabs conditionally rendered away).
+- `NG0100` (`ExpressionChangedAfterItHasBeenCheckedError`) — masonry/grid items must not set their
+  `width` binding after change detection completes.
+- **Never log API payloads to the console** — QA flagged leaked responses.
+- Swiper: enable `loop` only when there are enough slides for the configured
+  `slidesPerView`/`slidesPerGroup`, otherwise Swiper logs a loop warning on every load.
+- Avoid duplicate API calls on page load (home fired `object-of-the-week` 3×) — share/replay the
+  request in the service.
+
+## 7. Cross-module UI consistency
+
+These conventions were enforced by QA across modules — bake them in from the start:
+
+- **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).
+- **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).
+- **"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).
+- **Breadcrumbs:** everything except the active (last) item greyed — separators `#8e8e8e`,
+  intermediate links a WCAG-compliant grey (`#4b5563`/`#6f6f6f`), active item dark/semibold.
+- **Card hover:** underline the card **title** only (not the "Zobacz więcej" link) — pattern
+  aligned across objects/collections.
+- **Image fallback:** cards show the app's `no-image` placeholder when a thumbnail fails to load.
+- Keyword/tag chips must wrap on 360 px wide screens — no page-level horizontal scroll at
+  360/768/1024/1440.

package/plugins/mobilems/skills/mobilems-project-init/references/server-env.md

@@ -0,0 +1,97 @@
+# Runtime env delta — multimediaUrl + /api/translations
+
+The base shipped `environment.{ts,prod.ts}`, `EnvironmentService`, a `server.ts` with `/env.js`, and
+the SSRF allowed-hosts list — all keyed on `API_URL` / `SITE_URL` / `APP_VERSION` only. MobilEMS adds
+a **`multimediaUrl`** key (media/CDN host) and an **`/api/translations`** dev endpoint. These are the
+only env changes; do not otherwise rewrite the base SSR infra.
+
+## 1. `libs/shared/angular/src/lib/environments/environment.ts` + `environment.prod.ts`
+
+Add the `multimediaUrl` field to **both** files, mirroring the existing keys:
+
+```ts
+  multimediaUrl:
+    typeof window !== 'undefined' && (window as any)['env']
+      ? (window as any)['env']['multimediaUrl']
+      : process.env['MULTIMEDIA_URL'],
+```
+
+(Append after `siteUrl`. In reference mode the copied shared lib already carries this — verify it's
+present rather than duplicating.)
+
+## 2. `EnvironmentService` (shared lib)
+
+In `EnvironmentService.initFromProcessEnv()` and `init()`, propagate `multimediaUrl` alongside
+`apiUrl`/`siteUrl`/`version` (set from `process.env['MULTIMEDIA_URL']` on the server; copy from the
+transfer-state / `window.env` on the client). In reference mode this comes with the copied service —
+just confirm it.
+
+## 3. `apps/web/src/server.ts` — two additions
+
+**a) Allowed-hosts:** after the `SITE_URL` block and before the `API_URL` block, add a
+`MULTIMEDIA_URL` host so SSR can fetch media during render:
+
+```ts
+const multimediaUrl = process.env['MULTIMEDIA_URL'];
+if (multimediaUrl) {
+  try {
+    allowedHosts.push(
+      new URL(
+        multimediaUrl.startsWith('http')
+          ? multimediaUrl
+          : `https://${multimediaUrl}`,
+      ).hostname,
+    );
+  } catch {
+    // ignore invalid URL
+  }
+}
+```
+
+**b) `/env.js` template:** add the `multimediaUrl` line + its replacement:
+
+```ts
+window['env']['multimediaUrl'] = '${MULTIMEDIA_URL}';
+```
+
+```ts
+    .replace(/\$\{MULTIMEDIA_URL\}/g, process.env['MULTIMEDIA_URL'] || '')
+```
+
+**c) `/api/translations` endpoint** (needs `import * as fs from 'fs'` and `import * as path from 'path'`
+at the top): serve the translations JSON from dist, falling back to the public source. Register it
+**before** the static-file middleware and the catch-all `app.use('/**', …)`:
+
+```ts
+app.get('/api/translations', (req, res) => {
+  let translationPath = path.join(
+    process.cwd(),
+    'dist/apps/web/browser/translations.json',
+  );
+  if (!fs.existsSync(translationPath)) {
+    translationPath = path.join(
+      process.cwd(),
+      'apps/web/public/translations.json',
+    );
+  }
+  if (fs.existsSync(translationPath)) {
+    const translations = JSON.parse(fs.readFileSync(translationPath, 'utf8'));
+    res.json(translations);
+  } else {
+    console.error('Translation file not found at:', translationPath);
+    res.status(404).json({ error: 'Translation file not found' });
+  }
+});
+```
+
+The `app.config.ts` `provideAppInitializer` hits `/api/translations` in dev and `apiUrl + 'setting/theme'`
+in prod (see `references/config-providers.md`). Optionally seed an empty
+`apps/web/public/translations.json` (`{"en":{},"pl":{}}`) so dev SSR doesn't 404.
+
+## 4. `/sitemap.xml` + `/robots.txt` — dynamic endpoints (required)
+
+Never ship static `sitemap.xml`/`robots.txt` copied from the reference — two projects went to QA
+with another museum's domain in them. Build them as SSR endpoints from `SITE_URL`, with the logic in
+pure functions (`apps/web/src/seo/seo-endpoints.ts`) and thin routes in `server.ts`, registered
+after `/api/translations` and **before** `express.static` + the `'/**'` catch-all. Full pattern
+(normalization, headers, content rules): `references/qa-hardening.md` §2.