@tailor-platform/app-shell 1.13.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/app-shell",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "An opinionated React application framework for building ERP applications on Tailor Platform",
   "keywords": [
     "app-shell",
@@ -47,37 +47,37 @@
     "access": "public"
   },
   "dependencies": {
-    "@base-ui/react": "1.6.0",
+    "@base-ui/react": "1.8.0",
     "@internationalized/date": "3.12.2",
     "@standard-schema/spec": "^1.1.0",
     "@tailor-platform/auth-public-client": "^0.6.1",
+    "@tailor-platform/vite-plugin-app-shell": "0.3.0",
     "change-case": "^5.4.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "encoding-japanese": "^2.2.0",
-    "lucide-react": "^1.8.0",
+    "lucide-react": "1.8.0",
     "openai": "6.45.0",
     "papaparse": "^5.5.3",
     "react-router": "^8.3.0",
     "sonner": "^2.0.7",
-    "tailwind-merge": "^3.6.0",
-    "@tailor-platform/app-shell-vite-plugin": "0.2.3"
+    "tailwind-merge": "^3.6.0"
   },
   "devDependencies": {
     "@fontsource-variable/noto-sans-jp": "5.3.0",
     "@microsoft/api-extractor": "7.58.12",
     "@tailwindcss/postcss": "^4.3.3",
     "@testing-library/react": "16.3.3",
-    "@testing-library/user-event": "14.6.6",
+    "@testing-library/user-event": "14.6.7",
     "@types/encoding-japanese": "2.2.1",
-    "@types/node": "^25.9.5",
+    "@types/node": "^25.9.6",
     "@types/papaparse": "5.5.2",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "@vitejs/plugin-react": "^6.1.0",
     "@vitest/coverage-v8": "4.1.10",
     "happy-dom": "20.9.0",
-    "postcss": "8.5.26",
+    "postcss": "8.5.28",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "react-hook-form": "7.71.2",

package/skills/app-shell-patterns/SKILL.md

@@ -25,13 +25,15 @@ These are the foundational rules that underpin all patterns. All patterns build
 
 Read it when upgrading `@tailor-platform/app-shell`, and whenever styling, theming, or dark mode looks wrong after a version bump. These breakages are silent: the build succeeds and nothing warns, so the cause is not discoverable from the error output. The package ships no CHANGELOG, so this file is the only migration record available locally.
 
-## Available Patterns
+## Available Pages
+
+A page is the shape of a whole screen — the outer choice, made before picking patterns for the parts inside it. Where a pattern is one recipe, a page fixes the layout of a whole screen and says what belongs in each part of it. Match the screen first, then use the patterns the entry cites for the pieces within it.
 
-### detail
+| Slug                                   | Name        | Description                                                                                                        |
+| -------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
+| [`detail`](references/pages/detail.md) | Detail Page | The screen for a single record — its summary, its contents, the records around it, and the actions available on it |
 
-| Slug                                                                          | Name                     | Description                                                           |
-| ----------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------- |
-| [`detail/hero-with-actions`](references/patterns/detail-hero-with-actions.md) | Hero With Actions Detail | Single-record detail view with workflow actions and activity timeline |
+## Available Patterns
 
 ### form
 
@@ -60,16 +62,17 @@ Read it when upgrading `@tailor-platform/app-shell`, and whenever styling, themi
 ## How to Use
 
 1. Identify the user's intent (list, detail, form, interaction, screen composition, recipe)
-2. Match constraints to an entry slug from the tables above
-3. Read the entry's detailed spec: `references/<category>/<slug>.md` (relative to this file)
-4. Read fundamental references for component APIs, design tokens, and GraphQL conventions: `references/fundamental/`
-5. Implement using ONLY the imports listed in the entry's `requiredImports`
+2. Building a whole screen? Match it to a **page** entry first and read that. A page fixes the screen's shape — its layout, what goes where, and in what order — before any of the parts inside it are chosen.
+3. Match each part you are building to a **pattern** entry slug from the tables above. A one-off recipe rather than a screen skips straight to this step.
+4. Read the entry's detailed spec: `references/<category>/<slug>.md` (relative to this file)
+5. Read fundamental references for component APIs, design tokens, and GraphQL conventions: `references/fundamental/`
+6. Implement using ONLY the imports listed in the entry's `requiredImports` — for a page, the `requiredImports` of the pattern it sent you to
 
 ## Rules
 
 - ALWAYS cite the entry slug in a comment at the top of the file:
-  `/* pattern: list/dense-scan */`
-- NEVER mix patterns in a single page component
+  `/* pattern: list/dense-scan */`. Cite the pattern you implemented, even when a page entry sent you to it.
+- NEVER mix two patterns that solve the same problem in one component — one part, one recipe. Composing patterns for _different_ parts of a screen is expected, and the screen's page entry says which.
 - ALWAYS use AppShell components — do NOT use raw HTML or third-party UI libraries
 - If no entry matches, compose directly from fundamental references
 
@@ -83,4 +86,5 @@ Full rationale in [`design-system.md`](references/fundamental/design-system.md)
 - **Action placement:** primary CTA + status in `Layout.Header`; workflow actions in `ActionPanel`; back/navigation in the breadcrumb — never in `ActionPanel`.
 - **Metric tiles always go in a `Grid`** (`columns={{ initial: 1, md: 2, xl: 4 }}`) — never one-per-row.
 - **Forms default to `form/modal`** — only build a routed full-page form when the design explicitly calls for one.
+- **Forms use AppShell `Form` + `Field`**, submitting via `onFormSubmit` — never a bare `<form onSubmit>` with `FormData`. `onFormSubmit` reads registered `Field.Root`s, so every control (dropdowns included) just needs a wrapping `Field.Root name="…"` — no `name` on the control, no `useState`. React Hook Form is optional, consumer-installed, and only warranted for cross-field validation, field arrays, or a Zod resolver. Details in [`components.md`](references/fundamental/components.md) → Forms.
 - **Handle every state:** loading (skeleton), empty (labelled empty state), and error (inline + retry) — never ship only the happy path.

package/skills/app-shell-patterns/references/fundamental/components.md

@@ -9,7 +9,7 @@
 | This file (`components.md`)                                                                                       | `design-system.md`                                                                                |
 | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | **Imports**, compound structure, hooks, canonical **composition** (`Card` + `Table`, `DataTable`, `Dialog`, etc.) | **Tokens**, theme imports, typography/spacing/radius/elevation **tables**, breakpoints **intent** |
-| JSX examples tied to ERP patterns (`patterns/*`)                                                                  | **`astw:`** rules — only on AppShell `*ClassName` props; plain utilities on **your** elements     |
+| JSX examples tied to ERP patterns (`patterns/*`)                                                                  | **AppShell styling boundary** — plain utilities and no internal `astw:` prefix                    |
 | Prop summaries + links to upstream `docs/components/*.md`                                                         | **Visual conformance**: no magic colors/px on custom markup, motion, dark mode                    |
 
 **Rule of thumb:** “Which component / prop?” → **here.** “Which token / spacing step / elevation?” → **`design-system.md`** §§4–6.
@@ -105,7 +105,7 @@ import { Button, Layout, Tabs } from "@tailor-platform/app-shell";
 </Layout>
 ```
 
-**Notes:** Children that aren't `Layout.Header` or `Layout.Column` are filtered out. Column gap overrides (`<Layout className="astw:gap-6" />`) → **`design-system.md`** §5 (`astw:` rules).
+**Notes:** Children that aren't `Layout.Header` or `Layout.Column` are filtered out. Set column gaps with `<Layout gap={6} />` (supported steps: 4, 6, 8).
 
 **Used in patterns:** every page pattern (`list/*`, `detail/*`, `form/*`).
 
@@ -257,7 +257,7 @@ import { Button, Link } from '@tailor-platform/app-shell';
 
 **Used in patterns:** `list/*` (filter sheet variant).
 
-**Notes:** Size the panel with `Sheet.Content`'s **`size`** prop (`"sm" | "md" | "lg" | "xl" | "full"`, default `"sm"`) — not a width utility. `astw:` rules → **`design-system.md`** §5.
+**Notes:** Size the panel with `Sheet.Content`'s **`size`** prop (`"sm" | "md" | "lg" | "xl" | "full"`, default `"sm"`) — not a width utility.
 
 ### `Menu`
 
@@ -355,7 +355,7 @@ Plus `badgeVariants` CVA for custom-styled siblings.
 
 **Import:** `import { Table } from '@tailor-platform/app-shell'`
 **Purpose:** Semantic data table with scrollable container.
-**API:** Compound — `Table.Root`, `Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Head`, `Table.Cell`, `Table.Caption`. `Table.Root` accepts `containerClassName` for the outer wrapper, `className` for the inner `<table>`. `Table.Head` and `Table.Cell` accept **`align`** (`"left" | "center" | "right"`, default `"left"`) — prefer this over ad-hoc `className="astw:text-right"` and pair the same alignment on the head and its column's cells (right for numeric/money, center for compact status/icon columns).
+**API:** Compound — `Table.Root`, `Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Head`, `Table.Cell`, `Table.Caption`. `Table.Root` accepts `containerClassName` for the outer wrapper, `className` for the inner `<table>`. `Table.Head` and `Table.Cell` accept **`align`** (`"left" | "center" | "right"`, default `"left"`) — prefer this over ad-hoc `className="text-right"` and pair the same alignment on the head and its column's cells (right for numeric/money, center for compact status/icon columns).
 **Example:**
 
 ```tsx
@@ -385,8 +385,8 @@ Plus `badgeVariants` CVA for custom-styled siblings.
 
 **Notes:**
 
-- **Inside a card?** Pass `containerClassName="astw:px-6"` on `Table.Root` for the horizontal inset, and either drop `Card.Content` (bare list form) or pass `Card.Content className="astw:px-0"` (header+content form). Skipping the `containerClassName` lands the first column flush against the card edge. See the `Card` entry for the two canonical forms and a DON'T example. Dense cell typography (**`text-sm`**, **`tabular-nums`** for figures, **`font-mono`** for identifiers) → **`design-system.md`** §4 Typography.
-- **Whole row is clickable.** Use `<Table.Row onClick={() => navigate(detailPath)} className="astw:cursor-pointer">`. For keyboard and screen-reader users, also wrap the primary identifier cell content in `<Link>` (so the row is reachable via Tab; `Table.Row` is a `<tr>` and cannot itself be a Link — wrapping a `<tr>` in `<a>` is invalid HTML). **No per-row "View" / "Open" / "→" buttons.** Per-row `Menu` (overflow `…`) is the only allowed per-row action surface and is reserved for non-navigation actions like Archive, Duplicate.
+- **Inside a card?** Zero the card's horizontal padding — drop `Card.Content` (bare list form) or pass `Card.Content className="px-0!"` (header+content form) — and leave the table container's padding alone. `Table.Head` / `Table.Cell` carry their own `first:pl-6` / `last:pr-6`, so a `containerClassName="px-6"` double-pads and the first column lands 24px right of the card title. See the `Card` entry for the two canonical forms and a DON'T example. Dense cell typography (**`text-sm`**, **`tabular-nums`** for figures, **`font-mono`** for identifiers) → **`design-system.md`** §4 Typography.
+- **Whole row is clickable.** Use `<Table.Row onClick={() => navigate(detailPath)} className="cursor-pointer">`. For keyboard and screen-reader users, also wrap the primary identifier cell content in `<Link>` (so the row is reachable via Tab; `Table.Row` is a `<tr>` and cannot itself be a Link — wrapping a `<tr>` in `<a>` is invalid HTML). **No per-row "View" / "Open" / "→" buttons.** Per-row `Menu` (overflow `…`) is the only allowed per-row action surface and is reserved for non-navigation actions like Archive, Duplicate.
 
 ### `DataTable`
 
@@ -433,7 +433,7 @@ const table = useDataTable({
 
 **Column alignment:** each `Column` accepts **`align`** (`"left" | "right"`) applied to both header and body cell. Numeric `type` columns (`"number"`, `"money"`) default to `"right"` automatically so digits align on the decimal place — pass `align="left"` to opt out; everything else defaults to `"left"`.
 
-**Metadata path:** Prefer `createColumnHelper` + `inferColumns(tableMetadata.order)` (`@tailor-platform/app-shell-sdk-plugin` codegen) when available so enum/datetime/string filters bind to the right editors.
+**Metadata path:** Prefer `createColumnHelper` + `inferColumns(tableMetadata.order)` (`@tailor-platform/sdk-plugin-app-shell` codegen) when available so enum/datetime/string filters bind to the right editors.
 
 **Bucket tabs / segmented UX:** AppShell defines **toolbar chips**, not lifecycle tabs. When design places **`Tabs`** (All / Draft / …) inside the card, compose them **above** `DataTable.Root` and synchronize tab-driven bucket state with **`useCollectionVariables`** (`variables.query` / filters)—see **`patterns/list/dense-scan.md`**.
 
@@ -461,13 +461,13 @@ const table = useDataTable({
 
 **Notes:**
 
-- **Tables inside a card need TWO co-requisite geometry changes** (token-backed spacing rationale → **`design-system.md`** §4 Spacing): (a) Card stops imposing horizontal padding — drop `Card.Content` for the bare form, or pass `Card.Content className="astw:px-0"` for the header+content form. (b) `Table.Root` provides the inset itself via `containerClassName="astw:px-6"`. Skipping (b) lands the first column flush against the card edge — `Table.Cell`'s intrinsic `astw:first:pl-6` does NOT render reliably in this composition.
+- **A table inside a card needs ONE geometry change, not two** (token-backed spacing rationale → **`design-system.md`** §4 Spacing): the card stops imposing horizontal padding. Drop `Card.Content` for the bare form, or pass `Card.Content className="px-0!"` for the header+content form. That is all. `Table.Head` and `Table.Cell` already carry an intrinsic `first:pl-6` / `last:pr-6`, which supplies the inset on its own — so the table container must add **none**. Padding on the container stacks on top of the cell's own and pushes the first column 24px past the card title.
 
 **Bare table-in-card (list pages, no card-level title):**
 
 ```tsx
 <Card.Root>
-  <Table.Root containerClassName="astw:px-6">{/* … */}</Table.Root>
+  <Table.Root>{/* … */}</Table.Root>
 </Card.Root>
 ```
 
@@ -476,18 +476,19 @@ const table = useDataTable({
 ```tsx
 <Card.Root>
   <Card.Header title="Line items" />
