@mpfrontend/ai-skills 0.0.0-stage → 1.0.0

package/skills/mpfrontend-configure-i18n/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: mpfrontend-configure-i18n
+description: Configure the MP Frontend locale registry (English ships; a product adds its own locales, left to right or right to left, or replaces English, in its own repository), product-owned translations, right-to-left behavior, locale-aware digits and the locale the BFF sends upstream. Not automatic backend content translation.
+---
+
+# Configure locales
+
+Read the consumer's locale policy, instructions and installed `@mpfrontend/i18n` exports. MP Frontend
+ships English (`en`, left to right) only; every other language is the product's and lives in the product's
+repository. `createLocaleRegistry({locales, defaultLocale})` configures the app's own set: each entry names
+its direction (`ltr` or `rtl`) and, optionally, a `numberingSystem` for Intl digits. The default locale is
+configured per app and is `en` when unset; a product may register only its own locale and make it the
+default, and a registry without `en` names its default. Direction always comes from the registry; never
+derive it from a list of codes in feature code. `Locale` is a plain locale code and
+`LocaleOf<typeof registry>` types one registry's codes. `locale`, `direction`, `translator`, `formatValue`,
+`formatNumber`, `negotiateLocale` and MessageKey remain the public helpers; the built-in registry behind
+`locale` and `direction` knows English only, so pass the app's registry.
+
+Keep the app's registry in `src/config/app.ts`, with the shared preference cookie
+(`createPreferenceCookie({name, locales, themes})`) that carries the language and theme for the first paint
+and for the identity provider's `ui_locales`. Validate a persisted or requested locale with the
+registry's `locale`; an unknown value is the default. Set document `lang` and `dir` together from the
+registry, and use logical CSS start/end rather than left/right. Preserve the existing persistence and
+avoid SSR/hydration disagreement. Changing locale must not reset auth, cart or an editing draft.
+
+Upstream language is an allowlist in the Security BFF: `apiLocales: {supported, defaultLocale}`. The BFF
+negotiates the browser's Accept-Language against it and sends only an allowlisted token, the default
+otherwise; without configuration it sends only `en`. A product lists the locales its backends answer in,
+which may exclude English. The login `ui_locales` allowlist (`supportedUiLocales`) is separate.
+
+Write every visible text as a catalog message. The app-wide set is `src/i18n/messages/<locale>.ts` and each
+feature has `model/messages/<locale>.ts`: the default locale's file uses `defineMessages` and defines the
+keys and their parameters; every other locale is typed `Translation<typeof base>`. Build translators with
+`createMessages` (core messages are a separate set the catalog may override). Use ICU MessageFormat with
+named parameters, `plural` and `select`; never join a translated message to other text or a value. Run the
+app's `catalog-check` target: it fails on a key missing in a locale, an unused key, a key that code uses
+and the base does not define, or differing parameters. The base catalog defines every key its code uses;
+the core messages are not a fallback for a key the base lacks.
+A key missing in a locale falls back, key by key, to the default locale at run time, but the check still
+fails on it. Translate the files that a generator reports as `untranslated`. To add a locale, register it
+and add `messages/<code>.ts` to every set, listed in the set's `translations`; to replace English, rename
+every base catalog to the product's locale and set each set's `defaultLocale`. A product whose default is
+not English never sees the English core text, so its catalogs define every key they use. Numbers use the
+locale's digits through Intl (`formatNumber`, `formatValue`); a `numberingSystem` in the registry
+overrides them, and `formatValue` takes the product's `labels` for booleans. Preserve identifiers and
+machine payload values; never translate free text that users wrote. Fonts with glyph coverage for the
+product's scripts, and their licences, are product-owned.
+
+Test supported and unknown locales, matching lang/dir, catalog key parity, digits and the forwarded
+Accept-Language for a crafted header. In the browser verify locale switching and reload, right-to-left
+forms, tables and logical layout, and mixed-direction identifiers. Run actual Nx gates uncached and report
+exactly which locales and surfaces passed.

