@starci/hfs 4.2.12 → 4.2.14

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 4.2.14 - 2026-10-13
+
+- Breaking: HFS manifest 3.0.0 (schema `starci/hfs-slots@3`, rule catalog `starci/hfs-rules@3` 3.0.0). Removing the front-end database slots and the Supabase realtime feature slot and narrowing `fe.route` change answers for existing apps, so the manifest takes a major: every app pins `"hfs": 3` (scaffold writes it), and an app still pinned to 2 is refused with `HFS_MANIFEST_MAJOR_MISMATCH`.
+- Changed: HFS manifest 3.0.0 re-rules the lite edition (owner ruling 2026-10-12, R212): lite is the full architecture deployed without self-hosted infrastructure. Lite regains the worker app, queue, event bus, saga, reactors, fenced jobs, projections, realtime and event contracts through their Supabase adapters, and full's unit world; only the e2e and contract layers, the browser journey, UAT records, the socket and graphql-ws doors and the self-hosted stack stay forbidden. The lite-only `be.feature.realtime.supabase` door is added and `repo.tests-forbidden` is removed.
+- Changed: lite sync, scaffold and `add` render full's unit run (test scripts, jest config, the tests tsconfig, coverage and the CI unit step with the Codecov upload) and the lite unit specs; the lite identity module owns its access-token verifier token.
+- Changed: carry the canon pins for Grammar 0.9.14, the BE/FE lint canons 3.2.15/8.2.15, jest-preset 2.2.7 and CLI 1.2.14.
+- Changed: one front-end skeleton for lite and full (owner ruling 2026-10-13, knowledge/hfs/fe-stack.yaml). Every product Next app (full `app`, lite `web`; not the marketing `landing`) is scaffolded with the shared app core `templates/fe/skeleton/apps/__app__`: `modules/api/graphql` (the GraphQLResponse union), `modules/toast`, `modules/auth` (one `AuthClient` interface: a full IdP stub, the lite overlay a browser Supabase Auth client with client-side PKCE), `redux/` (store, typed hooks, ReduxProvider, the session slice), `components/providers` (one AppProviders owner composing the theme, redux, SWR config, app effects and the HeroUI toast region), `components/blocks` (SignInForm, SignOutButton, drawn by the home page), `hooks/auth` (session, sign-in, sign-out with its toast), `hooks/swr` (SwrSideEffects) and `hooks/effects` (the session kept in redux by the auth change subscription, no load in an effect). A fresh scaffold is lint-clean in both editions: it holds no code nothing calls, so the Apollo clients and their links arrive with the first GraphQL operation. The lite web app loses `modules/db`, its Server Actions, the `auth/callback` route and the session-refreshing proxy; health/live is its one route handler, and Supabase's redirect URL is the site root.
+- Changed: the scaffold installs every `tier: core` package of fe-stack.yaml at its canon pin in both editions, read from the catalog (product app workspaces take the runtime packages, the app root the codegen, lint and compiler tools), and both editions add the back end's GraphQL stack (@nestjs/graphql, @nestjs/apollo, @apollo/server, graphql).
+- Added: `npm run codegen:graphql`, and `scripts/codegen.mjs` in both editions generates each product app's `modules/api/graphql/__generated__` from `be/contracts/<app>/schema.graphql` with the GraphQL codegen client preset; both editions now run `codegen` before dev, build, typecheck and lint.
+- Changed: the GraphQL door is the same in both editions. The shared be skeleton's `requestOf` reads a resolver's request through the GraphQL context and the errors filter hands GraphQL failures to the formatter; the GraphQL server capability (`modules/platform/graphql`: Apollo driver, error formatter, depth limit, localize plugin over `x-locale`) is written by the first GraphQL feature. Lite `add api` now writes full's GraphQL transport (principal-aware command and handler) and wires it with the server into the api app; the lite HTTP-door templates are removed.
+- Changed: `add table --fe` emits the table's api feature over GraphQL (get and create, with the app_be insert policy and grant) and per product app the query/mutation operation files and the useQuery*Swr / useMutate*Swr hooks with their barrels, never Server Actions or Supabase readers; the first operation of an app also writes its GraphQL transport (`templates/fe/transport/graphql/clients`: the auth and no-auth Apollo clients with the retry, error, timeout, UNAUTHENTICATED refresh, locale, access-token and http links) and the `graphqlUrl` reader of its modules/config, as platform/graphql is written by the first GraphQL feature on the back end. `add app` is no longer refused in lite and renders partials and the shared core in both editions.
+- Fixed: `starci app scaffold --edition lite` loads the installed jest preset's Sonar exclusions like full, so a fresh lite app's sonar-project.properties is the render its own `starci app lint` expects.
+- Fixed: the full api `graphql.module.ts.tpl` imported a `<Feature>Module` the feature module never exported; it imports `<Feature>ApiModule`.
+
+## 4.2.13 - 2026-10-12
+
+- Added: HFS manifest 2.2.0 owns app compiler declarations under the declaration-only types/ambient slot, without a runtime entry; runtime source files remain refused there.
+- Fixed: the derived Grammar contract selects all three required peers, react, @heroui/react and @xyflow/react. Full and lite FE scaffolds and the shared UI workspace declare @xyflow/react at the canonical 12.11.6 pin.
+- Fixed: full and lite Next app scaffolds and the four Next app examples declare CSS imports through global declarations in their ambient owner, while missing non-CSS side-effect imports remain errors under TypeScript 6.
+- Changed: carry the merged runtime mirror and canon pins for Grammar 0.9.13 and Stylelint canon 2.0.9, retaining the no-frontend-tests policy.
+
 ## 4.2.12 - 2026-10-12
 
 - Changed: bundled canon pins carry @starci/grammar 0.9.12 (the secondary tab track keeps its padding).