-  <Card.Content className="astw:px-0">
-    <Table.Root containerClassName="astw:px-6">{/* … */}</Table.Root>
+  <Card.Content className="px-0!">
+    <Table.Root>{/* … */}</Table.Root>
   </Card.Content>
 </Card.Root>
 ```
 
-**DON'T — first column lands flush against the card edge:**
+**DON'T — the first column sits 24px right of the card title:**
 
 ```tsx
 <Card.Root>
-  <Card.Content className="astw:px-0">
-    <Table.Root>{/* missing containerClassName="astw:px-6" */}</Table.Root>
+  <Card.Content className="px-0!">
+    {/* double-pads: the container's 24px adds to the cell's own first:pl-6 */}
+    <Table.Root containerClassName="px-6">{/* … */}</Table.Root>
   </Card.Content>
 </Card.Root>
 ```
@@ -565,26 +566,37 @@ const table = useDataTable({
 />
 ```
 
-**Used in patterns:** `detail/hero-with-actions` (body sections).
+**Used in:** `page/detail` (body sections).
 
 ### `ActionPanel`
 
 **Import:** `import { ActionPanel } from '@tailor-platform/app-shell'`
 **Purpose:** Right-rail panel listing workflow actions for a detail page (approve, reject, archive, etc.).
-**API:** `ActionPanelProps` — `title`, `actions` (array of `{ label, onSelect, variant?, disabled?, hidden? }`), `className`.
+**API:** `ActionPanelProps` — `title`, `actions`, `className`. Each action is `{ key, label, icon, onClick?, disabled?, loading?, variant? }`; `key`, `label` and `icon` are all **required**, the handler is `onClick` (not `onSelect`), and `variant` is `"default" | "destructive"`. There is no `hidden` — omit a row by not spreading it in. The row type is not exported on its own; annotate an array as `ActionPanelProps["actions"]`.
 **Example:**
 
 ```tsx
 <ActionPanel
   title="Actions"
   actions={[
-    { label: "Approve", variant: "default", onSelect: handleApprove },
-    { label: "Reject", variant: "destructive", onSelect: handleReject, disabled: !canReject },
+    { key: "approve", label: "Approve", icon: <Check />, onClick: handleApprove },
+    ...(canReject
+      ? [
+          {
+            key: "reject",
+            label: "Reject",
+            icon: <X />,
+            onClick: handleReject,
+            variant: "destructive" as const,
+            loading: rejecting,
+          },
+        ]
+      : []),
   ]}
 />
 ```
 
