themelia-react-ui 2.0.2 → 2.0.4

package/docs/consumer-skill/references/composition-mapping.md

@@ -0,0 +1,92 @@
+# Executable composition mapping
+
+Use this when a screen needs several cooperating owners or when a component's
+surface and placement are unclear. The mapper resolves explicit responsibilities
+into exact public components and supported regions. The application still decides
+the user's priorities, data, commands and meaningful grouping.
+
+First resolve the installed package and verify copied guidance using
+[installed setup](installation.md). These commands assume its conventional
+`node_modules` location:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --roles
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --role facts
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --pattern record-detail --main invoice-lines --aside facts
+```
+
+For a complete copied bundle, use the shared skill's
+`scripts/map-composition.mjs` instead. It resolves `public-api.json` and
+`component-contracts.json` beside that script's shared references, independently
+of the current directory. Node is sufficient; the mapper does not load React,
+TypeScript, optional component peers or the consumer's application code.
+
+## Describe responsibilities, then inspect the plan
+
+1. Turn the business brief into independent subjects: for example invoice lines
+   in the main region and record facts in the supporting region. A responsibility
+   is a role tag reported by `--roles`; a complete business brief is not a role.
+2. Use `--role` to inspect a role's mapped owners. Role names accept spaces or
+   kebab-case. A qualified `themelia-react-ui/<family>#<Symbol>` selector chooses
+   an exact mapped contract when a role has several candidates.
+3. Select a pattern and repeat `--main` or `--aside` for each subject. Supported
+   patterns are `record-detail`, `collection`, `edit`, `analytics` and `embedded`.
+   They identify structural context; they do not install form state, fetch data
+   or choose application-specific variants. Edit plans explicitly retain the
+   application's native form and submission requirements.
+   Use `--limit 1..10` to bound candidate details; it does not discard requested
+   subjects or hide unresolved coverage.
+4. Read `tree`, `coverage`, `unresolved`, `warnings`, `requiredPeers`,
+   `applicationOwns` and the focused `nextReads` before implementing. Inspect each
+   chosen unfamiliar component with the [API inspector](discovery.md#inspect-a-selected-component).
+
+`requiredPeers` lists the selected families' additional optional package peers;
+`baselinePeers` lists the package's nonoptional peers. Both still require the
+installed setup and matching versions. An empty additional list does not remove
+React or Base UI requirements.
+
+The record-detail example resolves a route owner and, because support is
+requested, a main/support layout. Its `tree.slots` uses actual insertion props
+such as `children`, `main` and `aside`. Parent-surface content can receive a
+subject Card at that boundary. Already framed owners keep their own surface;
+variant-dependent owners require inspection before choosing framing.
+
+For an existing Card boundary:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --pattern embedded --parent Card --main facts
+```
+
+That plan uses the selected host's `children` region without adding another Page
+or Card. Qualify an ambiguous parent with `--import <exact public import>`.
+An embedded request without a parent leaves the host decision explicit; inspect
+its unresolved ownership before creating a new boundary.
+Only an explicitly declared route-child slot permits a Page inside a shell;
+AuthShell and bounded workspaces are ordinary content hosts. Variant-dependent
+hosts retain inspection warnings before another framed subject is added.
+
+## Read the result's scope
+
+The output is advisory JSON. `mapped` means the requested roles resolved under
+the mapper's supported contracts. It does not mean an application is implemented,
+accessible, visually accepted or ready for delivery. `partial` and `unresolved`
+retain requests the mapper could not place or uniquely identify; choose a more
+specific role or qualified mapped owner. Metadata coverage is deliberately
+explicit: an unmapped component can still be a valid public component.
+
+Mappings belong to exact import/symbol pairs in the existing authored catalogue,
+then flow into its generated public index. They describe role tags, owner kind,
+region/cell/overlay placement, surface ownership, insertion props and any authored
+literal recommendations. Generation checks them against the actual public API.
+They do not introduce another theme, token system or component registry.
+
+Table-cell identities stay in column renderers, and overlays stay at their
+composing app/feature boundary. Similar collection owners remain alternatives;
+a request that cannot distinguish them stays unresolved. App data, callbacks,
+permissions, forms and asynchronous lifecycle still follow the selected owner's
+contract and matching recipe.
+
+Use [composition ownership](composition.md), [screen archetypes](screen-archetypes.md)
+and [form workflows](rhf-workflows.md) for the selected task. After implementing,
+run the existing source checker and app checks, inspect narrow/wide light/dark
+appearance, and execute the relevant interactions from [review](review.md).

package/docs/consumer-skill/references/composition.md

@@ -1,6 +1,6 @@
 # Composition
 
-The [design contract](design-contract.md) separates application layout freedom
+The [design contract](design-contract.md#semantic-roles) defines shared spacing and typography roles and separates application layout freedom
 from library-owned anatomy. Use supported props and slots inside shared surfaces;
 keep placement, width, wrapping and overflow with the surrounding composition.
 
@@ -82,7 +82,8 @@ export and destructive command should not all inherit the same visual emphasis.
 }}>{/* route content */}</Page>
 ```
 
-A record split into sections adds `header.tabs`. The tabs sit under the header's
+When a record has separately selected or routed sections, use `header.tabs`.
+A continuous detail document can keep its sections in the body. The tabs sit under the header's
 copy and commands, a `badge` shows a count, tabs that do not fit move into a More
 menu, and `onValueChange` switches the section or routes. Labels name the
 command; an icon on every command repeats it, so keep `+` on an add command and
@@ -222,21 +223,39 @@ for richer content. Facts and rows follow the same rule: one glyph repeated on
 every MetadataList item or Item row is decoration, so leave `icon`/media empty.
 
 Card `gap` owns spacing between regions; `contentGap` owns direct body-child
-spacing; `textGap` owns title/supporting-copy rhythm. Region spacing defaults to
-`xl` (`md` for `padding="none"`). Use a semantic region gap for compact cards
-instead of resetting padding or adding local margins.
-
-Ordinary independent cards omit `padding` and retain `md` (the full surface
-inset, 20px at default roots). `sm` is half that inset (10px), for a deliberately
-compact subject; it is not the default for forms, settings, metrics or resource
-pages. Component size and
-density do not choose Card padding. `lg` uses 1.8 times the inset (36px), while
-`none` removes it. All sizes follow the surface roots and space-scale.
-Card dividers are on by default: a framed card rules its header and footer apart,
-while flat, card-free structure and a `headerPlacement="frame"` header draw no
-rule unless asked. UIProvider's `card.defaultHeaderDivider` and
-`card.defaultFooterDivider` (both `true`) turn the framed rules off app-wide;
-explicit per-card booleans win. Header/footer-only cards render one shared divider.
+spacing; `textGap` owns title/supporting-copy rhythm. `contentGap` is unset by
+default, so raw body children retain their inline or caller-owned layout.
+Choose `contentGap="xl"` for related siblings and `contentGap="2xl"` for
+independent sections. Omit it around an existing Grid/Stack or a single feature
+that already owns its layout:
+
+```tsx
+<Card title="Billing" contentGap="xl">
+  <MetadataList columns={1} items={[
+    { label: 'Plan', value: 'Studio' },
+    { label: 'Billing cycle', value: 'Monthly' },
+  ]} />
+  <Text type="secondary" size="xs">Invoices go to billing@northstar.example.</Text>
+</Card>
+```
+
+This lets Card own body rhythm without an extra caller wrapper. For independent sections,
+change the Card to `contentGap="2xl"` and let each section own its heading/copy
+group. The default regional gap
+follows the surface inset tier: 12px with `padding="sm"`, 24px with omitted/`md`
+or `none`, and 32px with `lg`, before spacing scale. An explicit semantic `gap`
+overrides it without changing the insets. See [semantic roles](design-contract.md#semantic-roles).
+
+Ordinary independent cards omit `padding` and retain `md` (24px at default
+roots). Card supports `sm` (12px), `md` (24px), `lg` (32px) and `none` (no inset).
+The general surface scale also has a 16px tier; Card does not expose it as a padding prop.
+Component size and density do not choose Card padding. All tiers follow the
+surface roots and space-scale.
+Card defaults to `surface="card"`, with no header rule and a footer rule.
+Flat, card-free structure and a `headerPlacement="frame"` header draw no rule
+unless asked. UIProvider's `card.defaultHeaderDivider` (false) and
+`card.defaultFooterDivider` (true) configure these rules app-wide; explicit
+per-card booleans win. Header/footer-only cards render one shared divider.
 Inside the body, separate a card's sections with `contentGap` or a Stack gap
 clearly larger than the row gap (`2xl` between sections), not rules.
 Overlays rule their regions the same way: `ActionDialog`, `ActionDrawer` and `ConfirmDialog`
@@ -448,10 +467,15 @@ TwoColumnLayout defaults to its existing viewport breakpoint; choose
 adaptTo="container" inside Container/PageViewport to adapt at 48rem of usable
 parent width while preserving main-before-aside DOM/focus order.
 
-See the installed [workspace recipe](../examples/app-layout.tsx).
+The installed [app-shell recipe](../examples/app-layout.tsx) exports a copyable
+`WorkspaceLayout` that hosts route children directly. Put `AccountDetailPage` or
+another route Page inside it. `WorkspaceExamplePage` separately demonstrates a
+Workspace title, Create callback and narrow measure; replace that example when
+composing a real route. This recipe name is local to the copied file; the public
+`WorkspaceLayout` from `layout/workspace` is the record shell described below.
 
 PageViewport owns scrolling and adds no padding. Page defaults to `gutter="lg"`
-and `padding="lg"` (36px at shipped roots), so it owns inline/block space once.
+and `padding="lg"` (32px at shipped roots), so it owns inline/block space once.
 `narrow` selects centered `md` width; explicit `maxWidth` wins. Header copy
 defaults to dense; `textGap="normal"` is an explicit alternative. Do not assume
 an app shell supplies gutters because it supplies a viewport. Set `gutter="none"`

package/docs/consumer-skill/references/design-contract.md

@@ -52,6 +52,38 @@ requests one shared boundary. Setting both does not add a second line or a blank
 body strip. Real body/alert regions retain their distinct requested boundaries;
 an explicitly expandable card retains its collapse region.
 
+## Semantic roles
+
+Choose spacing by the relationship between content, before choosing a gap tier.
+These base measurements use the shipped roots; spacing scales once through
+`--space-scale`.
+
+| Relationship | Default | Owner |
+| --- | --- | --- |
+| Structural title/supporting copy | `normal`, 4px | Headed owner or custom copy Stack |
+| Dense supporting copy | `dense`, 2px | Row/menu copy group |
+| Ordinary commands | `md`, 8px | Page, record and workspace command groups |
+| Compact row affordances | `xs`, 4px | Row action group |
+| Related fields/content | `xl`, 16px | Form or related-content group |
+| Independent subject regions | `2xl`, 24px | Page body, TwoColumnLayout, resource, workspace and settings subjects |
+| Page header/body separation | `3xl`, 32px | Page composition |
+| Surface header/body/footer | Surface-derived regional gap | Card or overlay anatomy, independent of peer gaps |
+
+Generic Stack and Grid keep their existing defaults; choose their semantic gap
+for the relationship they host. A Card's regional gap derives from its surface
+inset tier and remains independent of the gap between separate Cards. For Card,
+omitted `padding` means `md` (24px); `sm` is 12px, `lg` is 32px and `none` removes
+insets while retaining the 24px default regional gap. Explicit `gap` overrides
+that regional recipe. The general surface vocabulary also has a 16px tier; it is
+not an additional Card padding prop.
+
+Typography follows route, subject and subsection roles at 20/16/14px before
+customization. Body and supporting copy normally use 14/12px. Semantic tags stay
+independent of visual size; supported `size`, typography/provider defaults and
+CSS text-root overrides remain available. Density changes row/control geometry,
+not the primary text hierarchy. Preserve a deliberate website/hero emphasis or
+custom render content rather than forcing every heading onto the admin scale.
+
 ## Keep these choices independent
 
 | Choice | Purpose | Does not choose |

package/docs/consumer-skill/references/discovery.md

@@ -14,9 +14,9 @@ node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.
 
 For a copied skill, replace the script path with that copy's `scripts/find-components.mjs`. Copy the complete skill folder: the script resolves its adjacent `references/public-api.json` relative to itself, regardless of the working directory. It needs Node compatible with the package's engine requirement, not an npm/global CLI or extra dependency.
 
-Queries accept multiple words, quoted or separate. Every term must match metadata
-as a word; `stat` does not match `state` or `status`. An unknown term produces
-empty results. Exact imports and case-exact exported names such as `Table` or
+Queries accept multiple words, quoted or separate. Strict `results` require every
+term to match metadata as a word; `stat` does not match `state` or `status`. An
+unknown term leaves strict results empty. Exact imports and case-exact exported names such as `Table` or
 `Empty` select their precise contract. Ordinary task nouns `table` and `empty`
 retain DataTable/DataView and EmptyState alongside the base anatomy. Exported
 types and helper symbols remain available by their exact API name; documented
@@ -26,9 +26,18 @@ component symbols and curated aliases drive task recommendations.
 Foundations but filters under `--layer base`. `--limit` accepts 1–100 and defaults
 to 5. Invalid flags/options or incompatible indexes exit nonzero on stderr.
 
-If a query returns no results, shorten it to the main responsibility or an exact
-symbol, then remove the layer filter. No result does not prove the package lacks
-that responsibility. Read the selected result's choose/avoid guidance and
+When a natural-language query has no strict matches, the finder may add bounded
+`related.results` separately. For example, `member workspace` can suggest the
+workspace owner while explicitly reporting `workspace` as matched and `member`
+as unmatched. These are incomplete context suggestions, not proof that the owner
+implements the whole request. Unmatched terms describe missing metadata evidence;
+they do not establish an unsupported capability. Read the suggested owner's
+choose/avoid guidance and inspect its contract before choosing. Unknown-only
+queries, API-like CamelCase names and explicit import paths do not recover.
+
+If there are no useful related owners, shorten the query to the main
+responsibility or an exact symbol, then remove the layer filter. No result does
+not prove the package lacks that responsibility. Read the selected result's choose/avoid guidance and
 alternatives, then follow `nextReads`; do not load every reference. For routine compact searchable selection, search
 `PopoverMenu` or `compact searchable selection`; surface adjectives describe
 variants, not permission to rebuild the owner's padding.
@@ -44,7 +53,7 @@ description matches. Start with responsibilities such as `record directory`,
 `comparison table`, `identity cell`, `fact list`, `page header`, `query toolbar`
 or `theme boundary`. Read choose/avoid and app-owned responsibilities before
 deciding; a directory result does not require DataView when its workflow differs.
-Unknown terms still return no result; no fuzzy API or guessed prop is invented.
+Unknown terms never become strict matches; no fuzzy API or guessed prop is invented.
 
 Task language also includes `dashboard KPIs`, `dashboard metrics`, `revenue
 overview`, `statistic cards`, `usage statistics` and `single resource page`.
@@ -87,6 +96,14 @@ new code with the replacement. The public index carries the same map per family.
 Exact guide aliases precede generic overlap, and unrelated family pages
 do not fill the result merely to reach three entries.
 
+The optional `related` object leaves strict `total` and `results` unchanged. It
+reports an explanation, its own `total` and bounded `results` with `match:
+"partial"`, `matchedTerms` and `unmatchedTerms`. Term coverage ranks first, then
+the existing owner score and import ordering. These suggestions follow the same
+layer filter and limit, and use the same published owners and focused reads;
+package/path vocabulary alone cannot suggest an owner. The static finder shows
+their incomplete coverage separately from full matches.
+
 `nextReads.declaration` is relative to the installed package root.
 `nextReads.references` and `nextReads.examples[].file` are relative to this
 skill folder, so they also work with a complete copied skill. Examples report
@@ -105,6 +122,66 @@ owners and focused reads; declarations establish actual props and behavior.
 
 Read each declaration relative to the installed package root, for example `node_modules/themelia-react-ui/dist/components/base/cards/index.d.ts`, following its relative exports as needed. Copying this skill copies metadata, not the declaration tree: use declarations from the same installed package version. Never combine metadata from one version with another version's declarations.
 
+## Map cooperating components
+
+The [composition mapper](composition-mapping.md) resolves explicit role tags into
+qualified owners and an advisory region tree. Use it after decomposing a screen
+into subjects, or inspect the available roles before choosing components:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --roles
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --pattern record-detail --main invoice-lines --aside facts
+```
+
+Read its unresolved requirements, surface decisions and peers; the finder and
+API inspector remain useful for responsibilities outside mapped coverage.
+
+## Inspect a selected component
+
+The finder chooses owners. The dependency-free inspector retrieves a bounded,
+versioned API contract for an exact exported component without loading the full
+catalogue or manually chasing its declaration barrel:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs DataTable --import themelia-react-ui/features/table
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs DataTable --import themelia-react-ui/features/table --prop onRowSelectionChange
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs ThemeScope --import themelia-react-ui/ui-provider
+```
+
+Use `--import` to select an exact public contract when a symbol has several
+owners. `--prop` requests one exact property; `--limit` bounds the initial list
+of props. Read reported omissions before assuming a property is absent. Unknown
+exports/props and ambiguous unqualified contracts fail explicitly. Aliases can
+share implementation while distinct exports such as the two ThemeScope owners
+have different APIs.
+
+The generated `component-contracts.json` comes from the existing TypeScript/prop
+documentation pipeline. Types, call signatures, generic parameters, overloads
+and mode-dependent requirements remain visible. A prop required in one union
+branch is not universally required. Defaults are only those documented by that
+pipeline; an unknown default is not inferred. Native attributes and named helper
+types still lead to installed declarations where the bounded contract needs
+more detail. Inspect callback types and controlled/default state before adapting
+a recipe; sharing a visual shape does not mean controls share a value contract.
+
+The copied inspector reads its adjacent shared metadata, like the finder. Verify
+the complete copied bundle and installed identity first. It does not install
+dependencies, alter an app, or add an editor/type-checking runtime.
+
+## Inspect theme vocabulary
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs surface --limit 8
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs radius --limit 5
+```
+
+Token lookup reads the existing generated token index. It distinguishes public
+structural roots and advanced settings from derived utility vocabulary. A
+utility match does not become an override root. Unreported semantic theme values
+must be read from the installed stylesheet and [theme guide](theming.md); the
+tool does not invent a palette. The tokenization skill owns changing these
+shared roles and verifying the effects across controls/surfaces and portals.
+
 `ThemeScope` has distinct contracts. Root and `themelia-react-ui/ui-provider` export the basic CSS-inheritance boundary with native div/style props and portal hosting. `themelia-react-ui/features/theme-tweaker` exports the advanced theme-definition scope. Inspect the result's responsibility and that exact family's declaration before selecting props.
 
 The index retains schemaVersion/discoveryVersion 1; optional family `recipes` and `references`

package/docs/consumer-skill/references/installation.md

@@ -1,5 +1,26 @@
 # Installed package and skill setup
 
+## Choose the CSS path
+
+**Standalone compiled CSS:** import `themelia-react-ui/style.css` once in the app entry. It includes component styles and the documented public utility vocabulary; components work without a host reset, Tailwind processing or private-source scanning. It deliberately omits global preflight. This path does not generate arbitrary utility classes written in app source.
+
+**Tailwind v4 application utilities:** when the app authors Tailwind classes, process this application stylesheet through its Tailwind v4 build integration:
+
+```css
+@import "tailwindcss";
+@import "themelia-react-ui/style.css";
+@import "themelia-react-ui/theme.css";
+```
+
+Tailwind supplies app-generated utilities and its layered preflight; theme.css makes the semantic and structural vocabulary available to that compilation. No package-private source scan is required. The default layer order is `theme, base, components, utilities`. Keep app resets inside `@layer base`; unlayered universal/tag resets outrank layered package styles regardless of import order. Do not blanket-reset `[data-slot]`, which also belongs to third-party and app markup. Put intentional scoped app overrides after these imports. See [integration](integration.md) for an optional app-owned reset and provider setup.
+
+
+Themelia 2.0.4 requires the official `@base-ui/react ^1.9.0` npm peer alongside
+React, React DOM and Lucide. An app already using `^1.9.0` can retain that range.
+Remove any older private Base UI archive pin or override before refreshing the
+lockfile; dismissal translations and nested popup focus belong to Themelia's
+wrappers and work with the official package.
+
 Run from the consuming app or one of its subdirectories. Resolve a public
 entrypoint rather than guessing a hoisted node_modules path or importing
 `themelia-react-ui/package.json`, which is not an exported entrypoint. The following
@@ -25,27 +46,15 @@ while (true) {
 }
 const installedSkill = path.join(root, 'docs/consumer-skill');
 const selectedSkill = process.env.THEMELIA_SKILL_DIR ?? installedSkill;
-for (const file of ['public-api.json', 'tokens.json']) {
+for (const file of ['public-api.json', 'tokens.json', 'component-contracts.json']) {
   const installed = readJson(path.join(installedSkill, 'references', file));
   assert.equal(installed.package, manifest.name, 'Installed guidance package mismatch');
   assert.equal(installed.version, manifest.version, 'Installed guidance version mismatch');
-  const selected = readJson(path.join(selectedSkill, 'references', file));
-  assert.deepEqual(selected, installed, 'Copied skill is stale; refresh the complete folder');
 }
 if (fs.realpathSync(selectedSkill) !== fs.realpathSync(installedSkill)) {
-  function compareAssets(directory) {
-    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-      if (entry.name === '.DS_Store') continue;
-      const installed = path.join(directory, entry.name);
-      const selected = path.join(selectedSkill, path.relative(installedSkill, installed));
-      const info = fs.lstatSync(installed);
-      assert(!info.isSymbolicLink(), 'Installed guidance must contain real assets');
-      assert(fs.existsSync(selected) && !fs.lstatSync(selected).isSymbolicLink(), 'Copied skill is stale; missing or linked asset');
-      if (info.isDirectory()) compareAssets(installed);
-      else assert(fs.readFileSync(installed).equals(fs.readFileSync(selected)), 'Copied skill is stale; refresh the complete folder');
-    }
-  }
-  compareAssets(installedSkill);
+  const { pathToFileURL } = await import('node:url');
+  const { checkCopiedConsumerBundle } = await import(pathToFileURL(path.join(installedSkill, 'scripts/setup-skills.mjs')).href);
+  checkCopiedConsumerBundle({ packageRoot: root, destination: path.dirname(selectedSkill) });
 }
 // The app's project instructions block records the version it was pasted from.
 const instructions = ['AGENTS.md', 'CLAUDE.md'].find(file => fs.existsSync(file));
@@ -55,7 +64,7 @@ console.log(JSON.stringify({ package: manifest.name, version: manifest.version,
 JS
 ```
 
-Use the reported root for the bundled finder, stylesheet paths and published
+Use the reported root for the bundled finder/inspectors, stylesheet paths and published
 declarations. Install required peers from that manifest and optional peers for
 the exact imported families from `references/public-api.json`. A copied skill's
 finder reports its own metadata version; it does not inspect the app installation.
@@ -65,7 +74,7 @@ running the recipe. The comparison checks metadata contents as well as version,
 so stale copies with the same development version are caught. Every installed
 guidance/script/example asset is also compared byte-for-byte; extra app-owned
 files or publisher markers in the copy are not checked. Keep local product policy
-outside the package guidance. Recopy the complete folder after upgrades, and
+outside the package guidance. Recopy the complete bundle after upgrades, and
 read declarations from the installed package.
 
 `agentsBlock` reports whether the app's `AGENTS.md` (or `CLAUDE.md`) carries the
@@ -96,20 +105,21 @@ need the codemod; `button: { defaultTone: 'primary', defaultButtonStyle: 'solid'
 restores the previous default app-wide. Afterwards, demote extra primaries so
 each page or surface keeps one.
 
-## Manual skill copying
-
-1. Choose an agent skill destination in the user's configured skills directory,
-   named `themelia-react-ui-consumer`. For Codex the usual destination is
-   `~/.codex/skills/themelia-react-ui-consumer`; honor a configured alternative.
-2. Copy the **entire** installed `docs/consumer-skill` directory, including
-   references, scripts and examples. Do not copy only SKILL.md or merge files from
-   different releases. Preserve an existing user-customized copy before replacing it.
-3. Run the identity recipe with `THEMELIA_SKILL_DIR` pointing to that copy. Invoke
-   `$themelia-react-ui-consumer` or let the agent select it by task context.
-
-Copying into an agent's global skill directory is a separate user-requested
-action; reading these instructions does not perform or authorize it. The npm
-package does not install a skill automatically. Run the consuming app's own
-type/lint/test/build scripts after integration; repository check scripts are not
-installed consumer commands. See [integration](integration.md) for workflow and
-opened-surface verification.
+## Copy the complete skill bundle
+
+The package ships three focused capabilities and one compatibility/shared root. One copy of API/token/contract metadata, scripts and examples is shared by all three. Do not copy only an individual SKILL.md or duplicate the generated indexes into each skill.
+
+When the user requests installation, run the bundled copy helper with their configured agent skills directory. For Codex the usual destination is `~/.codex/skills`; honor a configured alternative:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --destination "$HOME/.codex/skills"
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --destination "$HOME/.codex/skills"
+```
+
+It copies `themelia-components`, `themelia-tokenization`, `themelia-composition`, and `themelia-react-ui-consumer` as real sibling directories. Rich templates are copied once under the shared directory. Markdown links are rebased for this installed layout; no symlinks or repository paths are required. Existing canonical/shared destinations are rejected before writing: preserve or move the previous complete bundle before an upgrade, then copy the release together. `--check` compares every expected asset after rebasing, so stale content with an unchanged development version is caught.
+
+The package retains `docs/consumer-skills/themelia-foundation/SKILL.md` and `themelia-forms/SKILL.md` as compatibility routers. They are not added by fresh copying. Existing legacy or unrelated skills are left untouched; review older agent routing separately when upgrading. Keep app policy outside the copied package bundle.
+
+For the identity recipe above, set `THEMELIA_SKILL_DIR` to the copied shared `themelia-react-ui-consumer` directory. In project instructions, use the generated [AGENTS.md block](agents-md.md) pointing at package skills, or point the three skill paths to their copied siblings. Invoke `$themelia-components` for setup, discovery and typed APIs/forms; `$themelia-tokenization` for themes and shared visual roles; and `$themelia-composition` for screen hierarchy, workflows and visual repair. The compatibility `$themelia-react-ui-consumer` entrypoint remains available.
+
+Copying into an agent's global skill directory requires a user request. The npm package does not perform installation automatically. Run the consuming app's own type/lint/test/build scripts after integration; repository maintainer commands are not installed consumer commands.

package/docs/consumer-skill/references/integration.md

@@ -1,6 +1,6 @@
 # Integration
 
-Install required peers from the installed package.json; public-api.json records required/optional peers. Install optional peers for the imported families, including base families such as charts and QR code. Whole-family declaration requirements can exceed a tree-shaken runtime graph; follow the exact family's index and declarations. Import style.css once before overrides; it omits preflight, so the app supplies its reset. Basic controls must not pull in unrelated map/editor/chart dependencies.
+Install required peers from the installed package.json; public-api.json records required/optional peers. Install optional peers for the imported families, including base families such as charts and QR code. Whole-family declaration requirements can exceed a tree-shaken runtime graph; follow the exact family's index and declarations. Import style.css once before overrides; it omits global preflight and components remain usable without a host reset. Use the [installation CSS paths](installation.md#choose-the-css-path) when generating app utilities. Basic controls must not pull in unrelated map/editor/chart dependencies.
 
 Put global resets in the lower-priority `base` layer, or use your framework's layered preflight. The package uses the `theme, base, components, utilities` layer order. Unlayered rules outrank layered component styles regardless of import order; a global `button { font: inherit }` can replace the library's control size and weight. For an app-owned reset:
 
@@ -18,7 +18,7 @@ Load intentional, scoped app overrides after the package stylesheet. Keep broad
 
 UIProvider supplies stable mount-time defaults: explicit prop, provider default, fallback. Per-mount requests/data/callbacks stay on components. ThemeScope from themelia-react-ui/ui-provider places descendant portals inside its CSS boundary. A styled div does not relocate body portals; explicit Base UI portal containers take precedence.
 
-Framed card regions are ruled apart by default. To separate them by spacing
+Cards omit the header rule and keep the footer rule by default. To separate them by spacing
 alone, configure the single application provider with
 `card: { defaultHeaderDivider: false, defaultFooterDivider: false }`.
 Explicit Card booleans override these defaults. Ordinary card
@@ -113,3 +113,7 @@ both container content edges without global preflight; Container and DataTable
 own border-box sizing. Stabilize lifecycle inputs as explained in
 [workflows](workflows.md#scoped-directory). These are example/runtime proofs,
 not evidence of an independent agent choosing the same composition.
+
+## Form transport and router adapters
+
+Use [RHF workflows](rhf-workflows.md#transport-lifecycle) for frontend state with Inertia callback visits or TanStack async mutations. Await the complete transport before resetting dirty state or closing an overlay. The framework stays in the app. `renderLink` on AppSidebar/Page headers adapts the app router: forward href, children, className, accessible/native attributes and onClick; preserve modifier/new-tab behavior and invoke the supplied click handler so mobile navigation can close. Use the [typed shell recipe](../examples/app-layout.tsx) for the exact public renderLink type rather than inventing a router prop. React Router Link, Inertia Link and TanStack Link each need an app adapter matching their own installed version.