@starci/hfs 4.7.32 → 4.7.34

package/runtime/engine/refuse.mjs

@@ -0,0 +1,11 @@
+// refuse.mjs — the refusal Error every verb raises: a message plus a stable `code` (and any extra fields the
+// caller attaches). `refuse` builds it, `fail` throws it, `need` throws it when a required condition is false.
+
+/** An Error carrying `code` and `extra` fields; callers `throw` it or hand it to a result row. */
+export const refuse = (message, code, extra = {}) => Object.assign(new Error(message), { code, ...extra });
+
+/** Throws the refusal `refuse` builds — the spelling used where refusing is the whole statement. */
+export const fail = (message, code, extra = {}) => { throw refuse(message, code, extra); };
+
+/** Throws `refuse(message, code)` when `ok` is falsy — the assertion spelling of a refusal. */
+export const need = (ok, message, code) => { if (!ok) throw refuse(message, code); };

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -1,6 +1,6 @@
 schema: starci/canon-pins@1
 purpose: >-
-  The exact version of every dependency a StarCi product repository pins. One version per dependency for the whole
+  The exact version of every shared dependency in the StarCi family, including package-owned runtime dependencies. One version per dependency for the whole
   family. Raising a version is a change to this file first (with the package bump when it is a @starci package),
   then the repositories' own upgrade lane (each sets the exact version and reinstalls; nothing else installs a @starci package). Read on 2026-09-29 from the packages under
   .claude/packages and from the installed node_modules of the six product repositories; where they disagreed the