@@ -12,9 +33,13 @@
 
 - Changed: bundled canon pins carry @starci/grammar 0.9.10 (the grammar ships without spec suites).
 
+## 4.2.9 - 2026-10-12
+
+- Changed: refresh the bundled canon pins for CLI 1.2.9 and the BE/FE lint canons 3.2.10/8.2.10 after correcting the CLI runtime install pin; app command implementations are unchanged.
+
 ## 4.2.8 - 2026-10-12
 
-- Changed: refresh the bundled canon pins for grammar 0.9.9; behaviour is unchanged.
+- Changed: refresh the bundled runtime and canon pins for grammar 0.9.9, the BE/FE lint canons 3.2.9/8.2.9, stylelint-canon 2.0.8 and CLI 1.2.8; app command implementations are unchanged.
 
 ## 4.2.7 - 2026-10-12
 

package/README.md

@@ -36,11 +36,15 @@ the app it began instead of leaving a partial tree.
 
 The lite additions are deliberately narrow:
 
-- `starci app add table <name> [--fe] [--no-types]` adds the migration and matching back-end capability. `--fe` also adds typed readers
-  and writers through the front-end database owner; types regenerate by default, while `--no-types` is the explicit opt-out.
+- `starci app add table <name> [--fe] [--no-types]` adds the migration and matching back-end capability. `--fe` also adds the table's
+  api feature over GraphQL (get-<singular> query, create-<singular> mutation, the GraphQL server capability on first use) and, in
+  every product Next app, one operation file per operation under `modules/api/graphql` and its `useQuery*Swr` / `useMutate*Swr`
+  hook under `hooks/swr/api/graphql`; never a Server Action or a Supabase reader. Types regenerate by default, while `--no-types` is
+  the explicit opt-out.
 - `starci app add cli <group>` creates the optional cli app on first use, including its built-in migration and seed groups, then adds
   the requested group without full-edition specs.
-- `starci app add app <name>` refuses in lite because lite has exactly one front-end app. Upgrade before adding another.
+- `starci app add app <name>` adds another Next app in either edition: the edition's app skeleton plus the shared app core
+  (modules/api, auth, toast, redux, the providers and the hooks), one fe structure for lite and full (owner ruling 2026-10-13).
 - An `add` or `new` whose target slot is unavailable in lite stops before writing with `<verb> <noun>: full edition only`.
 
 `starci app emit` continues to emit the enabled back-end snapshots and also writes `supabase/types/database.types.ts` when

package/emit/db-types.mjs

