docs: refine CLAUDE.md command and architecture notes

CLAUDE.md

@@ -40,21 +40,24 @@ sudo sysctl fs.inotify.max_user_instances=512
 
 ### Testing (from `apps/web`)
 - `pnpm test` — Jest unit tests (`nx test:unit`)
-- `pnpm test path/to/file.test.ts` — run a single Jest test file
+- `pnpm test -- path/to/file.test.ts` — run a single Jest test file (the `--` forwards args to Jest; or `cd apps/web && npx jest path/...`)
 - `pnpm test:playwright` — Playwright e2e tests
 - `pnpm test:playwright:open` — Playwright UI
+- `pnpm test:playwright:screenshots` — update Playwright screenshot snapshots
 - `pnpm coverage` — unit tests with coverage
 
 Note: `apps/desktop` unit tests use **Vitest** (`pnpm --filter element-desktop test:unit`), not Jest.
 
 ### Code Quality
 - `pnpm lint` (root) — full lint across all workspaces: types, prettier, eslint, stylelint, GH workflows, knip
+- `pnpm --filter element-web lint` — package-local shorthand for `lint:types && lint:js && lint:style`
 - `pnpm --filter element-web lint:types` — TypeScript check only (via Nx)
-- `pnpm --filter element-web lint:js-fix` — auto-fix ESLint
+- `pnpm --filter element-web lint:js` — ESLint check (`lint:js-fix` auto-fixes)
 - `pnpm --filter element-web lint:style` — Stylelint on `res/css/**/*.pcss`
+- `pnpm lint:knip` (root) — unused deps/exports; `pnpm lint:workflows` — validate GH Actions YAML. Both run as part of `pnpm lint` and gate CI.
 
 ### Utilities
-- `pnpm i18n` (root or per-package) — regenerate/sort/lint translation strings
+- `pnpm i18n` (root or per-package) — regenerate/sort/lint translation strings; chains `i18n:sort`, `i18n:lint`, and `i18n:diff` (run any one directly when only that step is needed)
 - `pnpm --filter @element-hq/web-shared-components storybook` — Storybook on port 6007
 
 ## Architecture
@@ -72,6 +75,11 @@ Components live in `apps/web/src/components/`:
 - `structures/` — major layout components (these use React classes)
 - `views/` — reusable UI grouped by function (auth, dialogs, messages, rooms, settings)
 
+Other recurring `apps/web/src/` layers worth knowing:
+- `customisations/` — Element customization hooks (e.g. `Media.ts`, `WidgetPermissions.ts`) — the sanctioned override points
+- `viewmodels/` — view logic separated from React components, consumed by `structures/` classes
+- `async-components/` — code-split / lazy-loaded mirrors of components (e.g. `ErrorView.tsx`)
+
 ### State Management
 Flux architecture:
 - Centralized dispatcher in `apps/web/src/dispatcher/`
@@ -91,8 +99,15 @@ Flux architecture:
 
 ### Module System
 Runtime plugin architecture (`apps/web/module_system/`, public API in `packages/module-api`):
-- `prebuild:module_system` reads `apps/web/build_config.yaml` and generates `apps/web/src/modules.js`
-- HealthChat ships the `healthchat-workspace` module (see release section)
+- `prebuild:module_system` reads `apps/web/build_config.yaml` and generates `apps/web/src/modules.js` (empty by default in this fork — no committed `build_config.yaml`)
+- In production, modules are loaded at runtime from `config.json`'s `modules` array, not via the build-time `modules.js` path
+- HealthChat ships the `healthchat-workspace` module (see release section); its version is pinned in `.healthchat-workspace-version`
+
+### HealthChat fork specifics
+Conventions unique to this fork that span multiple files:
+- **Branding defaults**: hardcoded in `apps/web/src/SdkConfig.ts` (`brand: "HealthChat"`, mobile app-store URLs); runtime config in `apps/web/config.json` (homeserver `matrix.healthchat.ch`, custom "HealthChat Light" theme). `config.sample.json` is the dev template — copy it to `config.json`.
+- **Widget auto-approval**: widgets served from `api.healthchat.ch` bypass permission dialogs and hide revoke/minimize controls. Logic lives in `apps/web/src/stores/widgets/ElementWidgetDriver.ts`, `apps/web/src/components/views/elements/AppTile.tsx`, and `.../context_menus/WidgetContextMenu.tsx`; base URL comes from the `ch.healthchat.api_base_url` config key.
+- **Desktop deep-linking**: scheme is `healthchat://` (`apps/desktop/src/protocol.ts`), with the SSO session passed via the `healthchat-desktop-ssoid` param. Desktop variant config (and its build runbook) lives under `apps/desktop/element.io/healthchat/` (`config.json`, `build.json`, `README`).
 
 ### Testing Patterns
 - Web unit tests in `apps/web/test/unit-tests/` (Jest)