themelia-react-ui 1.0.0 → 1.0.1

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

@@ -22,6 +22,19 @@ before selecting the owner. For routine compact searchable selection, search
 `PopoverMenu` or `compact searchable selection`; surface adjectives describe
 variants, not permission to rebuild the owner's padding.
 
+When the same symbol is re-exported by an aggregate family, its documented
+component owner ranks first. For example, `UsageCard` selects
+`themelia-react-ui/blocks/analytics/usage-card` with no optional chart peer;
+requesting the exact `themelia-react-ui/blocks/analytics` import still selects
+that broader family. Read the reported peers and declaration for your selection.
+
+Exact curated intent aliases rank below exact imports/symbols and above generic
+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.
+
 Output is deterministic JSON: package/version, query/options, total matching families and a bounded `results` list. Each result includes exact `import`, packaged `declaration`, technical `layer`, responsibility, required `optionalPeers`, match kind, exact matched symbols and up to three relevant guidance entries. Family `sections` and guidance `section` reflect responsibility-based documentation placement. Guidance carries jobs, tags, aliases, selection/avoidance, application ownership, canonical browse group/domain plus catalogue category/collection, search-section labels/symbols and alternatives resolved to exact published imports. Read the [full index](public-api.json) for all symbols/guidance. A result suggests an owner; declarations establish its 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.
@@ -31,3 +44,7 @@ Read each declaration relative to the installed package root, for example `node_
 The index retains `schemaVersion: 1` and adds `discoveryVersion: 1`. Package name/version and peer ranges come from the published manifest; symbols and declaration paths come from live public exports; jobs and guidance come from the live consumer catalogue. Utility/root responsibilities have explicit owners when no catalogue family represents them. Optional peer requirements follow transitive local source imports, including type-only and resolved `@types` peers; the manifest supplies their compatible ranges. This describes whole-family declaration/runtime requirements, not the smaller graph a bundler may obtain after tree shaking.
 
 Routing, records, translation, permissions and backend effects stay in the application. Discovery grants no publication or global installation authority.
+
+The index's `stylesheets` list derives from published CSS exports, including
+optional map styling. The source checker uses it instead of assuming every
+Themelia import is a component family.

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

@@ -32,6 +32,21 @@ for (const file of ['public-api.json', 'tokens.json']) {
   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);
+}
 console.log(JSON.stringify({ package: manifest.name, version: manifest.version, root, skill: selectedSkill }, null, 2));
 JS
 ```
@@ -43,9 +58,11 @@ finder reports its own metadata version; it does not inspect the app installatio
 
 To check a copied skill, set `THEMELIA_SKILL_DIR` to its complete directory when
 running the recipe. The comparison checks metadata contents as well as version,
-so stale copies with the same development version are caught. A successful check
-does not compare every prose file: recopy the complete folder after package
-upgrades or guidance updates, and read declarations from the installed package.
+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
+read declarations from the installed package.
 
 ## Manual skill copying
 

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

@@ -54,4 +54,16 @@ Server code imports pure helpers from `themelia-react-ui/features/email-composer
 
 Maintainer enforcement uses @shadcn/lint through Oxlint plus AST/contract checks. These are not runtime dependencies or a published consumer audit CLI. Configure app lint using published utilities/imports; do not copy repository migration-debt allowances. There is no Sass/SASSC pipeline in this Tailwind package.
 
+For opt-in import/anatomy checks, the package now includes a read-only Node script
+using the app's TypeScript dev dependency; see [review and checks](review.md).
+It is not a global CLI or a complete visual auditor. Keep product policies and
+current adapter/page examples in an app-owned reference, separate from this skill.
+
 The maintainer installed-tarball harness proves the basic provider/control/overlay SSR and hydration fixture, pure email preparation without editor peers, controlled table and email-composer workflows, and optional client module initialization. It checks hydration diagnostics and real callbacks in light/dark at narrow/wide widths. Optional module initialization alone does not prove its complete workflow or server-rendering support; verify the features your app uses. `check:all` runs the serial package and curated browser gates; evidence collection is a separate `collect:browser` command. Both are repository maintainer commands, not installed consumer CLIs.
+
+The scoped directory fixture also runs the packaged recipe's query/clear,
+fixed-scope, loading/error/retry, empty and keyboard row-menu callbacks. It checks
+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.