package/skills/mpfrontend-configure-theme/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: mpfrontend-configure-theme
+description: Bind consumer-owned light and dark CSS tokens to the MP Frontend light/dark/system mode helpers. Not a Figma importer, token compiler or automatic design synchronization.
+---
+
+# Bind consumer themes
+
+Read the consumer instructions, its reviewed DLS tokens and installed `@mpfrontend/tokens` exports.
+Core offers `validBrand`, `validMode`, `appearance` and Mode; it ships no product brand registry or
+token values. Put product CSS, fonts, icons and assets in the consumer theme package. Keep a reviewed
+snapshot identity/provenance when tokens originate in Figma; never modify Figma through this workflow.
+
+Inspect the workspace design-source contract. An attached source and binding govern generated token
+ownership. Pending source state must be resolved before claiming DLS parity; `none` permits an authored
+code-first theme but not a claim that it implements either a private or public design system.
+
+Provide an explicit consumer brand allowlist/fallback to `validBrand`. Parse user mode through
+`validMode`; resolve system preference with `appearance`. Apply resolved light/dark selectors and
+semantic CSS variables consistently to document and components. Use the existing persistence and
+SSR initialization paths; clean up media-query listeners and avoid hydration disagreement. Explicit
+light/dark must not change with OS preference; system mode must. Theme switching must preserve
+locale, identity and active drafts.
+
+The theme (light, dark or system) and the language travel in one shared preference cookie
+(`createPreferenceCookie` of `@mpfrontend/i18n`, value `lang=<locale>&theme=<theme>`), which the identity
+provider's pages may read on a common parent domain. The app's server reads it for the first paint and sets
+`data-mode`, `lang` and `dir` before any script runs, so the page does not flash; an invalid value is
+ignored. The brand stays an app cookie. Never put an identity claim in that cookie.
+
+Each app has one theme file, `src/theme/theme.css`, that the global stylesheet imports after the neutral
+fallback of `@mpfrontend/tokens` and the component styles. Set token values there, scoped to a brand of
+`src/theme/config.ts` (for example `:root[data-brand='product'] { --mp-surface-canvas: ... }`), or import
+the generated `tokens.gen.css` of an attached design source from it. Raw colours are allowed only in the
+theme layer; lint refuses them elsewhere. `config.ts` keeps the brand registry.
+
+Map surface, text, border, focus, disabled and feedback colors from reviewed consumer tokens;
+include the mp-* CSS-variable interface used by the actual UI exports. Do not substitute a product
+palette into neutral core or hard-code a separate color in every component. Asset/font rights and
+readable contrast remain consumer acceptance work. Missing or unresolved tokens need an explicit
+reviewed mapping/fallback, not a claim of automatic design fidelity.
+
+Test mode parsing, allowed/rejected brands and system-dark transitions. In the actual browser check
+switching, reload, long text, focus/errors/disabled/loading states, tables/forms and right to left in both
+themes. Inspect resolved styles/contrast when visual acceptance is required; save native screenshots
+alongside interaction evidence. Run consumer lint/typecheck/test/build targets uncached.
+
+Report observed modes/surfaces and remaining visual gaps. This procedure does not import Figma,
+diff semantic revisions, advance a design baseline, publish packages or certify a complete DLS.

package/skills/mpfrontend-form-from-api/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: mpfrontend-form-from-api
+description: Bind a scalar MP Frontend ResourceForm to an explicitly generated required JSON request, with authored defaults and protected submission. Not response-to-form inference, nested widgets or guarded PATCH generation.
+---
+
+# Bind a selected request form
+
+Read the consumer instructions, pinned package exports and approved operation first. A review does
+not authorize a mutation. This finite workflow needs compatible FTG request generation; use
+`mpfrontend skills list --json` and the installed `mpfrontend-integrate-openapi` procedure when the
+request is not yet generated. Do not invent a mutation or turn response fields into editable inputs.
+
+Inspect the generated `requests` metadata and `RequestModels` for the exact named operation. The
+supported default ResourceForm fields are string, boolean, number and integer. Author defaults,
+labels, domain constraints and the payload adapter outside generated output. Refuse object/array
+fields rather than serialize them into scalar controls. Nullable, enum and optional-field UX needs
+an explicit authored adapter; the generic scalar form is not a complete schema widget registry.
+
+Use `ResourceForm` from `@mpfrontend/ui`, with the selected request's fields, controlled values,
+localized saveLabel, labels, helpers, errors and onChange. A required JSON boolean can validly be false: do not
+interpret it as mandatory consent. When the page has an access snapshot, pass `access={useAccess()}` from
+`@mpfrontend/access-react` and the loaded values as `original`: a field the person may not view is not rendered
+(its label, helper and error with it) and leaves validation and the submitted values, a field they may not edit is
+disabled, and `onSubmit` receives only the changed fields they may edit (`dirtyPatch`); a changed field they may
+not edit throws `FORBIDDEN_FIELD` instead of being sent. Field access comes from the server's snapshot only, never
+from the schema, a role name or a guess. Keep busy disabled states, empty-form rejection, integer/decimal behavior
+and errors accessible. Remount or clear the draft when authority or the edited resource changes. A remote refresh
+must not silently overwrite an active editing draft.
+
+Construct the declared body in an authored adapter, call generated `parseRequest` immediately before
+submission, then retain the existing protected transport, CSRF, idempotency and authority fencing.
+Validate at the server boundary too; never trust a browser-only guard. Backend business rules and
+permissions remain authoritative. Handle actual 200/201/202 response contracts independently;
+no fallback success, read-derived partial PUT, guessed PATCH or field-access inference.
+
+Test the actual adapter with valid and rejected inputs, unknown/read-only fields, disabled and
+empty forms, both boolean values and relevant domain limits, and with an access snapshot a hidden field, a
+field without edit and a save that sends only the changed editable fields. Prove invalid input never reaches
+the transport; remove that guard only in an isolated negative-control fixture and require the
+real assertion to fail. Verify labels and focus/error behavior left to right and right to left, and light/dark.
+Run the consumer's actual generation/check, lint, typecheck, test and build targets uncached.
+
+Report the selected operation, observed tests and remaining widget/access/concurrency gaps.
+No live write, deployment, publication or complete production-form acceptance is implied.