@@ -10,7 +10,8 @@ purpose: >-
   two, pinned here with a why (2026-10-01: every such conflict but graphql was already pinned). The runtime's example apps
   merged the same way on 2026-10-01: no dependency outside this file was declared at two versions across their sides, so
   every choice is a pin (each side's older @starci pins and graphql moved to the version here). `side` names the side whose code uses
-  the dependency; the app root package.json carries the pins of both.
+  the dependency; the app root package.json declares the direct dependencies and tools its sides need. Package-owned
+  runtime dependencies are declared by their package, not by the app.
 pins:
   # --- @starci packages. Every @starci package is a PUBLISHED npm package (install: registry): a product repository
   # installs the exact pinned version from the npm registry in the root and every workspace package.json, never `file:`.
@@ -22,28 +23,28 @@ pins:
     source: packages/heroicons/package.json
     why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/grammar':
-    version: 0.11.0
+    version: 0.12.1
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.40
+    version: 3.4.43
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.39
+    version: 8.4.42
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/stylelint-canon':
-    version: 2.0.10
+    version: 2.0.11
     group: starci
     install: registry
     side: fe
@@ -62,7 +63,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.5
+    version: 2.3.6
     group: starci
     install: registry
     side: be
@@ -76,14 +77,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.32
+    version: 1.7.34
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.32
+    version: 4.7.34
     group: starci
     install: registry
     side: both
@@ -238,6 +239,11 @@ pins:
     group: framework
     side: be
     why: 'the Postgres driver behind TypeORM; the reference app declares ^8.12.0 and resolves 8.23.1.'
+  bullmq:
+    version: 6.3.11
+    group: framework
+    side: be
+    why: 'the queue transport of both editions behind platform/queue (ruling:R212/case-10); starci app add queue|job declares it in a lite app together with its Redis, and both example apps resolve this version.'
   reflect-metadata:
     version: 0.2.2
     group: framework
@@ -305,6 +311,11 @@ pins:
     group: framework
     side: fe
     why: 'the GraphQL client of every front end (fe-stack graphql): auth and no-auth clients with the link chain in modules/api/graphql; version read from the starci-academy package-lock on 2026-10-13.'
+  graphql-ws:
+    version: 6.2.1
+    group: framework
+    side: both
+    why: 'the subscription transport: the front end opens it only in the Apollo clients folder (fe-stack graphql, GraphQLWsLink of @apollo/client/link/subscriptions) and the back end serves it only from platform/realtime; the version resolved by the full-app lockfile on 2026-10-24.'
   '@graphql-codegen/cli':
     version: 7.4.6
     group: tooling
@@ -370,6 +381,16 @@ pins:
     group: ui
     side: fe
     why: 'the base of the one application icon set (fe-stack icons, with @starci/heroicons for the glyphs it lacks); eslint-canon-fe (icon.mjs) admits @heroicons/react/24/outline and /16/solid.'
+  '@dicebear/core':
+    version: 10.4.0
+    group: ui
+    side: fe
+    why: 'runtime dependency of @starci/grammar for its seeded circle avatars; apps use the Avatar seed prop and never declare or import @dicebear/*; pinned with @dicebear/styles.'
+  '@dicebear/styles':
+    version: 10.4.0
+    group: ui
+    side: fe
+    why: 'runtime dependency of @starci/grammar supplying its fixed avatar DNA style; apps use the Avatar seed prop and never declare or import @dicebear/*; pinned with @dicebear/core.'
   'next-themes':
     version: 0.4.6
     group: ui
@@ -481,6 +502,16 @@ pins:
     group: framework
     side: be
     why: 'the Apollo driver of @nestjs/graphql; the full-app resolution on 2026-10-13. Stays on 13.x with @nestjs/graphql (accepted advisory, major deferred to alpha.19).'
+  '@aws-sdk/client-s3':
+    version: 3.1150.0
+    group: framework
+    side: be
+    why: 'the S3 transport of integrations/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces, Supabase Storage); 3.1150.0 is the release of 2026-10-12, chosen over newer ones that had not aged two weeks.'
+  '@aws-sdk/s3-request-presigner':
+    version: 3.1150.0
+    group: framework
+    side: be
+    why: 'signs the presigned PUT and GET of integrations/object-storage locally, the same release as client-s3.'
   '@apollo/server':
     version: 5.5.1
     group: framework
@@ -496,6 +527,31 @@ pins:
     group: framework
     side: be
     why: 'the socket.io platform of @nestjs/websockets; the @nestjs/core pin line.'
+  socket.io:
+    version: 4.8.3
+    group: framework
+    side: be
+    why: 'the socket.io server the IoAdapter of platform/realtime builds (types and the adapter contract); the exact version @nestjs/platform-socket.io 11.2.5 depends on, so the workspace keeps one copy (4.8.4 is the latest on 2026-10-24).'
+  '@socket.io/postgres-adapter':
+    version: 0.5.0
+    group: framework
+    side: be
+    why: 'the stateless socket.io adapter of a back end without Redis that runs several api replicas (LISTEN/NOTIFY, no sticky sessions, websocket only), imported only by platform/realtime (knowledge/patterns/be/realtime.yaml BE-REALTIME-7); the latest registry version on 2026-10-24.'
+  '@socket.io/redis-adapter':
+    version: 8.3.0
+    group: framework
+    side: be
+    why: 'the sharded Redis adapter (createShardedAdapter, Redis 7 or later) of a back end with Redis declared that runs several api replicas, imported only by platform/realtime; the latest registry version on 2026-10-24.'
+  ioredis:
+    version: 5.11.1
+    group: framework
+    side: be
+    why: 'the one Redis client of a back end: the cache, the optional peer bullmq loads for the queue of platform/queue, and the Redis hub and sharded socket.io adapter of platform/realtime (its docs recommend ioredis over redis); the latest 5.x on 2026-10-24, because typeorm 0.3.31 declares ioredis ^5.0.4 as a peer and ioredis 6.0.0 (the latest) does not satisfy it.'
+  '@types/pg':
+    version: 8.23.1
+    group: framework
+    side: be
+    why: 'the types of the pg driver the Postgres hub of platform/realtime opens a LISTEN connection with; the pg pin line, the latest registry version on 2026-10-24.'
   '@as-integrations/express5':
     version: 1.1.2
     group: framework

package/runtime/knowledge/hfs/design-truths.yaml

@@ -0,0 +1,149 @@
+schema: starci/design-truths@1
+id: hfs.design-truths
+title: The design truths - the one list of exceptions the loosening state check allows
+purpose: |
+  A loosening is always red (owner ruling loosening-always-red). The state check (scripts/lib/loosening-state.mjs, self-check loosening-state,
+  also the app gate's bypass rule) reads the tree as it stands and refuses any bypass, any ignore or exclude entry, any lowered threshold and any
+  exception file the canon does not derive. This file is where the canon says what it does derive and allow: every exception is here and nowhere
+  else, each with the owner ruling that makes it a design truth rather than a loosening, and each list entry bound to the files it holds for.
+  Changing this file is an owner decision (owner ruling loosening-state-check, 2026-10-24): the latest owner ruling that amends it records its
+  sha256 (pins), and the self-check is red whenever the file's digest is not the recorded one, so an edit never lands on a lane's say-so.
+
+# The files that may spell a forbidden token on purpose (the fixtures of the specs of this checker) and the vendored dependency copy. They are not read
+# by the tree check; each is pinned by digest in the latest owner ruling, only a package spec of packages/hfs/src may import the fixtures, and
+# a vendored file is a dependency copy, not authored source.
+fixtureFiles:
+  - packages/hfs/src/fixtures/loosening/forms.mjs
+  - packages/hfs/src/fixtures/loosening/swallows.mjs
+  - packages/hfs/src/fixtures/loosening/adversarial.mjs
+vendored:
+  - {path: engine/yaml.mjs, slot: runtime.vendored-yaml}
+
+# What no gate reads: build output, generated records and sealed custody. An ignore or exclude entry that names only these is no loosening. A group
+# with anyDepth holds at any depth (a folder of that name anywhere is output); the others are rooted (only the spelling at the root of the file's own
+# tree, never a glob that reaches a domain folder of that name).
+outsideTheGates:
+  - id: build-output
+    cite: {ruling: design-truths-confirmed}
+    anyDepth: true
+    entries: [node_modules, dist, build, coverage, .next, storybook-static, "*.tsbuildinfo", __generated__, .starci]
+  - id: root-output-and-records
+    cite: {ruling: design-truths-confirmed}
+    entries: [reports, contracts, supabase/types, .starcistacks, .starciwork, package-lock.json]
+
+# The gate limits of the Sonar gate (knowledge/sonar-gate.yaml): a floor is a number that may not be lower, a ceiling a number that may not be higher.
+gateLimits:
+  file: knowledge/sonar-gate.yaml
+  cite: {ruling: design-truths-confirmed}
+  floors: {minPercent: 100, minReviewedPercent: 100}
+  ceilings: {maxPercent: 3, max: 0, unreviewedMax: 0, ignoreBelowChangedLines: 0}
+
+# The numeric budgets of the slot manifests, pinned: a ceiling raised, a floor lowered or a budget removed there is red. An app or example config
+# never states a budget (hfs.json keys, ESLint max-* options): the canon owns them.
+budgets:
+  - file: knowledge/hfs/slots.yaml
+    cite: {ruling: design-truths-confirmed}
+    params:
+      under: ruleParams.common
+      ceilings: {fileLines.soft: 500, functionLines: 80, featureFiles: 250}
+      floors: {duplicateBlock.lines: 8, duplicateBlock.tokens: 60}
+      equals: {fileLines.hardGrowth: true}
+    slots:
+        repo.docs-media: {"bytes": 512000}
+        be.app.api: {"app.module.ts": 250, "main.ts": 80, "<app>.env.ts": 150, "<app>.options.ts": 200, "compose/<area>.ts": 120}
+        be.app.worker: {"app.module.ts": 250, "main.ts": 80, "<app>.env.ts": 150, "<app>.options.ts": 200, "compose/<area>.ts": 120}
+        be.app.cli: {"app.module.ts": 250, "main.ts": 80, "<app>.env.ts": 150, "<app>.options.ts": 200, "compose/<area>.ts": 120}
+        be.feature: {"files": 250, "indexExports": 60}
+        be.domain: {"indexExports": 60}
+        be.platform: {"indexExports": 60}
+        be.platform.event-bus: {"indexExports": 60}
+        be.platform.queue: {"indexExports": 60}
+        be.platform.jobs: {"indexExports": 60}
+        be.integrations: {"indexExports": 80}
+        fe.feature: {"component.tsx": 300, "index.tsx": 200, "dataHooks": 6, "useState": 6}
+        fe.components: {"component.tsx": 300, "index.tsx": 200, "dataHooks": 6, "useState": 6}
+        fe.hooks: {"file": 200, "barrel": 400, "dataHooks": 6, "useState": 6}
+        fe.hooks.swr: {"file": 200, "barrel": 400}
+        fe.hooks.rhf: {"file": 200, "barrel": 400}
+        fe.hooks.zustand: {"file": 200, "barrel": 400}
+        fe.hooks.socketio: {"file": 200, "barrel": 400}
+        fe.hooks.effects: {"file": 200, "barrel": 400}
+        fe.hooks.reuseables: {"file": 200, "barrel": 400}
+        fe.redux: {"file": 400}
+        fe.modules: {"file": 400}
+        fe.package.ui: {"component.tsx": 300, "index.tsx": 200, "dataHooks": 6, "useState": 6}
+  - file: knowledge/hfs/runtime-slots.yaml
+    cite: {ruling: design-truths-confirmed}
+    params:
+      under: ruleParams.runtime
+      ceilings: {fileLines.soft: 500}
+      equals: {fileLines.hardGrowth: true}
+  - file: modules/kernel/hook-input.yaml
+    cite: {ruling: hook-input-budget-pins}
+    params:
+      under: ""
+      ceilings: {maxBytes: 1048576, outputTimeoutMs: 1000, verdictTimeoutMs: 20000, teardownTimeoutMs: 1000, hookTimeoutSeconds: 30}
+      floors: {minInputWindowMs: 5000}
+
+truths:
+  - id: fe-has-no-specs
+    cite: {ruling: design-truths-standing}
+    says: The front end has no tests, so it is never a coverage target and a front end folder is outside every coverage measure.
+    allows:
+      - {list: coverage-exclusions, file: "{**/codecov.yml,**/sonar-project.properties}", entries: ["fe/**"]}
+  - id: runtime-has-no-specs
+    cite: {ruling: no-runtime-specs}
+    says: The .claude runtime has no specs of its own (specs for bundled libraries live in packages/*), so Sonar analyses the runtime without a coverage report and its own specs are not analysed as source.
+    allows:
+      - {list: sonar-exclusions, derivedBy: runtime-coverage-scope, file: sonar-project.properties, entries: ["**/*.spec.mjs"]}
+      - {list: coverage-exclusions, derivedBy: runtime-coverage-scope}
+      - {list: sonar-scope, derivedBy: runtime-coverage-scope}
+  - id: thin-wiring-roles-outside-coverage
+    cite: {ruling: design-truths-standing}
+    says: Back end unit coverage is 100 per file on the logic roles only; the files of a thin wiring role (module, controller, resolver, port, options, entity and the like) and the slots marked coverage none are outside coverage, derived once from the slot manifest.
+    allows:
+      - {list: coverage-exclusions, derivedBy: coverage-scope}
+  - id: app-config-renders-from-the-canon
+    cite: {ruling: design-truths-standing}
+    says: The ignore and exclude lists of a rendered app file (sonar.exclusions, sonar.cpd.exclusions, a tsconfig exclude, a prettier ignore, the jest excludes) are what the canon template renders for that file; an entry the render does not hold is a loosening.
+    allows:
+      - {list: sonar-exclusions, derivedBy: template-render}
+      - {list: cpd-exclusions, derivedBy: template-render}
+      - {list: sonar-scope, derivedBy: template-render}
+      - {list: path-ignores, derivedBy: template-render}
+  - id: message-catalogs-are-not-duplicate-code
+    cite: {ruling: message-catalogs-not-duplicate-code}
+    says: The message catalogs are left out of Sonar copy-paste detection and out of the formatter, and nothing else is.
+    allows:
+      - {list: cpd-exclusions, file: "{**/sonar-project.properties,packages/hfs/templates/app/quality-config/*.properties}", entries: ["**/messages/*.messages.ts", "**/messages/*.json"]}
+      - {list: path-ignores, file: "{**/.prettierignore,packages/hfs/templates/app/tool-config*/prettierignore}", entries: ["**/i18n/messages/**"]}
+  - id: be-tests-have-their-own-tsconfig
+    cite: {ruling: design-truths-confirmed}
+    says: The app and build tsconfig of a back end exclude the test folders and the specs because src/tests/tsconfig.json compiles them, so every test is still type-checked.
+    allows:
+      - {list: path-ignores, file: "{**/be/tsconfig.json,**/be/tsconfig.build.json,packages/hfs/templates/be/tool-config/tsconfig*.json}", entries: [src/tests, src/tests/contract, src/tests/e2e, src/tests/integration, src/tests/world, "**/*.spec.ts"]}
+  - id: grammar-stories-are-not-the-package
+    cite: {ruling: design-truths-confirmed}
+    says: The grammar package build leaves its stories out of the shipped bundle; the stories are compiled by their own tsconfig in the same script, so no story is unchecked.
+    allows:
+      - {list: path-ignores, file: packages/grammar/tsconfig.build.json, entries: ["src/**/*.stories.ts", "src/**/*.stories.tsx", "src/stories/**"]}
+  - id: jest-preset-ignores-node-modules
+    cite: {ruling: design-truths-confirmed}
+    says: The jest preset skips the installed dependencies when it looks for tests; nothing else is skipped, and a jest pattern is compared as the exact text.
+    allows:
+      - {list: jest-patterns, file: packages/jest-preset/index.cjs, entries: [/node_modules/]}
+  - id: require-ci-defaults-false
+    cite: {ruling: release-require-ci-per-project}
+    says: release.requireCi defaults to false; every local gate row runs either way, so a project that does not wait for its candidate CI loosens nothing.
+    allows:
+      - {setting: requireCi, value: false}
+  - id: one-allowlist-holds-no-entries
+    cite: {ruling: loosening-always-red}
+    says: The runtime has one allowlist file, with its reserved sections empty. An entry added to it is a loosening.
+    allows:
+      - {exceptionFile: modules/kernel/allowlist.yaml, maxEntries: 0}
+  - id: skip-lib-check-skips-third-party-declarations
+    cite: {ruling: design-truths-confirmed}
+    says: skipLibCheck true skips type-checking of third-party declaration files only and never app code; it is a design truth of the canon base tsconfig and of no other file, so a tsconfig that sets it, or turns any other strictness option off, is red.
+    allows:
+      - {compilerOption: skipLibCheck, value: true, files: [packages/tsconfig/base.json]}

package/runtime/knowledge/hfs/fe-stack.yaml

@@ -19,7 +19,14 @@ concerns:
     home: [fe.modules.api, fe.transport.client, fe.transport.outcome]
     pattern: FE-API-GRAPHQL
     forbids: [urql, graphql-request, '@urql/core', graphql-hooks, apollo-boost]
-    why: one file per operation under modules/api/graphql/{queries,mutations}, run by the auth or no-auth Apollo client with the link chain.
+    why: one file per operation under modules/api/graphql/{queries,mutations,subscriptions}, run by the auth or no-auth Apollo client with the link chain.
+  - id: graphql-subscriptions
+    tier: opt
+    packages: [graphql-ws]
+    home: [fe.transport.client, fe.package.api.client]
+    pattern: FE-REALTIME
+    forbids: []
+    why: the subscription transport of a GraphQL subscription door (be.feature.realtime.graphql); only the Apollo clients folder imports it (GraphQLWsLink of @apollo/client/link/subscriptions), a subscription operation runs on that client and a useSubscribe hook of hooks/swr reads it.
   - id: codegen
     tier: core
     packages: ['@graphql-codegen/cli', '@graphql-codegen/client-preset']
@@ -74,8 +81,8 @@ concerns:
     packages: [socket.io-client, eventemitter2]
     home: [fe.hooks.socketio]
     pattern: FE-REALTIME
-    forbids: [graphql-ws, subscriptions-transport-ws, '@supabase/realtime-js', pusher-js, ably]
-    why: one socket.io-client singleton per namespace and one side-effect component that dispatches to redux and SWR; lite runs the gateway in the be api process. A one-way channel served as server-sent events needs no package, only a fetch reader in modules/api/sse and a use<Channel>Stream hook (FE-REALTIME).
+    forbids: [subscriptions-transport-ws, '@supabase/realtime-js', pusher-js, ably]
+    why: one socket.io-client singleton per namespace and one side-effect component that dispatches to redux and SWR; both editions run the gateway in the be api process. A one-way channel served as server-sent events needs no package, only a stream reader in modules/api/sse/clients, a stream operation in modules/api/sse and a useSubscribe<Channel>Swr hook (FE-REALTIME).
   - id: auth
     tier: core
     packages: []
@@ -89,7 +96,7 @@ concerns:
     home: [fe.modules.i18n]
     pattern: FE-I18N
     forbids: [i18next, react-i18next, next-i18next, react-intl, '@lingui/react']
-    why: useTranslations for copy and the next-intl formatter for numbers, dates and currency.
+    why: useTranslations for copy and the next-intl formatter for numbers, fixed dates and currency; FE-DATE owns live time display.
   - id: ui
     tier: core
     packages: ['@heroui/react', '@heroui/styles', tailwindcss, '@starci/grammar']
@@ -107,6 +114,17 @@ concerns:
       one application icon set, the heroicons family (owner ruling 2026-10-13), on the 24/outline and 16/solid cuts. @heroicons/react
       is the base set and is used first; @starci/heroicons holds only the glyphs heroicons lacks (brand or domain glyphs drawn in
       heroicons style), never duplicates a heroicons glyph, and a missing glyph is added to it.
+  - id: avatar-illustration
+    tier: opt
+    packages: ['@starci/grammar']
+    home: [fe.components]
+    pattern: FE-UI
+    forbids: ['@dicebear/*', boring-avatars, 'react-nice-avatar', multiavatar]
+    why: >-
+      Grammar owns circle avatars: pass the uploaded avatar as src, otherwise pass the user or identity id as seed on
+      Avatar, AvatarButton or AvatarGroup members. Grammar renders deterministic DiceBear images with its fixed DNA style;
+      @dicebear/core and @dicebear/styles are Grammar runtime dependencies pinned in canon-pins.yaml. Apps declare and
+      import @starci/grammar, never @dicebear/*, and draw no avatar visuals. With neither src nor seed, initials remain.
   - id: theme
     tier: core
     packages: [next-themes]
@@ -127,7 +145,7 @@ concerns:
     home: [fe.modules]
     pattern: FE-DATE
     forbids: [moment, moment-timezone, date-fns, luxon]
-    why: dayjs (modules/dayjs) for date math and parsing; display through the next-intl formatter.
+    why: FE-DATE owns application date math, fixed date formatting and Grammar's live time display.
   - id: numbers
     tier: opt
     packages: [decimal.js]