@@ -109,7 +109,8 @@ function emitDbTypesWithRunner({ root, run }) {
     const cause = firstLine(stderr) ?? firstLine(result?.error?.message ?? result?.error) ?? 'no output';
     throw new DbTypesError(`\`${command}\` failed${result?.status !== undefined && result?.status !== null ? ` (exit ${result.status})` : ''}: ${cause}; the local Supabase stack must be up (supabase start)`, { file: dbTypesPath, stderr });
   }
-  return `${TYPES_STAMP}${migrationsDigest(root)}\n${stdout}`;
+  // The CLI pads blank lines with spaces; the committed file carries none (git diff --check refuses trailing whitespace).
+  return `${TYPES_STAMP}${migrationsDigest(root)}\n${stdout.replace(/[ \t]+$/gm, '')}`;
 }
 
 export function emitDbTypes({ root, run = spawn, platform = process.platform } = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.2.12",
+  "version": "4.2.14",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

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

@@ -14,43 +14,38 @@ purpose: >-
 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:`.
-  '@starci/heroicons':
-    version: 0.3.3
-    group: starci
-    install: registry
-    side: fe
-    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/heroicons has no pin since 1.0.0-alpha.13: the application icon set is @phosphor-icons/react (fe-stack.yaml
+  # icons) and eslint-canon-fe one-icon-set refuses every other glyph catalogue, so no product repository installs it.
   '@starci/grammar':
-    version: 0.9.12
+    version: 0.9.14
     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.2.13
+    version: 3.2.16
     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.2.13
+    version: 8.2.15
     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.7
+    version: 2.0.9
     group: starci
     install: registry
     side: fe
     source: packages/stylelint/package.json
     why: 'the front-end stylelint canon: no-class-selector refuses a compound class selector (`div.card`); the brand layer accepts `--font-sans` and `--font-mono`; status-contrast measures the HeroUI soft pairs per theme; brand-layer-shape reads the shared :root,.light,.dark block and the info soft pair; appTokens come from loadAppTokens(import.meta.url) for the managed one-line stylelint.config.mjs.'
   '@starci/tsconfig':
-    version: 2.0.3
+    version: 2.0.4
     group: starci
     install: registry
     side: both
@@ -62,7 +57,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.2.6
+    version: 2.2.7
     group: starci
     install: registry
     side: be
@@ -76,14 +71,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.2.12
+    version: 1.2.14
     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.2.12
+    version: 4.2.14
     group: starci
     install: registry
     side: both
@@ -274,6 +269,11 @@ pins:
     side: be
     why: the e2e world of a back end calls the app over HTTP (/health/live in the skeleton); two product back ends resolve 7.3.0, one 7.2.2.
   # --- ui
+  '@xyflow/react':
+    version: 12.11.6
+    group: ui
+    side: fe
+    why: 'Grammar FlowGraph imports React Flow from @xyflow/react; every Grammar consumer declares this required peer at the version used by the Grammar package.'
   '@heroui/react':
     version: 3.2.6
     group: ui
@@ -294,6 +294,198 @@ pins:
     group: ui
     side: fe
     why: 'the PostCSS plugin tailwindcss 4 runs through; the reference app declares ^4 and resolves 4.3.3.'
+  # --- front-end stack (knowledge/hfs/fe-stack.yaml; owner ruling 2026-10-13: lite = full)
+  '@apollo/client':
+    version: 4.1.6
+    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-codegen/cli':
+    version: 7.4.6
+    group: tooling
+    side: fe
+    why: 'generates the front-end wire types from be/contracts/<app>/schema.graphql into modules/api/graphql/__generated__ (fe-stack codegen); the latest registry version on 2026-10-13, academy has none.'
+  '@graphql-codegen/client-preset':
+    version: 6.2.3
+    group: tooling
+    side: fe
+    why: 'the codegen preset of the front-end wire types (fe-stack codegen); the latest registry version on 2026-10-13.'
+  'axios':
+    version: 1.15.2
+    group: framework
+    side: fe
+    why: 'the REST client of the front end for uploads, presigned URLs and auth endpoints (fe-stack rest); version read from the starci-academy package-lock on 2026-10-13.'
+  'swr':
+    version: 2.4.2
+    group: framework
+    side: fe
+    why: 'the data hooks and cache of every front end, hooks/swr (fe-stack data); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-hook-form':
+    version: 7.77.0
+    group: framework
+    side: fe
+    why: 'the form library, hooks/rhf (fe-stack forms); version read from the starci-academy package-lock on 2026-10-13.'
+  '@hookform/resolvers':
+    version: 5.4.0
+    group: framework
+    side: fe
+    why: 'the zod resolver of react-hook-form (fe-stack forms); version read from the starci-academy package-lock on 2026-10-13.'
+  'zod':
+    version: 4.4.3
+    group: framework
+    side: fe
+    why: 'the schema library of front-end forms and boundary parsing (fe-stack forms); version read from the starci-academy package-lock on 2026-10-13.'
+  '@reduxjs/toolkit':
+    version: 2.11.2
+    group: framework
+    side: fe
+    why: 'app-wide shared state, redux/ (fe-stack state-global); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-redux':
+    version: 9.2.0
+    group: framework
+    side: fe
+    why: 'the React binding of the app-wide store (fe-stack state-global); version read from the starci-academy package-lock on 2026-10-13.'
+  'zustand':
+    version: 5.0.12
+    group: framework
+    side: fe
+    why: 'feature-local client state, hooks/zustand (fe-stack state-local); version read from the starci-academy package-lock on 2026-10-13.'
+  'socket.io-client':
+    version: 4.8.3
+    group: framework
+    side: fe
+    why: 'the realtime client, hooks/socketio (fe-stack realtime); version read from the starci-academy package-lock on 2026-10-13.'
+  'eventemitter2':
+    version: 6.4.9
+    group: framework
+    side: fe
+    why: 'the fan-out emitter behind the socket side-effect component (fe-stack realtime); version read from the starci-academy package-lock on 2026-10-13.'
+  '@phosphor-icons/react':
+    version: 2.1.10
+    group: ui
+    side: fe
+    why: 'the one application icon set (fe-stack icons); version read from the starci-academy package-lock on 2026-10-13.'
+  'next-themes':
+    version: 0.4.6
+    group: ui
+    side: fe
+    why: 'light and dark theme switching in components/providers (fe-stack theme); version read from the starci-academy package-lock on 2026-10-13.'
+  'framer-motion':
+    version: 12.42.2
+    group: ui
+    side: fe
+    why: 'motion (fe-stack motion); version read from the starci-academy package-lock on 2026-10-13.'
+  'dayjs':
+    version: 1.11.21
+    group: framework
+    side: fe
+    why: 'date math and parsing, modules/dayjs (fe-stack dates); display goes through the next-intl formatter; version read from the starci-academy package-lock on 2026-10-13.'
+  'decimal.js':
+    version: 10.6.0
+    group: framework
+    side: fe
+    why: 'money and decimal arithmetic, modules/utils (fe-stack numbers); version read from the starci-academy package-lock on 2026-10-13.'
+  'superjson':
+    version: 2.2.6
+    group: framework
+    side: fe
+    why: 'serialization of stored values, modules/superjson and modules/storage (fe-stack storage); version read from the starci-academy package-lock on 2026-10-13.'
+  'lodash':
+    version: 4.17.23
+    group: framework
+    side: fe
+    why: 'per-method utilities, modules/utils (fe-stack utils); version read from the starci-academy package-lock on 2026-10-13.'
+  'usehooks-ts':
+    version: 3.1.1
+    group: framework
+    side: fe
+    why: 'reusable React hooks, hooks/reuseables (fe-stack utils); version read from the starci-academy package-lock on 2026-10-13.'
+  'recharts':
+    version: 3.8.1
+    group: ui
+    side: fe
+    why: 'charts (fe-stack charts); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-markdown':
+    version: 10.1.0
+    group: ui
+    side: fe
+    why: 'markdown rendering (fe-stack markdown); version read from the starci-academy package-lock on 2026-10-13.'
+  'remark-gfm':
+    version: 4.0.1
+    group: ui
+    side: fe
+    why: 'GitHub-flavoured markdown for react-markdown (fe-stack markdown); version read from the starci-academy package-lock on 2026-10-13.'
+  'remark-directive':
+    version: 4.0.0
+    group: ui
+    side: fe
+    why: 'markdown directives for react-markdown (fe-stack markdown); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-shiki':
+    version: 0.9.2
+    group: ui
+    side: fe
+    why: 'code highlighting (fe-stack code); version read from the starci-academy package-lock on 2026-10-13.'
+  '@monaco-editor/react':
+    version: 4.7.0
+    group: ui
+    side: fe
+    why: 'the code editor (fe-stack code); version read from the starci-academy package-lock on 2026-10-13.'
+  'mermaid':
+    version: 11.16.0
+    group: ui
+    side: fe
+    why: 'diagrams (fe-stack diagrams); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-dropzone':
+    version: 15.0.0
+    group: ui
+    side: fe
+    why: 'file drop zones of uploads (fe-stack upload); version read from the starci-academy package-lock on 2026-10-13.'
+  'react-pdf':
+    version: 10.4.1
+    group: ui
+    side: fe
+    why: 'PDF viewing (fe-stack pdf); version read from the starci-academy package-lock on 2026-10-13.'
+  '@fingerprintjs/fingerprintjs':
+    version: 5.2.0
+    group: framework
+    side: fe
+    why: 'the device id of the GraphQL fingerprint link (fe-stack device-id); version read from the starci-academy package-lock on 2026-10-13.'
+  '@sentry/nextjs':
+    version: 11.7.0
+    group: framework
+    side: fe
+    why: 'error reporting through sentry.*.config.ts and instrumentation.ts (fe-stack observability); the latest registry version on 2026-10-13, academy has none.'
+  # --- back-end transports the front end calls, and the realtime gateway
+  '@nestjs/graphql':
+    version: 13.4.5
+    group: framework
+    side: be
+    why: 'the GraphQL transport of every back end (be.transport.graphql) that the front end calls; the ecommerce-app resolution on 2026-10-13.'
+  '@nestjs/apollo':
+    version: 13.4.5
+    group: framework
+    side: be
+    why: 'the Apollo driver of @nestjs/graphql; the ecommerce-app resolution on 2026-10-13.'
+  '@apollo/server':
+    version: 5.5.1
+    group: framework
+    side: be
+    why: 'the Apollo server behind @nestjs/apollo; the ecommerce-app resolution on 2026-10-13.'
+  '@nestjs/websockets':
+    version: 11.2.5
+    group: framework
+    side: be
+    why: 'the socket.io gateway of a realtime back end (lite runs it in the api process, owner ruling 2026-10-13); the @nestjs/core pin line.'
+  '@nestjs/platform-socket.io':
+    version: 11.2.5
+    group: framework
+    side: be
+    why: 'the socket.io platform of @nestjs/websockets; the @nestjs/core pin line.'
+  '@as-integrations/express5':
+    version: 1.1.2
+    group: framework
+    side: be
+    why: 'the Express 5 integration @nestjs/apollo loads at boot (R111 nestjs-apollo-express5, knowledge/hfs/peer-integrations.yaml); every api app that serves GraphQL installs it; the latest registry version on 2026-10-13.'
   # --- Supabase lite
   '@supabase/ssr':
     version: 0.12.7

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

@@ -0,0 +1,218 @@
+schema: starci/fe-stack@1
+purpose: >-
+  The front-end stack of every app, lite and full alike (owner ruling 2026-10-13, R212 case-2): for each common front-end concern the
+  ONE canonical library, its HFS home (slot ids of knowledge/hfs/slots.yaml), the pattern id that teaches it
+  (knowledge/patterns/fe/*.yaml) and the alternatives a front end never depends on or imports. Versions live in
+  knowledge/hfs/canon-pins.yaml only. `tier: core` packages are installed by every scaffold; `opt` packages are added when a feature
+  needs the concern. Source example: starci-lab/starci-academy (origin/main, 2026-10-13); it illustrates, this file decides.
+concerns:
+  - id: framework
+    tier: core
+    packages: [next, react, react-dom, typescript]
+    home: [fe.route, fe.source-root-pinned]
+    pattern: FE-ROUTE
+    forbids: []
+    why: App Router with thin routes; route handlers (except health/live and the auth callback slot) and Server Actions are refused by FE_ROUTE_HANDLER_FORBIDDEN and FE_SERVER_ACTION_FORBIDDEN.
+  - id: graphql
+    tier: core
+    packages: ['@apollo/client', graphql]
+    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.
+  - id: codegen
+    tier: core
+    packages: ['@graphql-codegen/cli', '@graphql-codegen/client-preset']
+    home: [fe.modules.api]
+    pattern: FE-WIRE-GENERATED
+    forbids: []
+    why: the wire types are generated from be/contracts/<app>/schema.graphql into modules/api/graphql/__generated__, never typed by hand.
+  - id: rest
+    tier: core
+    packages: [axios]
+    home: [fe.modules.api]
+    pattern: FE-API-REST
+    forbids: [ky, superagent, node-fetch, cross-fetch, isomorphic-fetch]
+    why: modules/api/rest/<area>/*.ts for uploads, presigned URLs and auth endpoints only; GraphQL carries every other call.
+  - id: data
+    tier: core
+    packages: [swr]
+    home: [fe.hooks.swr]
+    pattern: FE-DATA-SWR
+    forbids: ['@tanstack/react-query', react-query]
+    why: hooks/swr/api/{graphql,rest}/{queries,mutations}/use*Swr.ts wrap one operation each; components call hooks only.
+  - id: toast
+    tier: core
+    packages: ['@heroui/react']
+    home: [fe.modules.toast]
+    pattern: FE-TOAST
+    forbids: [sonner, react-toastify, react-hot-toast, notistack]
+    why: mutation outcomes are reported by modules/toast (showGraphQLToast, use*WithToast) with next-intl labels.
+  - id: forms
+    tier: core
+    packages: [react-hook-form, '@hookform/resolvers', zod]
+    home: [fe.hooks.rhf]
+    pattern: FE-FORM
+    forbids: [formik, yup, final-form, react-final-form]
+    why: hooks/rhf/use<X>Form.ts builds a zod schema with next-intl messages and submits through an SWR mutation and the toast.
+  - id: state-global
+    tier: core
+    packages: ['@reduxjs/toolkit', react-redux]
+    home: [fe.redux]
+    pattern: FE-STATE-REDUX
+    forbids: [mobx, mobx-react, mobx-react-lite, recoil, jotai, valtio, redux-saga]
+    why: app-wide shared state (selected ids synced from the route, server-pushed entities) lives in redux/slices.
+  - id: state-local
+    tier: core
+    packages: [zustand]
+    home: [fe.hooks.zustand]
+    pattern: FE-STATE-ZUSTAND
+    forbids: []
+    why: feature-local UI, wizard and editor state lives in hooks/zustand/<store>.
+  - id: realtime
+    tier: opt
+    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.
+  - id: auth
+    tier: core
+    packages: []
+    home: [fe.modules.auth]
+    pattern: FE-AUTH
+    forbids: []
+    why: modules/auth is the identity-provider client (lite - the @supabase/supabase-js auth client; full - the app's IdP client); it yields the session and the access token for the Apollo link and never reads data.
+  - id: i18n
+    tier: core
+    packages: [next-intl]
+    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.
+  - id: ui
+    tier: core
+    packages: ['@heroui/react', '@heroui/styles', tailwindcss, '@starci/grammar']
+    home: [fe.components, fe.feature]
+    pattern: FE-UI
+    forbids: ['@mantine/core', '@mui/material', '@chakra-ui/react', antd, styled-components, '@emotion/react', '@emotion/styled']
+    why: the grammar renderers over HeroUI and Tailwind; no second UI kit and no CSS-in-JS.
+  - id: icons
+    tier: core
+    packages: ['@phosphor-icons/react']
+    home: [fe.components]
+    pattern: FE-ICON
+    forbids: [react-icons, lucide-react, '@iconify/react', '@gravity-ui/icons', '@tabler/icons-react', '@fortawesome/react-fontawesome']
+    why: one application icon set.
+  - id: theme
+    tier: core
+    packages: [next-themes]
+    home: [fe.components.providers]
+    pattern: FE-THEME
+    forbids: []
+    why: the theme provider lives in components/providers.
+  - id: motion
+    tier: opt
+    packages: [framer-motion]
+    home: [fe.components]
+    pattern: FE-MOTION
+    forbids: [react-spring, '@react-spring/web', gsap]
+    why: one motion library.
+  - id: dates
+    tier: core
+    packages: [dayjs]
+    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.
+  - id: numbers
+    tier: opt
+    packages: [decimal.js]
+    home: [fe.modules]
+    pattern: FE-NUMBER
+    forbids: [big.js, bignumber.js, numeral]
+    why: decimal.js for money arithmetic in modules/utils; display through the next-intl formatter.
+  - id: storage
+    tier: core
+    packages: [superjson]
+    home: [fe.modules]
+    pattern: FE-STORAGE
+    forbids: [localforage, store2]
+    why: modules/storage (local and session storage) serializes through modules/superjson; components never touch storage directly.
+  - id: utils
+    tier: opt
+    packages: [lodash, usehooks-ts]
+    home: [fe.modules, fe.hooks.reuseables]
+    pattern: FE-UTILS
+    forbids: [underscore, ramda, lodash-es]
+    why: per-method lodash imports in modules/utils and reusable hooks in hooks/reuseables.
+  - id: charts
+    tier: opt
+    packages: [recharts]
+    home: [fe.components]
+    pattern: FE-CHART
+    forbids: [chart.js, react-chartjs-2, '@nivo/core', d3, echarts, echarts-for-react]
+    why: one chart library, styled by the dataviz grammar.
+  - id: flow
+    tier: opt
+    packages: ['@xyflow/react']
+    home: [fe.components]
+    pattern: FE-FLOW
+    forbids: [reactflow, cytoscape]
+    why: graph canvases go through the grammar FlowGraph over React Flow.
+  - id: markdown
+    tier: opt
+    packages: [react-markdown, remark-gfm, remark-directive]
+    home: [fe.components]
+    pattern: FE-MARKDOWN
+    forbids: [marked, markdown-it, showdown]
+    why: markdown renders through react-markdown, never dangerouslySetInnerHTML.
+  - id: code
+    tier: opt
+    packages: [react-shiki, '@monaco-editor/react']
+    home: [fe.components]
+    pattern: FE-CODE
+    forbids: [prismjs, react-syntax-highlighter, highlight.js, '@uiw/react-codemirror', codemirror]
+    why: react-shiki highlights and Monaco edits.
+  - id: diagrams
+    tier: opt
+    packages: [mermaid]
+    home: [fe.components]
+    pattern: FE-DIAGRAM
+    forbids: []
+    why: diagrams render through mermaid in a block.
+  - id: upload
+    tier: opt
+    packages: [react-dropzone]
+    home: [fe.components, fe.modules.api]
+    pattern: FE-UPLOAD
+    forbids: [react-dropzone-uploader, filepond, react-filepond, uppy]
+    why: react-dropzone in a block and a presigned PUT through modules/api/rest.
+  - id: pdf
+    tier: opt
+    packages: [react-pdf]
+    home: [fe.components]
+    pattern: FE-PDF
+    forbids: ['@react-pdf-viewer/core', pdfjs-dist]
+    why: PDF viewing through react-pdf in a block.
+  - id: device-id
+    tier: opt
+    packages: ['@fingerprintjs/fingerprintjs']
+    home: [fe.transport.client]
+    pattern: FE-API-GRAPHQL
+    forbids: []
+    why: the fingerprint link of the Apollo client attaches the device id.
+  - id: observability
+    tier: opt
+    packages: ['@sentry/nextjs']
+    home: [fe.source-root-pinned]
+    pattern: FE-OBSERVE
+    forbids: [logrocket, bugsnag-js, '@bugsnag/js', '@datadog/browser-rum']
+    why: errors are reported through @sentry/nextjs (sentry.*.config.ts, instrumentation.ts), never console-only.
+  - id: lint
+    tier: core
+    packages: [eslint, prettier, '@starci/eslint-canon-fe', '@starci/prettier-config']
+    home: [fe.tool-config]
+    pattern: FE-LINT
+    forbids: []
+    why: the canon lint and format configuration.