package/skills/mpfrontend-implement-feature/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: mpfrontend-implement-feature
+description: Implement one approved MP Frontend feature slice across an existing consumer app, generated API boundary and UI, then verify its real states. Use only when story, contract, access and design decisions already exist.
+---
+
+# Implement an approved feature slice
+
+Requires the reviewed MP Frontend CLI `1.0.0` cohort. Read repository instructions, the approved
+story and acceptance criteria before editing. Stop when the API contract, permission, tenant rule,
+business transition or DLS behavior is absent or contradictory; never invent it to complete a screen.
+
+Map the slice before coding: route and entry point, approved OpenAPI operations, generated read/request
+models, authored domain transformations, access decisions, visual states and the smallest affected Nx
+projects. Keep route files thin. Product rules and presentation stay consumer-owned. Treat generated
+FTG outputs and accepted design artifacts as read-only; change their declared source/configuration and
+regenerate instead of hand-editing them.
+
+Create the structure with the generators, not by hand: `pnpm exec mpfrontend create feature --app
+<app-directory> --name <feature> [--resource <ftg-resource>] --dry-run --json`, then without `--dry-run`,
+and `mpfrontend create route` for each screen (a detail view is a child route, for example
+`<feature>/[position]`). A feature keeps the view in `ui/`, workflow state in `model/` and `hooks/`,
+requests and persistence in `api/` and small pure helpers in `utils/`; code outside it imports only its
+`index.ts`, which lint enforces. Types and rules that several features of one entity share go in
+`src/entities/<entity>/`; code that two apps need goes in a package from `mpfrontend create package`.
+Never invent a contract or an endpoint to fill a generated file; a screen feature stays unbound until
+an approved contract adapter exists. Every visible text of the feature is a message in its
+`model/messages/<locale>.ts` catalogs, with named parameters placed by each message; translate the
+locales the generator reports as `untranslated`, and keep `catalog-check` and the `no-literal-text` lint
+rule passing. A sensitive write sends an `Idempotency-Key`; when the BFF answers `STEP_UP_REQUIRED`, keep
+the person's input, run the step-up and resubmit only a request whose `resubmit` is `idempotent`, with the
+same key. Never replay a write without a key automatically. A feature that uploads or downloads a file
+uses the app's transfer route (`/api/transfer/...`), which relays a streamed BFF route as streams: send
+the file as the request body with its Content-Type and Content-Length, the CSRF token and, for a
+sensitive write, an idempotency key; read a download as a stream; handle 411, 413, 415, 401, 502 and 504
+as states of the slice. Never read a whole file into memory to send it, and never invent a route,
+media type or size that the BFF's approved stream policy does not declare.
+
+Use `mpfrontend-integrate-openapi`, `form-from-api` or `table-from-api` only for selected finite contract
+shapes. Every new route gets one entry in the app's page manifest (`definePageManifest`) with the capability its
+page and menu entry need and its elements and fields, and the manifest test (`assertPageManifest` with
+`appRoutes`) stays green. Read and write server data in client components only through `@mpfrontend/data-react` (`useScopedQuery`,
+`useScopedMutation`, under the app's `QueryScope`), through the app's own routes or the BFF; never retry a write
+automatically and never add a global client store. Keep page, sort, filter and similar screen state in the URL with
+`listUrlState` and `useTableUrlState`, never the scope or a personal value. A list over a backend declares its
+paging, sorting and filtering as a `ListProtocol` checked against the contract. Present access from the server's
+snapshot with `@mpfrontend/access-react`
+(`AccessProvider`, `AccessGuard`, `AccessLink`, `useCapability`, `useFieldState`) as `mpfrontend-apply-access`
+describes; never from a role name. Publish protected asynchronous results through `@mpfrontend/access-core`
+`AuthorityFence` (`useAccessCapture()` inside a provider) and keep backend/BFF authorization authoritative. Compose `@mpfrontend/ui` primitives through the
+consumer DLS adapter; do not copy sample branding into neutral code.
+
+Implement loading, empty, success, validation, denied and recoverable error states required by the
+criteria. Preserve unsaved input across safe retries and refuse stale identity/tenant/role-revision
+results. Locale, theme, responsive and keyboard behavior are part of the slice when the approved
+design includes them.
+
+Run affected Nx `lint`, `typecheck`, `test`, `build`, `generated-check` and `design-verify` targets
+uncached where defined. Exercise positive and negative API/access states and inspect the actual browser
+surface at required viewports/locales/themes. Report exact commands and counts plus any unverified
+criteria. Implementation does not authorize Git operations, deployment, publication, Figma writes,
+role creation or acceptance-baseline changes.

package/skills/mpfrontend-import-design-system/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: mpfrontend-import-design-system
+description: Import a supplied normalized local DLS export as an immutable MP Frontend candidate with source provenance and explicit consumer mappings. Does not change Figma or accept the candidate baseline.
+---
+
+# Import a declared design export
+
+Requires MP Frontend CLI 1.0.0 or the reviewed compatible cohort. Read the consumer instructions,
+installed CLI `DESIGN-SYNC.md`, approved source and its distribution limits. Check the actual
+`mpfrontend --version`. The CLI consumes a finite normalized export; it does not capture Figma.
+Prefer supplied local evidence. If another authorized read connector is available, follow that
+connector's instructions; missing access is a prerequisite, not permission to invent source details.
+
+Run `mpfrontend design status --directory <consumer> --json` before import. A pending `existing` source
+needs the approved consumer binding attached with `design attach --source existing`. The consumer owns
+the Figma/DLS, export, mapping and rights; no public release manifest is accepted in the MVP. A `none`
+workspace may transition to `existing` only when the implementation request and supplied provenance
+identify a real consumer-owned source. Do not attach merely to make import pass.
+
+Preserve the raw export and digest in the consumer. Record file/node IDs, available source revision,
+actual capture/extractor identity and the declared scope. Unknown revision stays null; unavailable
+behavior stays unknown. Review any mode/collection/type projection. The current profile supports
+light/dark scalar tokens and aliases, declared component variants/properties/behavior and asset
+metadata. Unsupported expressions, extra modes or raw export shapes need an explicit adapter/review;
+never silently erase them to pass validation. A token-only export is not the complete DLS.
+
+Create a consumer-owned root binding from the documented schema: explicit source IDs to CSS names,
+brand/mode selector, adapter/test paths and reasoned exclusions. Keep product assets, snapshots,
+fonts and palettes out of neutral core. Unknown asset rights do not become cleared by Figma access.
+
+Run `mpfrontend design import --binding <file> --snapshot <export> --dry-run --json`, inspect its
+candidate hash/diagnostics, then import only within the requested implementation scope. Re-import
+must preserve immutable bytes. Run validate and diff with that exact candidate; report unmapped
+tokens, unknown behavior and unsupported cases. Do not apply or accept a baseline under an import-only
+request. Never force over an authored collision or delete another writer's marker.
+
+Report provenance, scope, actual commands and what remains unresolved. No Figma write, watcher,
+deployment, package publication or actual agent-parity acceptance follows from an import.

package/skills/mpfrontend-integrate-auth/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: mpfrontend-integrate-auth
+description: Integrate an existing consumer with the MP Frontend server-side OIDC BFF, opaque cookie session and explicit route policy. Use for approved identity-provider settings, not for creating realms, users, roles or credentials.
+---
+
+# Integrate server-side authentication
+
+Requires the reviewed MP Frontend CLI `1.0.0` cohort and `@mpfrontend/security-bff`. Read the
+consumer instructions and obtain approved issuer, client, callback/logout URLs, audiences, route policy,
+cookie domain and supported UI locales. Missing provider metadata or secret ownership is a prerequisite,
+not permission to create identity data.
+
+Configure authorization code plus PKCE through the server BFF. Keep access, refresh and ID tokens on
+the server; the browser receives only the bounded opaque `HttpOnly`, `Secure` production cookie. Apply
+same-origin and CSRF controls to state-changing BFF routes, validate state/nonce/issuer/audience/time,
+and use explicit route/method/role allowlists. Forward only an allowlisted locale through standard
+`ui_locales`; the identity provider remains responsible for translating its own forms. Configure
+`apiLocales: {supported, defaultLocale}` for the Accept-Language that the BFF sends upstream (English
+only by default; a product lists the locales its backends answer in); the BFF negotiates the browser's header against it
+and never forwards the header as given. Project only the claims the UI needs into `/context` with
+`contextClaims` (an allowlist; ID token by default, refreshed ID token at refresh); never project a token,
+never write a claim into a cookie and never treat a projected claim as authorization. Configure
+`preferenceCookie` with the shared language and theme cookie so that login pages receive `ui_locales`.
+
+Use the in-memory session store only for local development. Beyond developer machines configure the
+production profile, `production: {sessionVault, clientAuthentication, secureCookies: true}`, with a Redis
+vault over `rediss:` with host-supplied credentials and key ring; the package refuses any unmet condition
+by name (`PRODUCTION_PROFILE_REFUSED:...`). Resolve the named condition in the deployment; never bypass a
+refusal or describe the profile as a production HA claim. Each front end is the confidential client of its
+issuer: configure `clientAuthentication` with `private_key_jwt` (the host's private key and key id, or a
+function returning the current one for rotation) or `client_secret_basic`; a public client must be declared
+with `publicClient: true`. Keep the key or secret in the host's secret store; never put it in a file of the
+repository, a log or an error. Set the session policy for the product's risk: a
+`__Host-` session cookie (default in production), `sameSite: 'Strict'`, an idle timeout (default 30
+minutes) and an absolute lifetime within their bounds; never shorten a lifetime the product owner set, and
+expect 401 on an idle or expired session and a rotated session cookie after a role change. When the provider
+must end sessions at once (an account disabled, a provider logout), enable `backChannelLogout` and route
+`POST /backchannel-logout` only from the provider's network path; register that URL as the client's
+back-channel logout URL in the provider without changing provider configuration yourself. For
+sensitive operations give the route `authentication: {maxAge}` (and `acr` only when the product defines
+levels in `acrValues`); handle the typed `STEP_UP_REQUIRED` answer by sending the person to its `login`
+path with an allowlisted `return_to`, and list every return path in `returnPaths`. For files that pass
+between the browser and a backend, give the route a `stream` policy with the product's approved request
+and response media types, maximum size, response headers, idle and total timeouts and session check
+interval; nothing has a default, so ask for each value rather than inventing it. Relay it from the
+presentation application with `createRelay` of `@mpfrontend/presentation-server/relay` (the template's
+`/api/transfer/...` route) and set `BFF_SESSION_COOKIE` to the BFF's session cookie name. A streamed
+upload declares Content-Length; never parse, inspect or log a streamed body or a file name in the
+presentation application. Never log tokens, authorization codes, cookies, client secrets or personal data.
+
+Add focused tests for login/callback, state replay, nonce/issuer/audience/expiry rejection, logout,
+refresh rotation/outage, CSRF/origin rejection, locale propagation and absence of browser token
+exposure; for a streamed route also 411, 413 and 415 before any upstream call, a refused response type,
+the headers that cross, and a transfer ended by logout, timeout and cancellation. Verify an actual browser sign-in and return URL without collecting real credentials. Record
+the approved cookie/session settings and remaining HA/TLS/key-rotation work.
+
+Do not create or mutate Keycloak realms, clients, users, roles, resources or grants through this skill.
+Do not replace an existing auth architecture, weaken production guards, deploy or publish without a
+separate explicit request.

package/skills/mpfrontend-integrate-openapi/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: mpfrontend-integrate-openapi
+description: Integrate approved local OpenAPI 3.1 responses or explicitly selected required JSON requests with FTG models and standalone validators, preserving authored overrides. Does not invent APIs, authorize writes or infer form transforms.
+---
+
+# Integrate an explicit API contract
+
+Requires MP Frontend CLI `1.0.0`. Read the consumer instructions and the named API owner's
+contract before edits. An implementation request permits scoped integration; a review alone does not.
+
+Establish the public presentation boundary: browser paths, server operation bindings, auth/roles,
+errors and the fields intentionally exposed. A backend URL, response example or DTO is not an
+approved browser contract. Preserve the internal/private boundary and any existing exposure policy.
+Record upstream identity/digest and explicit projection differences; do not fabricate missing success
+schemas. Ask the API owner to correct its OpenAPI or get a reviewed projection before proceeding.
+
+The current generator supports finite OpenAPI 3.1 object/array read shapes, required versus nullable,
+primitive enums and scalar dictionaries. It rejects recursive/unsupported composed types, meaningful
+reference siblings and mixed fixed/dictionary signatures. Unsupported diagnostics are prerequisites,
+not permission to erase constraints. Response fields are always non-editable; a response cannot
+become a write contract merely because it lacks readOnly annotations.
+
+Configure a local `ftg.config.json` with `openapi`, `output` and explicit `resources` selections
+(`name`, `operationId`, optional `responsePath` and explicit `responseStatus` 200/201/202; default 200).
+`responsePath` selects table fields; generated `ReadModels` and `parseRead` validate the **whole
+selected JSON response**, not just the selected row. Do not relabel a 201/202 operation as 200.
+Use a new/owned generated output location, retaining all authored overrides separately.
+
+For an authorized input integration, select a separate `requests` entry by its exact `name` and
+`operationId`. The current profile requires a mutation operation with a required application/json
+object body and explicitly closed objects at every level. `RequestModels`, `requests` metadata and
+`parseRequest` validate this declared body: read-only fields are excluded/forbidden, write-only
+inputs are included, and unknown fields/constraints are not stripped or coerced. An open or optional
+body requires a reviewed contract/profile decision, not a guessed allowlist. Form defaults, widgets,
+read-to-form mappings and dirty-field transforms remain authored. A complete PUT body is not a
+guarded partial update; do not infer PATCH, concurrency or field permissions from these types.
+
+Check `pnpm exec mpfrontend --version`. Run `pnpm exec ftg generate --config <config> --dry-run
+--json`, inspect the plan, then generate only within the requested implementation scope. Run
+`pnpm exec ftg check --config <config> --json`. A lock/collision/drift failure needs inspection of
+its actual owner; never delete a live writer marker or use force overwrite.
+
+Use the exact pinned Ajv/ajv-formats runtime-helper dependencies from the compatible template.
+Generation compiles standalone validators; do not compile schemas dynamically in the browser or
+weaken CSP with unsafe-eval. Call generated `parseRead` before protected results reach state/rendering,
+while keeping the consumer's authority/abort fence. Its generic error must not log response payloads.
+
+Verify valid and malformed actual-contract responses, nullable/optional fields, required values,
+extra/write-only fields, formats and numeric/string/array limits as applicable. No coercion, default
+insertion, field stripping or business mutation may hide an invalid read. Prove drift failure in an
+isolated fixture and show that regeneration preserves authored overrides. Run actual Nx targets
+uncached; compare the FTG manifest hash with the immutable contract served to Swagger.
+
+For selected requests, also prove rejection of read-only/unknown fields, malformed nested inputs,
+and missing write-only required values without logging them. Validate before the existing protected
+server mutation path; generated validation never replaces CSRF, identity, roles or backend enforcement.
+Prove unknown resource/request names cannot invoke inherited validator-object properties.
+
+Report observed commands, counts, contract identities and gaps. Format/source installation does not
+prove Codex/Claude behavioral parity. Do not change Figma, publish, deploy or claim production-ready
+authorization, HA or complete write-model acceptance from generated read models.

package/skills/mpfrontend-integrate-realtime/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: mpfrontend-integrate-realtime
+description: Integrate an approved realtime event contract with MP Frontend ticket admission, bounded browser recovery and authority revision checks. Use only when topic/event ownership and snapshot semantics are already defined.
+---
+
+# Integrate an approved realtime stream
+
+Requires the reviewed MP Frontend CLI `1.0.0` cohort and `@mpfrontend/realtime-core`. Read the
+consumer instructions plus the approved event/topic schema, ordering/idempotency rules, admission
+policy and snapshot endpoint. Stop rather than inventing event names, replay guarantees or recovery
+semantics.
+
+Issue short-lived one-use admission tickets server-side. Never place service tokens, broker credentials
+or durable session material in the browser. Configure `useRealtime` with bounded resources, the current
+authority revision, required `onSnapshot` recovery and a generic `onUnavailable` state. Treat realtime
+messages as invalidations or declared events; after gaps, reconnects or uncertainty, recover from the
+authoritative snapshot before publishing state.
+
+Bound reconnect delay, jitter, attempt/rate budgets and cancellation. Coalesce duplicate invalidations,
+discard messages and snapshots from stale sockets/subjects/tenants/role revisions, and preserve safe
+unsaved drafts during recovery. Do not claim durable replay, exactly-once delivery or production HA
+unless the approved server contract and deployment evidence provide it.
+
+Test ticket admission and replay refusal, reconnect/backoff, quota `429`, snapshot failure/hang,
+duplicate/coalesced events, revocation, identity/tenant change, stale socket delivery and successful
+recovery. Include a failing control for the admission floor or stale-authority property. Verify the
+actual browser state through an interruption.
+
+Report commands/counts, observed recovery evidence and remaining infrastructure gates. Do not create
+broker topics, alter production quotas, deploy or publish through this skill.

package/skills/mpfrontend-prepare-release/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: mpfrontend-prepare-release
+description: Prepare a bounded MP Frontend source and package cohort for release by proving clean-consumer installation, packed contents, API policy and reference gates, then hand the owner the release workflow's rehearsal. Stops before commit, tag, push, registry, deployment or Figma publication.
+---
+
+# Prepare release evidence
+
+Obtain the approved release scope, versions, package/repository names, license choice, distribution
+rights and acceptance criteria. A missing license, private asset right or repository name is a blocker,
+not a default for the agent to choose. Read all repository instructions and inspect existing changes;
+do not absorb unrelated work into the candidate.
+
+Verify source for credentials/private keys, personal/product-only data, private design-library links,
+provenance gaps and undeclared local dependencies. Run frozen installation plus the actual Nx `lint`,
+`typecheck`, `test` and `build` gates, generated/design drift checks and repository skill validation.
+Pack the declared cohort and inspect every manifest, export, executable and file list. Packed manifests
+must contain no `workspace:` or checkout-only dependency and each immutable version must identify one
+content set.
+
+Install the packed artifacts into a fresh independent consumer and exercise real CLI init, skill
+install/check, scaffold, FTG generation/drift, security/realtime controls and consumer build. Exercise
+both MVP design-source init contracts. Prove `none` remains usable and `existing` attaches a
+consumer-owned binding without public-release metadata. Prove the deferred `mpfrontend` public-template
+mode is rejected rather than advertised without a shipped Community DLS. Run the approved
+reference applications' artifact verification, frozen install and full gates. Confirm a clean-clone
+consumer has an obtainable dependency path; ignored local tarballs alone are not a public release
+strategy. Keep advisory-service uploads opt-in and report them as not run when unauthorized.
+
+MP Frontend releases one cohort version for every package: the version that the root `package.json` and every
+package declare, with every framework pin (the app template, the Nx plugin's cohort, the AI procedures) equal to it;
+`node tools/distribution/release.mjs guard --version <v> --ref <ref>` and its `self-test` prove this offline. A version
+the registry already holds is never built again: a corrected build takes the next version, and a bad version is
+deprecated, never unpublished. Check the API against the policy of README "Versioning" with `pnpm check` (the
+`api-check` of every package's `api-report.json` and of the published archives that
+`tools/distribution/api-baseline.json` names); from 1.0.0 a break needs a new major version and release notes that
+say how to move. After a release, move the baseline to it in a commit of its own with `node
+tools/distribution/api-report.mjs baseline --record <release.json>`. Run `pnpm exec nx run distribution:registry-install` for the scope binding and
+the exact pins against throw-away local registries. The owner then runs the release workflow
+(`.github/workflows/release.yml`) without `publish` as a rehearsal, and with it only on main, as
+docs/RELEASE-GUIDE.md describes.
+
+Produce the exact candidate file/package/version list, hashes, commands/counts, known limitations and
+separately named production gates such as HA/TLS/load/accessibility/security review. For a protected
+deployment, show that the Security BFF and the presentation server start with their production profiles
+in the target environment and record any `PRODUCTION_PROFILE_REFUSED:` reason as an open gate. Do not convert POC
+evidence into a production claim.
+
+Stop before `git init`, commit, tag, push, pull request, registry upload, a run of the release workflow,
+deployment, release creation, Figma write/publication or baseline acceptance. Never publish from a workstation,
+create an npm token or organization, or change a trusted-publisher or environment setting. Show the owner what would
+be published and obtain explicit authority for each external action.

package/skills/mpfrontend-reconcile-design-components/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mpfrontend-reconcile-design-components
+description: Reconcile declared added, changed or removed DLS components with MP Frontend consumer adapters and tests using reviewed semantic plans. Not automatic React generation or business-rule inference from Figma.
+---
+
+# Reconcile authored component behavior
+
+Requires the reviewed CLI 1.0.0 cohort, an attached design source and a normalized candidate with explicit interaction evidence.
+Read consumer instructions, installed CLI `DESIGN-SYNC.md`, approved source, adapter bindings and
+the actual public UI types. Use stable IDs for component identity; display renames do not justify
+creating duplicates. Core currently exposes six finite components, not the whole supplied DLS.
+Run `design status` before planning; source drift or a pending/disabled source blocks reconciliation.
+
+Run validate/diff/plan for the exact candidate. Inspect variants, props, documented behavior and assets
+alongside affected usages. Unknown mapped behavior or unmapped IDs needs a designer/developer decision.
+Figma visual/prototype information does not define auth, monetary semantics, validation or API writes.
+Do not infer those business rules. Scope authored tasks to the requested product; use neutral exports
+and consumer-owned tokens/assets. A missing reusable core behavior needs its own neutral contract/test.
+
+Review the plan before apply. Generated components.gen.json is metadata, never implementation.
+Implement approved adapter/interaction changes and regression tests outside owned outputs. For removals,
+keep reconciliation bindings until migrations/deprecations are reviewed; do not delete authored code or
+extensions automatically. Inspect disabled/loading, pointer/keyboard, focus restoration, errors,
+reduced motion and long text as applicable, left to right and right to left, and light/dark/system.
+
+Run actual feature/Nx/visual checks and record current adapter/test hashes in genuine reviewed task
+evidence. Unchanged mapped adapters still need matching verification. A CLI evidence digest is not
+proof that claimed behavior works; no synthetic fixture attestation may stand in for these runs.
+Missing/failed/unimplemented tasks prevent acceptance. Re-plan after source/binding/CLI/output drift.
+Promote only when the user authorized acceptance and all required evidence/review passes, then check.
+
+Report mapped scope and unresolved states explicitly. No automatic Figma change, protected business
+mutation, deployment or npm/public release authority is included.

package/skills/mpfrontend-review-design-drift/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: mpfrontend-review-design-drift
+description: Review an MP Frontend declared design candidate or accepted baseline for semantic, output and evidence drift without applying changes or promoting a baseline.
+---
+
+# Review declared design drift
+
+Requires the reviewed CLI 1.0.0 cohort. Read consumer instructions, installed CLI `DESIGN-SYNC.md`,
+accepted source/binding and any supplied candidate's provenance. A review request is read-only:
+do not import, persist a plan, apply tokens, edit Figma, run a live write or accept a baseline.
+If the candidate is not imported, an explicit import implementation request is a prerequisite.
+
+Begin with the read-only `mpfrontend design status --directory <consumer> --json`. Report disabled or
+pending source state as such. For `existing`, source distribution and provenance remain consumer-owned;
+binding drift is distinct from candidate/output drift. Do not attach, switch modes or repair files
+during a review request.
+
+Run `mpfrontend design check --binding <file> --json` for the accepted declared scope. With a named
+candidate, run validate and diff; a plan dry-run can identify affected owned outputs/authored tasks
+without writing state. Inspect stable IDs, removals/renames, alias/mode/type changes, component
+variants/props/behavior, assets and compatibility severity. Check declared omissions separately:
+a token-only export cannot prove that unspecified components are unchanged.
+
+Distinguish source drift from generated-output edits, stale CLI/binding/plans, changed evidence,
+unmapped IDs, unknown interaction/rights and another active writer. Baseline import/apply is not
+acceptance, and accepted output hashes do not prove a whole design system's visual fidelity.
+The CLI checks reviewed artifact identity/current files, not truthfulness of external test claims.
+
+Report the exact source/candidate/CLI identity, observed diagnostics and affected authored paths.
+Suggest scoped re-plan, migration, tests or designer review without silently repairing files. Preserve
+custom code and a writer's marker; recovery needs inspection and separate authority. Visual/source
+conflicts need explicit resolution, not a hidden palette edit. Publication remains a separate gate.

package/skills/mpfrontend-scaffold-app/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: mpfrontend-scaffold-app
+description: Create an independent MP Frontend Next.js app with the installed CLI and verify its Nx build and generated API boundaries. Does not initialize a production deployment or invent product configuration.
+---
+
+# Scaffold an app
+
+Requires MP Frontend CLI `1.0.0` and the compatible packaged Nx plugin. Read the consumer's
+repository instructions before changing files; this skill grants no release or external-write authority.
+
+Obtain the app name, new destination and an approved local OpenAPI projection. Do not choose a
+product DLS, identity provider, role catalog or backend endpoint. Confirm `pnpm exec mpfrontend
+--version`; unsupported versions need a bounded upgrade decision, not guessed flags.
+
+Run `pnpm exec mpfrontend create app --name <name> --directory <new-directory> --dry-run --json`.
+Inspect the proposed paths and run without `--dry-run` only within the user's implementation request.
+An existing destination is a collision; never remove it or use a force overwrite to make scaffolding pass.
+
+For an existing pnpm/Nx workspace, preserve its configuration and register its app glob only if missing.
+For an explicitly requested new product workspace, choose the design-source contract from evidence:
+`existing` for any consumer-owned DLS or `none` for a code-first product. The MVP does not ship or
+require a public Figma Community DLS. Do not silently default a known design-backed
+product to another source. Use `mpfrontend init --name <workspace-name> --directory
+<new-workspace-directory> --design-source <existing|none> --dry-run --json`, inspect its paths, then apply the command
+without dry-run only within the implementation request. The destination must not exist; do not
+remove/overwrite it on refusal. Init does not install packages or configure a protected runtime.
+Never initialize Git, deploy, publish or access/write Figma merely because scaffolding was requested.
+
+For `existing`, report the pending state until an approved consumer binding is attached. For `none`,
+continue code-first without pretending design acceptance. `design status` verifies the
+recorded choice but neither imports a snapshot nor approves a baseline.
+
+Place the approved contract at the path named by the
+generated `ftg.config.json`; never fabricate business fields. Install dependencies and validate a frozen
+install, then run the app's actual Nx `build`, `typecheck` and `generated-check` targets uncached.
+
+Create app writes one list route and one detail route over the catalog example, a `preferences`
+feature, `.env.example` with variable names only and `docs/overview.md` and `docs/api-contracts.md`;
+init writes `CODEOWNERS` with placeholder owners and `.agents/skills/README.md`, the guide for the
+workspace's own `project-*` and `domain-*` skills. Report the placeholder owners as a follow-up for the
+user; never fill in real owners or environment values yourself. Add features, routes and shared packages
+with `mpfrontend create feature`, `create route` and `create package`; see the CLI guide for what each
+writes and refuses.
+
+The app frame comes from `@mpfrontend/app-layout` (skip link, header, navigation slot, page frame); the
+template passes its own navigation items. `src/app/globals.css` holds only imports and base element
+rules: Tailwind v4, the UI and shell sources, the neutral tokens, the component styles and, last, the app
+theme file `src/theme/theme.css`. Apps created before the shell keep their own stylesheet; moving them
+to the shell replaces their hand-written layout classes with the shell components and utility classes.
+
+Init writes the quality profile: root `eslint.config.mjs` and `prettier.config.mjs` that re-export
+`@mpfrontend/workspace-config`, a `check` script, `tools/ci/check.sh` and a GitHub Actions workflow that
+runs it. Create app gives the app `format`, `format:check`, `lint` and `test` targets and an app
+`eslint.config.mjs` that spreads the workspace profile. Run `pnpm check --skip-nx-cache` on the new
+workspace; it runs the format check, lint, typecheck, test, build, generated-check and catalog-check. A
+lint failure on
+module boundaries, raw colours, hand-written CSS or a physical left or right is fixed in the code, never by
+switching a rule off.
+
+Inspect exports and imports: the new app must consume published/packed core packages and its own
+authored code, not the platform source checkout or a sample-only Nx target. Preserve authored
+overrides and demonstrate FTG regeneration/check. Report the commands and observed output; a
+generated directory alone is not a working app. If consumer libraries export build outputs, keep their
+Nx graph edges and the app build's explicit `^build` prerequisite; a project-level dependsOn array
+replaces the root default. Verify from an isolated checkout without pre-existing library dist so a
+local build cannot conceal incorrect task ordering. Declare library dist as an Nx output for restore.
+Missing contract or workspace configuration is a
+specific prerequisite, not permission to invent production infrastructure.