-**Used in patterns:** `detail/hero-with-actions`.
+**Used in:** `page/detail`.
 
 **Notes:**
 
@@ -595,7 +607,7 @@ const table = useDataTable({
 **Import:** `import { ActivityCard } from '@tailor-platform/app-shell'`
 **Purpose:** Timeline of events on a record (audit log, status changes, comments).
 **API:** Compound — `ActivityCard.Root`, `ActivityCard.Items` (generic over item type), plus `ActivityCardProps`, `ActivityCardItem`, `ActivityCardItemProps`. Items render with timestamp + actor + description.
-**Used in patterns:** `detail/hero-with-actions` (right column or bottom section).
+**Used in:** `page/detail` (right column, for revision history / audit trail).
 
 ### `Alert`
 
@@ -619,13 +631,41 @@ const table = useDataTable({
 
 ## Forms
 
+> **Which form stack?** AppShell's `Form` / `Field` / `Fieldset` wrap Base UI primitives and are the
+> default — they need no extra dependency. They own **accessibility wiring and visual state only**
+> (`htmlFor`, `aria-describedby`, `data-invalid` / `data-dirty` / `data-touched`); they do **not** own
+> your values. React Hook Form is **optional** and consumer-installed — reach for it only when a form
+> genuinely needs cross-field validation, field arrays, or a Zod resolver. The two compose; they are
+> not alternatives. `react-hook-form` stopped being a runtime dependency in 1.4.0; it is a dev-only
+> dependency of the package today, used to test the RHF integration contracts — if you use it,
+> install it in your own app.
+
 ### `Form`
 
 > Full API: [https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/form.md](https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/form.md)
 
 **Import:** `import { Form } from '@tailor-platform/app-shell'`
-**Purpose:** Form root wired to react-hook-form. Use with `Field`, `Fieldset`, and Zod for validation.
-**API:** `FormProps` — `errors`, `actionsRef`, `validationMode`, `noValidate`, plus a namespace exposing form-related sub-helpers. Generic over `FormValues`.
+**Purpose:** Form root that wraps Base UI's form primitive. Provides shared validation context for
+child `Field.Root`s, consolidated error display, and server-error routing by field `name`.
+**API:** `FormProps` — `onFormSubmit`, `onSubmit`, `errors`, `actionsRef`, `validationMode`,
+`noValidate`, `id`. Generic over `FormValues`.
+**Actions outside the form:** give the `Form` an `id` and point a detached submit button at it with
+the native `form` attribute. This is how a page-header Save reaches a body form (1.13.0+):
+
+```tsx
+<Layout.Header
+  title="Create product"
+  actions={[<Button key="save" type="submit" form="product-form">Save</Button>]}
+/>
+<Form id="product-form" onFormSubmit={save}>…</Form>
+```
+
+**Submit:** use `onFormSubmit(values)` — it receives parsed form values and is the default. Use the
+low-level `onSubmit` **only** when handing the native event to React Hook Form's `handleSubmit`.
+**Never** hand-roll `<form onSubmit={e => new FormData(e.currentTarget)}>` — that skips validation
+and error routing.
+**Server errors:** pass `errors={{ fieldName: "message" }}`; they route to the matching
+`Field.Error` and clear when the user edits that field.
 **Example:** see `form/single-page.md`.
 **Used in patterns:** all `form/*`.
 
@@ -633,9 +673,71 @@ const table = useDataTable({
 
 **Import:** `import { Field } from '@tailor-platform/app-shell'`
 **Purpose:** Single form field with label + control + error message wiring.
-**API:** Compound. Wraps any input control (`Input`, `Select`, `Combobox`, etc.) and binds it to react-hook-form via `name`.
+**API:** Compound — `Field.Root`, `Field.Label`, `Field.Control`, `Field.Description`, `Field.Error`,
+`Field.Validity`. `Field.Root` establishes a context boundary; every Base UI-backed AppShell control
+placed inside it inherits label association, `aria-describedby`, `disabled`, and invalid state
+automatically.
+**`Field.Control` is already a styled input** — write `<Field.Control />`, not
+`<Field.Control render={<Input />} />`. `Input` and `Field.Control` share the same base classes, so
+the `render` form just double-wraps. Reach for `Input` directly when you need a control outside a
+`Field.Root`, or when the value is React-controlled.
+**RHF interop (optional):** `Field.Root` accepts `isTouched`, `isDirty`, `invalid`, and `error`,
+matching RHF's `fieldState` shape — so `<Field.Root {...fieldState}>` works with no adapter.
 **Used in patterns:** all `form/*`.
 
+### How values reach your submit handler
+
+There are three separate mechanisms. Picking the wrong mental model is the most common
+form mistake, so be explicit about which one a screen uses.
+
+**1. `Form` + `Field.Root` → `onFormSubmit` (the default).** `onFormSubmit` does **not** read
+`FormData`; it collects values from the `Field.Root`s registered inside the `Form`, keyed by each
+field's `name`. Every AppShell control works this way once wrapped in a `Field.Root name="…"` —
+including `Select`, `Combobox`, and `Autocomplete`. They need **no `name` of their own and no React
+state**:
+
+```tsx
+<Form onFormSubmit={(values) => save(values)}>
+  <Field.Root name="category">
+    <Field.Label>Category</Field.Label>
+    <Select items={CATEGORIES} placeholder="Select category" />
+  </Field.Root>
+</Form>
+```
+
+**2. Native submission** — a plain `<form>`, `new FormData(form)`, or a server action. This reads the
+DOM, so each control needs its own `name`. `Select`, `Combobox`, and `Autocomplete` gained `name`
+(plus `form`, `required`, `inputRef`) in 1.13.0; before that they contributed nothing to a native
+payload.
+
+**3. React Hook Form** — optional, consumer-installed. RHF owns the values; drive the control with
+`value` / `onValueChange` from a `Controller` and spread `fieldState` onto `Field.Root`. Warranted
+for cross-field validation, field arrays, or a Zod resolver — not for ordinary CRUD forms.
+
+#### Object items
+
+Under mechanism 1, a non-string item is serialised into the submitted value:
+
+| Item shape                             | Value in `onFormSubmit`              |
+| -------------------------------------- | ------------------------------------ |
+| `string`                               | the string                           |
+| `{ value, label }`                     | `value`, automatically               |
+| any other object                       | **JSON string** — usually not wanted |
+| any other object + `itemToStringValue` | whatever that function returns       |
+
+So for arbitrary objects, pass `itemToStringValue` to choose the submitted key. It is distinct from
+`mapItem`, which controls what the user sees:
+
+```tsx
+<Combobox
+  items={warehouses}
+  mapItem={(w) => ({ label: w.name, key: String(w.id) })}
+  itemToStringValue={(w) => String(w.id)}
+/>
+```
+
+Multi-select submits an array.
+
 ### `Fieldset`
 
 **Import:** `import { Fieldset } from '@tailor-platform/app-shell'`
@@ -657,7 +759,7 @@ const table = useDataTable({
 **Import:** `import { Textarea } from '@tailor-platform/app-shell'`
 **Purpose:** Multi-line text input. Maps to spec field types: `text`, long-form `string`. Use instead of `Input` whenever the value is prose (notes, descriptions, replies, reasons).
 **API:** `TextareaProps` — Base UI's field control (`value`, `defaultValue`, `onChange`, `onValueChange`, `disabled`, `required`, `readOnly`, `name`, aria-\*) rendered as a `<textarea>`, plus `rows`. `cols` / `wrap` are not accepted — the control is `w-full`, so neither can take effect.
-**Sizing:** no fixed height — `rows` sets the visible line count and the user can drag it taller. `min-h-16` is a hard floor, so `rows` only takes effect from 3 up. Width is the parent's job: the control is `w-full`, and `cols` is not accepted because it could never win against that. Do **not** reach for `Input` and a height override; `Input` is locked to `h-9`, and an `astw:h-*` override from a consuming app resolves to nothing unless that exact utility was compiled into the package CSS.
+**Sizing:** no fixed height — `rows` sets the visible line count and the user can drag it taller. `min-h-16` is a hard floor, so `rows` only takes effect from 3 up. Width is the parent's job: the control is `w-full`, and `cols` is not accepted because it could never win against that. Do **not** reach for `Input` and a height override; `Input` is locked to `h-9`, and an application must not use AppShell's internal `astw:` classes.
 **Field integration:** drops straight into `Field.Root` for label/description/error wiring exactly like `Input` and `Checkbox` — no bespoke `error` prop.
 **Example:**
 
@@ -702,6 +804,22 @@ const table = useDataTable({
 
 ---
 
+## AI
+
+### `AIChat`
+
+> Full API: [https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/ai-chat.md](https://raw.githubusercontent.com/tailor-platform/app-shell/refs/heads/main/docs/components/ai-chat.md)
+
+**Import:** `import { AIChat } from '@tailor-platform/app-shell'`
+**Purpose:** Building blocks for an LLM assistant UI — a streaming conversation view over a composer, plus reasoning, tool-call, and citation parts. The root places three regions in a fixed order, `Layout`-style: `AIChat.Header` (optional) over `AIChat.Conversation` over `AIChat.Composer` (optional). Each region carries its own props; the root carries `status`.
+**API:** Root (`status`) + regions — `AIChat.Header` (`title`, `icon`, `actions`), `AIChat.Conversation` (`autoScroll`, transcript as children), `AIChat.Composer` (`onSubmit`, `onStop`, `value`/`defaultValue`/`onValueChange`, `placeholder`, `disabled`, `submitOnEnter`, `actions`) — + transcript parts: `AIChat.Message`, `.Response`, `.EmptyState`, `.Suggestions`/`.Suggestion`, `.Actions`/`.Action`, `.Reasoning`/`.ReasoningTrigger`/`.ReasoningContent`, `.ChainOfThought*`, `.Tool*`, `.Sources*`, `.History`.
+**Composer:** Body is `Textarea` over one action row per `form/composer`'s layout. Enter submits (IME-safe), Shift+Enter newlines, and `status` from `useAIChat()` drives the busy/Stop state.
+**Header:** a 48px strip (graphic + `text-sm font-semibold` title + right action slot) closed by a full-width rule; renders only when `title` or `actions` is set.
+**Renders no chrome:** no border or background of its own — wrap in `Card`, `Sheet`, or a `Layout.Column`, with `overflow-hidden` so the header rule stays inside rounded corners.
+**Used in patterns:** none yet — a component, not a catalogue pattern (platform-planning#1748).
+
+---
+
 ## Auth & access
 
 ### `AuthProvider`

package/skills/app-shell-patterns/references/fundamental/design-system.md

@@ -1,6 +1,6 @@
 # Design System
 
-Authority for **visual-only** decisions — tokens, theme imports, breakpoints intent, the `astw:` prefix, and custom-component conformance. For **React component APIs** (imports, props, JSX composition), pair this file with `components.md`; that split avoids duplicating tables and lengthy examples across both docs.
+Authority for **visual-only** decisions — tokens, theme imports, breakpoints intent, and custom-component conformance. For **React component APIs** (imports, props, JSX composition), pair this file with `components.md`; that split avoids duplicating tables and lengthy examples across both docs.
 
 `@tailor-platform/app-shell` ships an opinionated design system as CSS variables, bridged into Tailwind v4's token namespace. Use it whether you are consuming AppShell components (most cases) or building a custom component to fill a gap.
 
@@ -302,23 +302,30 @@ Stock Tailwind breakpoints — AppShell does not change them.
 
 Two-column **behavior** (right rail stacks under `lg`): respect AppShell defaults — do not force side-by-side grids on narrow viewports. The `Layout` column width table lives in `components.md` → Layout; reuse those numbers instead of guessing rem values here.
 
-## 5. The `astw:` prefix
+## 4b. Links
 
-AppShell exposes **layout / sizing / overflow** escapes on some components via props like `containerClassName` and `className` on roots. Prefix those utilities with `astw:` so they apply to the wrapper AppShell controls.
+One treatment for every text link — inside `DescriptionCard`, in table rows,
+in cards:
 
-**Do not duplicate full component trees here.** Typical patterns (full `DataTable` composition, `Sheet` + footer, `Table.Root` + card insets) live in `components.md` with JSX you can copy.
+- **`text-primary` at rest, `hover:underline` only.** Colour carries the affordance; a resting underline is noise. Pair with `underline-offset-4`.
+- **Internal routes** use app-shell's `Link` (`to`), never a bare `<a href>`.
+- **External destinations** use `<a target="_blank" rel="noopener noreferrer">` with a lucide `ExternalLink` at `size-3` after the label. There is no dedicated component for this; that markup is the convention.
+- **Identifiers** (document numbers, SKUs) keep `font-mono` on top of the link style.
 
-Minimal illustration — the same rules apply to other `*ClassName` hooks:
+This is the treatment `DescriptionCard` already applies to its `type: "link"`
+fields — match it rather than inventing a second one.
+
+## 5. AppShell styling boundary
+
+`astw:` is AppShell's internal compiled CSS prefix. **Never write it in an application.** It is not a consumer customization API and arbitrary prefixed utilities may not exist in the shipped CSS.
+
+Use ordinary Tailwind utilities on your own markup. An explicitly documented layout hook, such as `Table.Root`'s `containerClassName`, also accepts ordinary utilities from the application's Tailwind build:
 
 ```tsx
-<Table.Root containerClassName="astw:px-6 astw:overflow-y-auto" />
+<Table.Root containerClassName="px-6 overflow-y-auto" />
 ```
 
-Rules:
-
-- `astw:` only on AppShell `*ClassName` / root `className` hooks each component exposes. Use **plain** Tailwind (`flex`, `gap-4`, `bg-background`, …) on **your** markup.
-- Stick to **layout** utilities (`flex`, `grid`, `max-h-*`, `min-h-0`, `overflow-*`, widths). Avoid painting over internal AppShell padding or colors via `astw:` — prefer an upstream prop or composition change.
-- Steps like `astw:p-4` still resolve through the scale — never arbitrary `astw:p-[13px]`.
+For an AppShell component's appearance, use its documented props, variants, or composition instead of styling over its internals.
 
 ## 6. When AppShell doesn't have a component you need
 
@@ -380,13 +387,13 @@ When a custom component proves reusable across 2+ apps, promote it upstream into
 
 ### Where to look
 
-| Concern                                             | File                               |
-| --------------------------------------------------- | ---------------------------------- |
-| Component imports, props, JSX composition           | **`components.md`**                |
-| Page / screen layout patterns                       | **`patterns/<type>/<slug>.md`**    |
-| Design tokens, `astw:` rules, custom UI conformance | **this file** (`design-system.md`) |
+| Concern                                                         | File                               |
+| --------------------------------------------------------------- | ---------------------------------- |
+| Component imports, props, JSX composition                       | **`components.md`**                |
+| Page / screen layout patterns                                   | **`patterns/<type>/<slug>.md`**    |
+| Design tokens, AppShell styling boundary, custom UI conformance | **this file** (`design-system.md`) |
 
-**`components.md`** holds long JSX compositions (e.g. **`DataTable`**, **card + `Table`**). **Do not copy those trees into this file** — link back here only for tokens and `astw:` policy.
+**`components.md`** holds long JSX compositions (e.g. **`DataTable`**, **card + `Table`**). **Do not copy those trees into this file** — link back here only for tokens and the AppShell styling boundary.
 
 `patterns/` is organised by page type: `patterns/list/`, `patterns/detail/`, `patterns/form/`, `patterns/interaction/`. Pick the slug matching the screen you're building.
 

package/skills/app-shell-patterns/references/fundamental/graphql.md

@@ -108,7 +108,7 @@ For `pnpm gql-tada:check` to pass, always destructure with optional chaining and
 
 For **standard list pages**, do not hand-roll only `first` / `after`. Compose AppShell **`DataTable`** + **`useCollectionVariables`** + **`useDataTable`**: derive query variables from `variables.pagination`, `variables.query`, `variables.order`, map `edges` / `pageInfo` / `total` into `useDataTable`’s `data`. See **`patterns/list/dense-scan.md`** and **`components.md` → DataTable**.
 
-When `@tailor-platform/app-shell-sdk-plugin` codegen is enabled, pass generated **`tableMetadata`** into **`useCollectionVariables`** so `variables.query` / `variables.order` are typed against your Tailor GraphQL inputs (upstream **data-table.md** Typed query variables).
+When `@tailor-platform/sdk-plugin-app-shell` codegen is enabled, pass generated **`tableMetadata`** into **`useCollectionVariables`** so `variables.query` / `variables.order` are typed against your Tailor GraphQL inputs (upstream **data-table.md** Typed query variables).
 
 ## Mutations and cache invalidation