@astryxdesign/core 0.7.2-canary.081ccea → 0.7.2-canary.085e145

package/README.md

@@ -6,10 +6,10 @@ Core UI components, theme system, and utilities for the Astryx design system. Fo
 >
 > ```bash
 > npm install -D @astryxdesign/cli   # or: pnpm add -D / yarn add -D / bun add -d
-> npx astryx init                    # resolves to the CLI you just installed
+> npx @astryxdesign/cli init         # the CLI you just installed
 > ```
 >
-> `init` writes the Astryx component index into your `AGENTS.md`/`CLAUDE.md` so your agent discovers components, templates, and design tokens instead of guessing. Need a single command without installing? Use the scoped package directly — `npx @astryxdesign/cli <cmd>` (or `pnpm dlx`/`bunx @astryxdesign/cli`). Bare `npx astryx` only works once `@astryxdesign/cli` is a dependency; before that npm resolves it to an unrelated package. See [XDS CLI](#xds-cli).
+> `init` writes the Astryx component index into your `AGENTS.md`/`CLAUDE.md` so your agent discovers components, templates, and design tokens instead of guessing. Need a single command without installing? The same scoped command works: `npx @astryxdesign/cli <cmd>`. Always use the scoped name: the unscoped `astryx` resolves to an unrelated npm package until `@astryxdesign/cli` is a dependency. See [XDS CLI](#xds-cli).
 
 ## Component Docs
 
@@ -21,7 +21,7 @@ npx @astryxdesign/cli component Button        # full docs for a component
 npx @astryxdesign/cli component --list        # list all components
 ```
 
-> Use the scoped `@astryxdesign/cli` to run without installing; bare `npx astryx` only resolves once the CLI is a dependency.
+> Use the scoped `@astryxdesign/cli`: it runs with or without installing, while the unscoped `astryx` resolves to an unrelated npm package until the CLI is a dependency.
 
 ## Page Layouts
 
@@ -57,7 +57,7 @@ astryx discover                     # discover external Astryx packages
 astryx gap-report                   # report a missing capability
 ```
 
-> Prefix these with your runner: `npx astryx …` / `pnpm exec astryx …` once the CLI is installed, or `npx @astryxdesign/cli …` to run without installing.
+> Run these as `npx @astryxdesign/cli …`, or `pnpm exec astryx …` (or your package manager's equivalent) once the CLI is installed.
 
 ## Related Packages
 

package/dist/DropdownMenu/DropdownMenuCheckboxItem.d.ts

@@ -35,7 +35,7 @@ export interface DropdownMenuCheckboxItemProps extends Omit<BaseProps, 'onChange
     description?: ReactNode;
     /**
      * Icon to display before the label. Accepts a semantic icon name (see
-     * `npx @astryxdesign/cli docs icons`) or a rendered node.
+     * `astryx docs icons`) or a rendered node.
      */
     icon?: ReactNode | IconType;
     /**

package/dist/DropdownMenu/DropdownMenuRadioItem.d.ts

@@ -35,7 +35,7 @@ export interface DropdownMenuRadioItemProps extends Omit<BaseProps, 'role' | 'ar
     description?: ReactNode;
     /**
      * Icon to display before the label. Accepts a semantic icon name (see
-     * `npx @astryxdesign/cli docs icons`) or a rendered node.
+     * `astryx docs icons`) or a rendered node.
      */
     icon?: ReactNode | IconType;
     /**

package/dist/FormLayout/FormLayout.d.ts

@@ -28,10 +28,11 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
      * Direction of field arrangement.
      *
      * - `'vertical'` — Fields stack top-to-bottom (default). Most common.
-     * - `'horizontal'` — Fields arrange left-to-right in equal-width columns
-     *   using CSS Grid. Each child occupies one equal column.
-     * - `'horizontal-labels'` — CSS Grid with labels to the left of inputs.
-     *   Collapses to vertical when the container is narrow (≤480px).
+     * - `'horizontal'` — Fields occupy one `1fr` CSS Grid track per child in
+     *   logical inline order.
+     * - `'horizontal-labels'` — CSS Grid with labels beside their inputs on the
+     *   inline-start side. Collapses to vertical when the viewport is narrow
+     *   (≤480px).
      *
      * @default 'vertical'
      */

package/dist/FormLayout/FormLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FormLayout.d.ts","sourceRoot":"","sources":["../../src/FormLayout/FormLayout.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AA2C7B,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAEhC;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAAkB,CAAC,EAAE,eAAe,CAAC;CACtC;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,SAAsB,EACtB,kBAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,+BA0BjB;yBAnCe,UAAU"}
+{"version":3,"file":"FormLayout.d.ts","sourceRoot":"","sources":["../../src/FormLayout/FormLayout.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAU,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AA2C7B,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAEhC;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAAkB,CAAC,EAAE,eAAe,CAAC;CACtC;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,SAAsB,EACtB,kBAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,+BA0BjB;yBAnCe,UAAU"}

package/dist/FormLayout/FormLayoutContext.d.ts

@@ -2,9 +2,9 @@
  * Direction of form field arrangement.
  *
  * - `'vertical'` — Fields stack top-to-bottom (default). Most common.
- * - `'horizontal'` — Fields arrange left-to-right, wrapping when needed.
- * - `'horizontal-labels'` — Fields stack vertically but labels sit to the left
- *   of their inputs (settings/admin panel pattern).
+ * - `'horizontal'` — Fields occupy one `1fr` grid track per child in logical inline order.
+ * - `'horizontal-labels'` — Fields stack vertically while labels sit beside
+ *   their inputs on the inline-start side (settings/admin panel pattern).
  */
 export type FormLayoutDirection = 'vertical' | 'horizontal' | 'horizontal-labels';
 /**

package/dist/FormLayout/FormLayoutContext.js

@@ -19,9 +19,9 @@ import { createLayerScopedContext as createContext } from "../Layer/layerScopedC
  * Direction of form field arrangement.
  *
  * - `'vertical'` — Fields stack top-to-bottom (default). Most common.
- * - `'horizontal'` — Fields arrange left-to-right, wrapping when needed.
- * - `'horizontal-labels'` — Fields stack vertically but labels sit to the left
- *   of their inputs (settings/admin panel pattern).
+ * - `'horizontal'` — Fields occupy one `1fr` grid track per child in logical inline order.
+ * - `'horizontal-labels'` — Fields stack vertically while labels sit beside
+ *   their inputs on the inline-start side (settings/admin panel pattern).
  */
 
 /**

package/dist/Grid/Grid.js

@@ -368,6 +368,7 @@ export function Grid({
   const columnsVariant = typeof columns === 'number' ? columns : typeof columns === 'object' ? undefined : undefined;
   return /*#__PURE__*/_jsx("div", {
     ref: ref,
+    ...props,
     ...mergeProps(themeProps('grid', {
       columns: columnsVariant,
       gap,
@@ -377,7 +378,6 @@ export function Grid({
       ...style,
       ...inlineStyle
     }),
-    ...props,
     children: children
   });
 }

package/dist/PowerSearch/PowerSearch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PowerSearch.d.ts","sourceRoot":"","sources":["../../src/PowerSearch/PowerSearch.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"PowerSearch.d.ts","sourceRoot":"","sources":["../../src/PowerSearch/PowerSearch.tsx"],"names":[],"mappings":"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"}

package/dist/PowerSearch/PowerSearch.js

@@ -661,6 +661,11 @@ export function PowerSearch({
       size: size,
       icon: tokenIcon,
       endContent: valueContent,
+      onMouseDown: handleClick ? e => {
+        // Keep a token press from entering Tokenizer's input-focus
+        // redirect. Click still edits/removes; Tab entry is unchanged.
+        e.preventDefault();
+      } : undefined,
       onClick: handleClick ? e => {
         e.stopPropagation();
         handleClick();

package/dist/Token/Token.js

@@ -89,7 +89,7 @@ const styles = {
     kMwMTN: "x1heor9g",
     k5JduY: "x1s928wv",
     kwXMNM: "x1j6awrg",
-    kv0HGH: "x1xsm0q9",
+    kv0HGH: "xramuyw",
     $$css: true
   }
 };

package/dist/astryx.css

@@ -2077,7 +2077,7 @@
   .x1bev2v5[data-astryx-press="on"]:not(#\#):not(#\#):not(#\#):not(#\#):not(#\#){background-image:none}
   .x524tya[data-astryx-press="fading"]:not(#\#):not(#\#):not(#\#):not(#\#):not(#\#){background-image:none}
   @starting-style{.x1sopeo2.x1sopeo2:not(#\#):not(#\#):not(#\#):not(#\#):not(#\#){grid-template-rows:0fr}}
-  .x1xsm0q9:not(#\#):not(#\#):not(#\#):not(#\#):not(#\#)::after{inset:-14px}
+  .xramuyw:not(#\#):not(#\#):not(#\#):not(#\#):not(#\#)::after{inset:-4px}
   .xarstr8:not(#\#):not(#\#):not(#\#):not(#\#):not(#\#)::after{inset:0}
   .xxx281p:not(#\#):not(#\#):not(#\#):not(#\#):not(#\#)::before{inset:0}
   .xht581f:not(#\#):not(#\#):not(#\#):not(#\#):not(#\#)::after{inset:var(--_input-clear-hit-inset)}

package/docs.mjs

@@ -13,8 +13,8 @@
  * ==========================================================================
  *  AI AGENT: do NOT guess component APIs or hand-write CSS. Run:
  *      npx @astryxdesign/cli init
- *  Use the SCOPED name `@astryxdesign/cli` — bare `npx astryx` resolves to an
- *  unrelated package until the CLI is a dependency. Then, per component:
+ *  Use the SCOPED name `@astryxdesign/cli` — the unscoped `astryx` resolves to
+ *  an unrelated npm package until the CLI is a dependency. Then, per component:
  *      npx @astryxdesign/cli component <Name>
  *      npx @astryxdesign/cli component --list
  * ==========================================================================
@@ -27,8 +27,8 @@ const BANNER = `
 
      npx @astryxdesign/cli init
 
- (Use the scoped name @astryxdesign/cli. Bare \`npx astryx\` resolves to an
- unrelated package until the CLI is installed as a dependency.)
+ (Use the scoped name @astryxdesign/cli. The unscoped name astryx resolves
+ to an unrelated npm package until the CLI is installed as a dependency.)
 
  init writes the full component guide, page templates, design rules & tokens
  into your AGENTS.md / CLAUDE.md. Then, for any component:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.2-canary.081ccea",
+  "version": "0.7.2-canary.085e145",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -792,8 +792,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.2-canary.081ccea",
-    "@astryxdesign/cli": "0.7.2-canary.081ccea",
+    "@astryxdesign/a11y-spec": "0.7.2-canary.085e145",
+    "@astryxdesign/cli": "0.7.2-canary.085e145",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/scripts/agent-doc-state.mjs

@@ -145,15 +145,37 @@ function findRepositoryRoot(start) {
 }
 
 /**
- * The one-line next-step both postinstall nudges print. Kept here so layer 1
- * (core) and layer 2 (cli) can never word it differently.
- *
- * Scoped package form (`@astryxdesign/cli`) — always resolves to us, even before
- * the CLI is installed. Bare `npx astryx` would fetch an unrelated look-alike
+ * The invocation the setup nudge falls back to when the CLI's picker
+ * (`getCliInvocation`) cannot be loaded. Scoped package form
+ * (`@astryxdesign/cli`) — always resolves to us, even before the CLI is
+ * installed. npx with the unscoped name would fetch an unrelated look-alike
  * package (see PR #4151).
  */
-export const SETUP_NUDGE =
-  '\nNext step: run `npx @astryxdesign/cli init` to finish setup and install the Astryx agent prompt.\n\n';
+export const SETUP_INVOCATION = 'npx @astryxdesign/cli';
+
+/**
+ * The one-line next-step every setup layer prints. Kept here so layer 1
+ * (core), layer 2 (cli postinstall) and layer 3 (each command) can never word
+ * it differently. Each layer passes the stem from the CLI's picker when it can
+ * load it.
+ *
+ * @param {string} [invocation] the CLI invocation stem, e.g. `pnpm exec astryx`
+ * @param {{before?: string | null}} [options] `before`: a command to run
+ *   first, such as the one that adds the CLI to a project that has none
+ * @returns {string}
+ */
+export function setupNudge(
+  invocation = SETUP_INVOCATION,
+  {before = null} = {},
+) {
+  const run = before
+    ? `\`${before}\`, then \`${invocation} init\``
+    : `\`${invocation} init\``;
+  return `\nNext step: run ${run} to finish setup and install the Astryx agent prompt.\n\n`;
+}
+
+/** The nudge with the fallback invocation. */
+export const SETUP_NUDGE = setupNudge();
 
 /**
  * Pure decision: should a postinstall print the setup nudge? Shared by BOTH

package/scripts/postinstall.mjs

@@ -1,7 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file @astryxdesign/core postinstall — nudge to run `npx @astryxdesign/cli init`.
+ * @file @astryxdesign/core postinstall — nudge to run `astryx init`, prefixed
+ * the way the project's installed CLI prints commands.
  *
  * Enforcement layer 1 of making `astryx init` foolproof: when the design system
  * is installed and the project hasn't run init yet, print a one-line next-step
@@ -19,6 +20,8 @@
  * during npx's fetch, and once set up.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {fileURLToPath, pathToFileURL} from 'node:url';
 
 const HERE = fileURLToPath(import.meta.url);
@@ -37,6 +40,39 @@ async function loadContract() {
   }
 }
 
+/**
+ * The stem the project's installed CLI would print, from its picker
+ * (`getCliInvocation`). Core cannot depend on the CLI, so this looks for an
+ * installed copy from the project upward and imports the picker by path; with
+ * no CLI there, or one too old to have the picker, it returns undefined and
+ * the contract's scoped fallback is printed. At install time no integration is
+ * loaded, so this is the package-manager guess.
+ * @param {string} root
+ * @returns {Promise<string | undefined>}
+ */
+export async function cliInvocation(root) {
+  try {
+    let dir = path.resolve(root);
+    for (;;) {
+      const picker = path.join(
+        dir,
+        'node_modules/@astryxdesign/cli/foundation/env/package-manager.mjs',
+      );
+      if (fs.existsSync(picker)) {
+        const {getCliInvocation} = await import(pathToFileURL(picker).href);
+        return typeof getCliInvocation === 'function'
+          ? getCliInvocation(root)
+          : undefined;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) return undefined;
+      dir = parent;
+    }
+  } catch {
+    return undefined;
+  }
+}
+
 async function main() {
   const contract = await loadContract();
   if (!contract) return;
@@ -48,7 +84,12 @@ async function main() {
       isSetUp: contract.isAstryxPromptInReach(root),
     })
   ) {
-    process.stdout.write(contract.SETUP_NUDGE);
+    const invocation = await cliInvocation(root);
+    process.stdout.write(
+      typeof contract.setupNudge === 'function'
+        ? contract.setupNudge(invocation)
+        : contract.SETUP_NUDGE,
+    );
   }
 }
 

package/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
       name: 'icon',
       type: 'IconType',
       description:
-        'Icon to display before the label. See `npx @astryxdesign/cli docs icons` for valid semantic names.',
+        'Icon to display before the label. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'value',

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -98,7 +98,7 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
   description?: ReactNode;
   /**
    * Icon to display before the label. Accepts a semantic icon name (see
-   * `npx @astryxdesign/cli docs icons`) or a rendered node.
+   * `astryx docs icons`) or a rendered node.
    */
   icon?: ReactNode | IconType;
   /**

package/src/DropdownMenu/DropdownMenuRadioItem.doc.mjs

@@ -43,7 +43,7 @@ export const docs = {
       name: 'icon',
       type: 'IconType',
       description:
-        'Icon to display before the label. See `npx @astryxdesign/cli docs icons` for valid semantic names.',
+        'Icon to display before the label. See `astryx docs icons` for valid semantic names.',
     },
     {
       name: 'isDisabled',

package/src/DropdownMenu/DropdownMenuRadioItem.tsx

@@ -93,7 +93,7 @@ export interface DropdownMenuRadioItemProps extends Omit<
   description?: ReactNode;
   /**
    * Icon to display before the label. Accepts a semantic icon name (see
-   * `npx @astryxdesign/cli docs icons`) or a rendered node.
+   * `astryx docs icons`) or a rendered node.
    */
   icon?: ReactNode | IconType;
   /**

package/src/FormLayout/FormLayout.doc.mjs

@@ -13,7 +13,7 @@ export const docs = {
       name: 'direction',
       type: "'vertical' | 'horizontal' | 'horizontal-labels'",
       description:
-        'Controls field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right with equal flex-grow, and horizontal-labels uses CSS Grid with labels to the left of inputs (collapses to vertical on narrow viewports <=480px).',
+        'Controls field arrangement. Vertical stacks top-to-bottom, horizontal uses one fractional grid track per field in logical inline order, and horizontal-labels uses CSS Grid with labels beside inputs on the inline-start side (collapsing to vertical when the viewport is <=480px).',
       default: "'vertical'",
     },
     {
@@ -51,6 +51,7 @@ export const docs = {
       { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
     ],
     anatomy: [
+      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
       {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
       {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
       {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
@@ -67,7 +68,7 @@ export const docsZh = {
       name: 'direction',
       type: "'vertical' | 'horizontal' | 'horizontal-labels'",
       description:
-        '控制字段排列方式。vertical 从上到下堆叠，horizontal 从左到右排列且等比弹性增长，horizontal-labels 使用 CSS Grid 将标签放在输入框左侧（在窄视口 <=480px 时折叠为垂直布局）。',
+        '控制字段排列方式。vertical 从上到下堆叠；horizontal 为每个字段使用一个 1fr 网格轨道，并按逻辑行内方向排列；horizontal-labels 使用 CSS Grid，将标签放在输入框的行内起始侧（当视口宽度 <=480px 时折叠为垂直布局）。',
       default: "'vertical'",
     },
     {
@@ -105,6 +106,7 @@ export const docsZh = {
       { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
     ],
     anatomy: [
+      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
       {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
       {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
       {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
@@ -127,13 +129,14 @@ export const docsDense = {
       { guidance: false, description: 'Nest horizontal-labels inside another FormLayout. It uses CSS Grid and needs to be the outermost container.' },
     ],
     anatomy: [
+      {name: 'Layout container', required: true, description: 'Owns field arrangement, spacing, direction, and form-level optionality.'},
       {name: 'Form title', required: false, description: 'Heading that describes the purpose of the form.'},
       {name: 'Fields', required: true, description: 'Input components with labels for collecting user data.'},
       {name: 'Footer', required: false, description: 'Contains confirmation buttons such as Submit or Cancel.'},
     ],
   },
   propDescriptions: {
-    direction: 'Field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right w/ equal flex-grow, horizontal-labels uses CSS Grid w/ labels left of inputs (collapses <=480px).',
+    direction: 'Field arrangement. Vertical stacks top-to-bottom; horizontal uses one fractional grid track per field in logical inline order; horizontal-labels places labels on the inline-start side and collapses when the viewport is <=480px.',
     defaultOptionality: 'State the form treats as default, so only the exception is marked. "optional" → only isRequired fields show an indicator; "required" → only isOptional fields do. Under "required" unmarked fields also expose aria-required (aria only, not native required). Unset = per-field behavior.',
     children: 'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',

package/src/FormLayout/FormLayout.spec.md

@@ -0,0 +1,192 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:FormLayout
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/FormLayout/FormLayout.test.tsx,
+    apps/storybook/stories/FormLayout.stories.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    packages/core/src/docPropLiterals.test.ts,
+    packages/core/src/docPropReferences.test.ts,
+  ]
+modules: []
+families: [family:input-fields]
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+  ]
+contributing: []
+system_specs: []
+---
+
+# FormLayout component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `FormLayout` arranges caller-owned fields through `vertical`, `horizontal`, and `horizontal-labels` directions, provides a form-level optionality default, exports its context and supporting types, and accepts root `BaseProps`.                                      |
+| Behavior                | Vertical stacks children; horizontal creates one fractional grid track per child in logical inline order; horizontal-labels pairs Field labels and controls, then collapses below a 481px viewport.                                                                     |
+| End-user impact         | People encounter predictable field spacing and order, and assistive technology receives required-state information even when the form-wide visual convention leaves the common case unmarked.                                                                           |
+| Builder impact          | Builders supply the fields and any semantic `<form>`, title, or footer; nested layouts replace the outer direction and optionality context for their descendants.                                                                                                       |
+| Compatibility/readiness | This draft records released behavior. It changes no public API, default, or runtime behavior.                                                                                                                                                                           |
+| Review checks           | Reject lost root props, physical inline ordering, changed collapse boundaries, caller-overridable direction reflection, lost nested-context shadowing, or a visible optionality convention that disagrees with ARIA. Narrow label/control grouping remains open in OQ1. |
+| Governing rules         | Established public FormLayout interface; `family:input-fields` outer-arrangement ownership; `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV2–INV6`.                                                                          |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+`FormLayout` owns the outer spatial relationship among caller-owned form fields. It does not create form submission, field state, labels, controls, or action regions.
+
+## Compatibility and migration
+
+- Released default preserved: yes; direction defaults to `vertical`, and optionality remains field-owned when `defaultOptionality` is unset.
+- Compatibility class: observational only; this draft changes no public prop, default, or behavior.
+- Controlled/uncontrolled behavior: not applicable; FormLayout owns no form value or submission state.
+- Migration decision: none.
+
+## Ownership boundary
+
+**Owns**
+
+- Outer field arrangement, spacing, direction, and the viewport collapse for horizontal labels.
+- Form-level optionality context and nested-layout shadowing.
+- The root DOM element, root prop composition, and the `form-layout` theme target.
+
+**Does not own / non-goals**
+
+- Form semantics, submission, validation, or action placement — owned by the product callsite and native `<form>`.
+- Field labels, controls, status, and internal geometry — owned by `component:Field`, each input, and `family:input-fields`.
+- The content or visual contract of caller-supplied titles and footers — owned by their rendered components or the callsite.
+
+## Public concepts
+
+| Concept             | Closed values or states                         | Meaning                                                                 | Availability by variant/orientation/state                    | Default              | Owner                  | Stability | Invalid-value behavior |
+| ------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------ | -------------------- | ---------------------- | --------- | ---------------------- |
+| direction           | `vertical`; `horizontal`; `horizontal-labels`   | Selects the outer arrangement and provides that value to descendants.   | All layouts.                                                 | `vertical`           | `component:FormLayout` | released  | Type-constrained       |
+| default optionality | unset; `optional`; `required`                   | Marks only exceptions while controls preserve resolved required state.  | All directions; the nearest nested layout shadows the outer. | unset / per-field    | `component:FormLayout` | released  | Type-constrained       |
+| root composition    | DOM/data/ARIA/events; ref; class/style/`xstyle` | Extends the root layout container without replacing owned reflection.   | All directions.                                              | no caller decoration | `component:FormLayout` | released  | Shared merge contract  |
+| layout context      | direction plus optionality                      | Lets Field and inputs adapt their layout and required-state projection. | Descendants in the same layer scope.                         | vertical / unset     | `component:FormLayout` | released  | Nearest provider wins  |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                         | Basis                                                               | Draft review state                                    |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------- |
+| FR1 | Vertical direction stacks children with the shared spacing token.                                                                                                                                                                                                                                                           | Established public interface; current source and stories            | settled observation                                   |
+| FR2 | Horizontal direction places every direct child in one `1fr` grid track and follows the document's logical inline order without a component-owned wrap rule.                                                                                                                                                                 | Established public interface; current source and stories            | settled observation                                   |
+| FR3 | Horizontal-labels direction lets Field labels and control groups participate in a two-column grid, with the label on the inline-start side; at a viewport width of 480px or below it becomes one vertical flex column. Whether the collapsed label/control gap distinguishes each pair strongly enough remains open in OQ1. | Established public interface; Field composition and browser fixture | wide behavior settled; narrow grouping human decision |
+| FR4 | A nested FormLayout replaces the outer direction and optionality context for its descendants.                                                                                                                                                                                                                               | Existing context and unit tests                                     | settled observation                                   |
+| FR5 | `defaultOptionality` suppresses only the visible marker that restates the form default; descendant controls still expose resolved `aria-required`, while native `required` remains tied to explicit field intent.                                                                                                           | Existing tests; `family:input-fields` ownership                     | settled observation                                   |
+| FR6 | Root ref, DOM/data/ARIA/event props, `xstyle`, class name, and inline style reach or compose on the root without replacing `data-direction` or the canonical target.                                                                                                                                                        | `architecture:public-component-api/INV5–INV8`                       | settled observation                                   |
+
+### Allowed variation
+
+- **AV1 — Caller content.** Any caller-owned field, heading, explanatory content, or action region may be a child; FormLayout does not inspect or rewrite it.
+- **AV2 — Nested arrangement.** Builders may nest vertical and horizontal layouts; each provider owns only its descendant scope.
+- **AV3 — Root styling.** Caller styling may change the container's presentation while preserving the public direction and child contracts.
+
+### Representative states
+
+| State                      | Required invariant                                                      | Allowed variation                                                  |
+| -------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| vertical                   | One block-axis stack with tokenized gaps.                               | Any caller-owned children.                                         |
+| horizontal                 | One `1fr` grid track per child in logical inline order.                 | Child count and content.                                           |
+| horizontal labels / wide   | Label/control pairs share consistent two-column tracks.                 | Label and control content.                                         |
+| horizontal labels / narrow | One vertical column at 480px or below with no component-owned overflow. | Label/control grouping remains OQ1; caller-owned content may wrap. |
+| optional by default        | Only explicitly required fields show the exception marker.              | Field and input type.                                              |
+| required by default        | Only explicitly optional fields show the exception marker.              | Field and input type.                                              |
+| nested                     | Inner direction and optionality replace outer values.                   | Any supported inner direction/default combination.                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Context.** Explicit props resolve against `vertical` and unset defaults, then the nearest provider exposes the resolved values to descendants.
+- **ORD2 — Root props.** FormLayout-owned target and direction reflection compose with StyleX and caller styling; caller DOM props reach the same root without replacing owned reflection.
+- **ORD3 — Optionality.** The layout default establishes the unmarked majority; a field-level `isRequired` or `isOptional` marks the exception and controls native validation only when explicitly requested.
+
+### Performance and resources
+
+- **PR1 — Stable context identity.** Descendants receive one memoized context value per direction/optionality pair; FormLayout owns no listener, observer, timer, or external resource.
+
+## Accessibility contract
+
+- **AR1 — Layout remains nonsemantic.** FormLayout renders a `<div>` and does not imply `<form>`, group, label, or submission semantics; callers provide those when their composition needs them.
+- **AR2 — Required state remains perceivable.** A form-wide optionality convention may remove redundant visible markers, but descendant controls preserve the resolved required state for assistive technology.
+- **AR3 — Logical order is preserved.** Every direction retains DOM order and logical inline flow; FormLayout does not create a separate keyboard order.
+
+## Design relationships
+
+No current component-local or shared design record prescribes a FormLayout-specific representation. Spacing uses the current token scale; exact tuning remains token-owned.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Layout container": {"target": "form-layout"},
+  "Form title": {
+    "none": {
+      "reason": "intentional: A title is caller-owned content; FormLayout neither renders nor styles a title part."
+    }
+  },
+  "Fields": {
+    "none": {
+      "reason": "intentional: Caller-owned Field and input components retain their own theming targets."
+    }
+  },
+  "Footer": {
+    "none": {
+      "reason": "intentional: A footer is caller-owned content; FormLayout neither renders nor styles an action region."
+    }
+  }
+}
+```
+
+The root target reflects the closed `direction` axis. It owns the outer arrangement container and does not claim the visual parts rendered by child components.
+
+## Family and system relationships
+
+- `family:input-fields` identifies FormLayout as the owner of outer arrangement, spacing, direction, and form-level optionality.
+- `component:Field` consumes horizontal-label direction and optionality while retaining label, control, description, and status ownership.
+- `architecture:public-component-api` owns root prop, styling, event, ref, and released-type composition.
+- `architecture:component-theming-surface` owns the root target's anatomy mapping and reflected direction axis.
+- `architecture:component-test-sufficiency` owns bounded, mutation-sensitive evidence selection.
+
+## Verification map
+
+| Contract          | Verification                                                                                           | Representative states                                            | Mutation or failure expectation                                                                               | Audit section                    |
+| ----------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1–FR4, ORD1     | `FormLayout.test.tsx`, exact-head `AuditMatrix` story-play guards, and independent rendered inspection | vertical, horizontal, horizontal-label wide/narrow, nested       | Changed display, order, breakpoint, or provider shadowing fails; narrow grouping remains visible for OQ1.     | `audit:FormLayout/behavior`      |
+| FR5, ORD3, AR2    | `FormLayout.test.tsx`, Field tests, and scoped browser accessibility audit                             | required/optional/unset defaults; explicit exceptions            | A redundant marker returns, resolved `aria-required` disappears, or native validation changes.                | `audit:FormLayout/accessibility` |
+| FR6, ORD2         | root composition tests, BaseProps lint, theming-target tests, and exact-head AuditMatrix play          | ref, DOM/data/ARIA/events, class/style/`xstyle`, every direction | A caller input drops, direction reflection is replaced, or the public target disappears.                      | `audit:FormLayout/api`           |
+| AR1, AR3          | DOM tests and exact-head browser/a11y evidence                                                         | plain root, native form wrapper, LTR/RTL                         | Layout invents semantics, changes DOM/keyboard order, or uses physical inline placement.                      | `audit:FormLayout/accessibility` |
+| Theming anatomy   | knowledge validation, consumer-doc projection, and theming-target tests                                | root target; caller-owned title, fields, and footer              | The target loses its semantic owner or FormLayout claims a child component's painter.                         | `audit:FormLayout/theming`       |
+| Documentation     | docs typecheck and prop literal/reference tests                                                        | all directions, breakpoint, optionality, root anatomy            | Docs claim wrapping, physical order, flex growth, or another behavior the released code lacks.                | `audit:FormLayout/docs`          |
+| RTL applicability | verified-N/A registry plus exact-head AuditMatrix logical-order assertion                              | horizontal and horizontal-labels in LTR/RTL                      | A physical side, directional glyph, transform, scroll/drag, overlay, or directional key path makes N/A stale. | `audit:FormLayout/i18n-rtl`      |
+
+## Decision log
+
+No component-local decision is asserted. This draft records released behavior and its current shared owners.
+
+## Open questions
+
+- **OQ1 — At 480px and below, should each horizontal-label pair preserve a smaller intra-field label/control gap than the gap between adjacent fields?** (`human-design`)
+
+## Content boundary
+
+This draft records verified shipped behavior and the unresolved narrow grouping relationship. It does not create form semantics, prescribe caller content, approve a new API or target, or duplicate consumer prop tables and audit-run scores.

package/src/FormLayout/FormLayout.tsx

@@ -82,10 +82,11 @@ export interface FormLayoutProps extends BaseProps<HTMLDivElement> {
    * Direction of field arrangement.
    *
    * - `'vertical'` — Fields stack top-to-bottom (default). Most common.
-   * - `'horizontal'` — Fields arrange left-to-right in equal-width columns
-   *   using CSS Grid. Each child occupies one equal column.
-   * - `'horizontal-labels'` — CSS Grid with labels to the left of inputs.
-   *   Collapses to vertical when the container is narrow (≤480px).
+   * - `'horizontal'` — Fields occupy one `1fr` CSS Grid track per child in
+   *   logical inline order.
+   * - `'horizontal-labels'` — CSS Grid with labels beside their inputs on the
+   *   inline-start side. Collapses to vertical when the viewport is narrow
+   *   (≤480px).
    *
    * @default 'vertical'
    */

package/src/FormLayout/FormLayoutContext.ts

@@ -20,9 +20,9 @@ import {createLayerScopedContext as createContext} from '../Layer/layerScopedCon
  * Direction of form field arrangement.
  *
  * - `'vertical'` — Fields stack top-to-bottom (default). Most common.
- * - `'horizontal'` — Fields arrange left-to-right, wrapping when needed.
- * - `'horizontal-labels'` — Fields stack vertically but labels sit to the left
- *   of their inputs (settings/admin panel pattern).
+ * - `'horizontal'` — Fields occupy one `1fr` grid track per child in logical inline order.
+ * - `'horizontal-labels'` — Fields stack vertically while labels sit beside
+ *   their inputs on the inline-start side (settings/admin panel pattern).
  */
 export type FormLayoutDirection =
   'vertical' | 'horizontal' | 'horizontal-labels';

package/src/Grid/Grid.test.tsx

@@ -308,6 +308,28 @@ describe('Grid', () => {
     expect(grid).toHaveAttribute('aria-label', 'Product grid');
   });
 
+  it('keeps component-owned theme metadata over colliding pass-throughs', () => {
+    render(
+      <Grid
+        columns={3}
+        gap={4}
+        align="end"
+        justify="center"
+        data-columns="9"
+        data-gap="10"
+        data-align="start"
+        data-justify="stretch"
+        data-testid="grid">
+        <div>Item</div>
+      </Grid>,
+    );
+    const grid = screen.getByTestId('grid');
+    expect(grid).toHaveAttribute('data-columns', '3');
+    expect(grid).toHaveAttribute('data-gap', '4');
+    expect(grid).toHaveAttribute('data-align', 'end');
+    expect(grid).toHaveAttribute('data-justify', 'center');
+  });
+
   it('renders children correctly', () => {
     render(
       <Grid columns={3} data-testid="grid">

package/src/Grid/Grid.tsx

@@ -455,6 +455,7 @@ export function Grid({
   return (
     <div
       ref={ref}
+      {...props}
       {...mergeProps(
         themeProps('grid', {columns: columnsVariant, gap, align, justify}),
         stylex.props(
@@ -470,8 +471,7 @@ export function Grid({
         ),
         className,
         {...style, ...inlineStyle},
-      )}
-      {...props}>
+      )}>
       {children}
     </div>
   );

package/src/Indicator/Indicator.doc.mjs

@@ -171,7 +171,7 @@ defineTheme({
       code: `// When the shape itself is wrong, hand the theme a component. It receives
 // {state, size, isDisabled, children} and nothing else.
 //
-// Use theme tokens, never raw values — run \`npx @astryxdesign/cli docs tokens\` for the
+// Use theme tokens, never raw values — run \`astryx docs tokens\` for the
 // full set. Color: --color-accent, --color-on-accent, --color-border,
 // --color-border-emphasized, --color-background-surface,
 // --color-background-muted. Radius: --radius-inner, --radius-full.
@@ -236,7 +236,7 @@ defineTheme({name: 'brand', indicators: {check: RadioIndicator}});`,
       {
         guidance: true,
         description:
-          'Use theme tokens for every color, radius, and border width in a replacement. Run `npx @astryxdesign/cli docs tokens` for the set.',
+          'Use theme tokens for every color, radius, and border width in a replacement. Run `astryx docs tokens` for the set.',
       },
       {
         guidance: true,
@@ -297,7 +297,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'Use theme tokens for every color, radius, and border width in a replacement. Run `npx @astryxdesign/cli docs tokens` for the set.',
+          'Use theme tokens for every color, radius, and border width in a replacement. Run `astryx docs tokens` for the set.',
       },
       {
         guidance: true,

package/src/PowerSearch/PowerSearch.test.tsx

@@ -552,6 +552,68 @@ describe('PowerSearch', () => {
   });
 });
 
+describe('filter token focus', () => {
+  it('opens the editor with the mouse without opening search suggestions', async () => {
+    const user = userEvent.setup();
+    render(
+      <PowerSearch
+        config={config}
+        filters={[
+          {
+            field: 'status',
+            operator: 'is',
+            value: {type: 'enum', value: 'open'},
+          },
+        ]}
+        onChange={() => {}}
+      />,
+    );
+    const input = screen.getByRole('combobox', {name: 'Search'});
+
+    await user.pointer({
+      target: screen.getByText('Status: is'),
+      keys: '[MouseLeft>]',
+    });
+    expect(input).not.toHaveFocus();
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+    expect(
+      screen.queryByRole('button', {name: 'Apply', hidden: true}),
+    ).toBeNull();
+
+    await user.pointer({keys: '[/MouseLeft]'});
+    expect(
+      await screen.findByRole('button', {name: 'Apply', hidden: true}),
+    ).toBeInTheDocument();
+  });
+
+  it('preserves search entry and token editing with the keyboard', async () => {
+    const user = userEvent.setup();
+    render(
+      <PowerSearch
+        config={config}
+        filters={[
+          {
+            field: 'status',
+            operator: 'is',
+            value: {type: 'enum', value: 'open'},
+          },
+        ]}
+        onChange={() => {}}
+      />,
+    );
+    await user.tab();
+    expect(screen.getByRole('combobox', {name: 'Search'})).toHaveFocus();
+
+    await user.tab({shift: true}); // Remove button
+    await user.tab({shift: true}); // Token label
+    expect(screen.getByRole('button', {name: 'Status: is'})).toHaveFocus();
+    await user.keyboard('{Enter}');
+    expect(
+      await screen.findByRole('button', {name: 'Apply', hidden: true}),
+    ).toBeInTheDocument();
+  });
+});
+
 describe('PowerSearch statusVariant forwarding', () => {
   it('defaults to attached (status renders with data-variant="attached")', () => {
     const {container} = render(

package/src/PowerSearch/PowerSearch.tsx

@@ -900,6 +900,15 @@ export function PowerSearch({
           size={size}
           icon={tokenIcon}
           endContent={valueContent}
+          onMouseDown={
+            handleClick
+              ? e => {
+                  // Keep a token press from entering Tokenizer's input-focus
+                  // redirect. Click still edits/removes; Tab entry is unchanged.
+                  e.preventDefault();
+                }
+              : undefined
+          }
           onClick={
             handleClick
               ? (e: React.MouseEvent) => {

package/src/Token/Token.tsx

@@ -190,7 +190,7 @@ const styles = stylex.create({
     '::after': {
       content: '""',
       position: 'absolute',
-      inset: '-14px',
+      inset: '-4px',
     },
   },
 });

package/src/Token/__tests__/TokenRemoveTarget.a11y.chromium.spec.ts

@@ -0,0 +1,86 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TokenRemoveTarget.a11y.chromium.spec.ts
+ * @input The `Core/PowerSearch` Pre-set Filters story in a built Storybook and
+ *   real mouse input, in both text directions.
+ * @output Real-engine proof that a Token's enlarged remove target stays on its
+ *   X: a press on the end of the value beside it runs the token's own action,
+ *   and a press just outside the visible X still removes.
+ * @position Run with `pnpm test:a11y-contract`. jsdom has no hit testing, so
+ *   the remove target's reach is only observable here.
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+const STORY = 'core-powersearch--with-preset-filters';
+const REMOVE_BUTTONS = '#storybook-root button[aria-label^="Remove "]';
+
+async function open(page: Page, direction: 'ltr' | 'rtl') {
+  await page.setViewportSize({width: 900, height: 600});
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=${STORY}&viewMode=story&globals=direction:${direction}`,
+  );
+  await expect(page.locator(REMOVE_BUTTONS)).toHaveCount(2);
+  const remove = page.locator(REMOVE_BUTTONS).first();
+  const value = page
+    .locator('#storybook-root')
+    .getByText('Open', {exact: true})
+    .first();
+  const x = await remove.boundingBox();
+  const v = await value.boundingBox();
+  if (x == null || v == null) {
+    throw new Error('the Status token has no visible value or remove button');
+  }
+  return {remove, x, v};
+}
+
+for (const direction of ['ltr', 'rtl'] as const) {
+  test(`a press on the end of the value opens its editor (${direction})`, async ({
+    page,
+  }) => {
+    const {x, v} = await open(page, direction);
+    // Two pixels inside the value's inline-end edge, level with the X.
+    const px = direction === 'ltr' ? v.x + v.width - 2 : v.x + 2;
+    const py = x.y + x.height / 2;
+    // Precondition: the point is on the value, not on the visible X.
+    expect(px < x.x || px > x.x + x.width).toBe(true);
+
+    await page.mouse.click(px, py);
+
+    await expect(page.getByRole('combobox', {name: 'Field'})).toBeVisible();
+    await expect(page.locator(REMOVE_BUTTONS)).toHaveCount(2);
+  });
+
+  test(`a press just outside the visible X still removes (${direction})`, async ({
+    page,
+  }) => {
+    const {x} = await open(page, direction);
+    // Two pixels past the X's inline-end edge: outside the 16px glyph, inside
+    // the enlarged target.
+    const px = direction === 'ltr' ? x.x + x.width + 2 : x.x - 2;
+    const py = x.y + x.height / 2;
+
+    await page.mouse.click(px, py);
+
+    await expect(page.locator(REMOVE_BUTTONS)).toHaveCount(1);
+    await expect(page.getByRole('combobox', {name: 'Field'})).toHaveCount(0);
+  });
+}

package/src/postinstall.test.mjs

@@ -24,7 +24,9 @@ import {
   AGENT_DOC_PATHS,
   INIT_MARKERS,
   SETUP_NUDGE,
+  setupNudge,
 } from '../scripts/agent-doc-state.mjs';
+import {cliInvocation} from '../scripts/postinstall.mjs';
 // Dev-only, monorepo-relative: core must not depend on the CLI at runtime (the
 // CLI peer-depends on core), but the test can read the source and the generator.
 import * as cliLeaf from '../../cli/foundation/agent-docs/agent-doc-state.mjs';
@@ -95,6 +97,9 @@ describe('core postinstall — one authoritative source, no drift', () => {
     expect(AGENT_DOC_PATHS).toEqual(cliLeaf.AGENT_DOC_PATHS);
     expect(INIT_MARKERS).toEqual(cliLeaf.INIT_MARKERS);
     expect(SETUP_NUDGE).toBe(cliLeaf.SETUP_NUDGE);
+    expect(setupNudge('pnpm exec astryx')).toBe(
+      cliLeaf.setupNudge('pnpm exec astryx'),
+    );
   });
 
   it('agrees with the CLI leaf on a real project', () => {
@@ -181,3 +186,31 @@ describe('core postinstall — shouldNudge', () => {
     }
   });
 });
+
+describe('core postinstall — the nudge names the command the CLI would print', () => {
+  it('words the nudge around the stem it is given', () => {
+    expect(setupNudge('pnpm exec astryx')).toContain(
+      'run `pnpm exec astryx init` to finish setup',
+    );
+    expect(SETUP_NUDGE).toContain('run `npx @astryxdesign/cli init`');
+  });
+
+  it("asks the project's installed CLI for its stem", async () => {
+    write('package.json', '{"name":"app"}');
+    write('pnpm-lock.yaml', '');
+    write('node_modules/.bin/astryx', '');
+    fs.mkdirSync(path.join(tmp, 'node_modules/@astryxdesign'), {
+      recursive: true,
+    });
+    fs.symlinkSync(
+      path.resolve(import.meta.dirname, '../../cli'),
+      path.join(tmp, 'node_modules/@astryxdesign/cli'),
+    );
+    expect(await cliInvocation(tmp)).toBe('pnpm exec astryx');
+  });
+
+  it('has no stem to offer when the CLI is not installed', async () => {
+    write('package.json', '{"name":"app"}');
+    expect(await cliInvocation(tmp)).toBeUndefined();
+  });
+});