@viglet/viglet-design-system 2026.3.9 → 2026.3.11

package/README.md

@@ -1,25 +1,31 @@
 # Viglet Design System
 
 Shared component library, design tokens, hooks, utilities, and i18n for the
-seven applications that install it: the Turing, Dumont and Shio consoles,
-the Cloud Console, the Cloud Home, Schools, and the Roadkeep GUI.
-`consumers.json` is the list, and it is what the guards read.
+nine applications that install it: the Turing, Dumont and Shio consoles,
+the Cloud Console, the Cloud Home, Schools, the Roadkeep GUI,
+the Openviglet Website and Viglet Docs. `consumers.json` is the list, and it is
+what the guards read.
 
 **[Browse the component catalogue](https://openviglet.github.io/viglet-design-system/)** — every
 component, its variants and its props, rebuilt on each commit to `2026.3`. Look
 there before writing a component: the catalogue is the answer to "does this
 already exist".
 
-The six applications that install this package are the consumers it holds itself
+The nine applications that install this package are the consumers it holds itself
 to, declared in [`consumers.json`](consumers.json) rather than remembered: each
-entry names its framework, its chrome, the accent it renders with and the
-subpaths it takes, and CI refuses prose that names a subset as though it were
-the whole set. An eighth is one entry there, and the checks widen with it.
+entry names its framework, its chrome, the accent it renders with, where its
+source is and the subpaths it takes, and CI refuses prose that names a subset as
+though it were the whole set. A tenth is one entry there, and the checks widen
+with it. The file ships in the package, and a consumer holds its own entry to its
+source with [`viglet-ds-consumer-entries`](#keeping-your-entry-in-the-register-true).
 
 Three are Vite consoles (Turing, Shio, Dumont), one is a Vite platform home
-(the Cloud Home), one is a Vite desktop shell (the Roadkeep GUI), and two are
-Next applications (the Cloud Console and Schools). The split matters: a Next
-consumer takes no `./router` and no `./vite`.
+(the Cloud Home), one is a Vite desktop shell (the Roadkeep GUI), one is a Vite
+marketing site (the Openviglet Website), two are Next applications
+(the Cloud Console and Schools), and one is Docusaurus (Viglet Docs). The split
+matters: a
+Next consumer takes no `./router` and no `./vite`, and Viglet Docs takes no root
+entry at all — only `./preset` and the background.
 
 ## Installation
 
@@ -27,30 +33,41 @@ consumer takes no `./router` and no `./vite`.
 pnpm add @viglet/viglet-design-system
 ```
 
+**Declare `react-hook-form` yourself.** It is a required peer, not something this
+package brings: the root entry exports `Form`, and that module re-exports
+`FormProvider`, `useFormContext` and `useFormState` straight from it. A second
+copy in your tree is a second React context, and `useFormContext` then returns
+null inside a form that looks correctly wired. Declaring it is what keeps the
+install to one copy — `npm ls react-hook-form` should say `deduped`.
+
 ## Trying a change in a product before publishing
 
 A change here is a change to shared chrome, so the question is always what it
-does to Shio, Turing, Dumont, the Cloud Console, the Cloud Home, Schools and the
-Roadkeep GUI — and the answer should not require a publish. `use:local` walks a
-products root, so it reaches the first three; the other four are checked out
-elsewhere and `npm pack` into them is the loop until that changes (VDS73). From this checkout:
+does to Shio, Turing, Dumont, the Cloud Console, the Cloud Home, Schools,
+the Roadkeep GUI, the Openviglet Website and Viglet Docs — and the answer should
+not require a publish. The last two take the package by caret range rather than
+pinning it, so they also receive each release the moment they install one. From
+this checkout:
 
 ```bash
-pnpm use:local           # build, then push dist into every 2026.3 product on disk
+pnpm use:local           # build, then push dist into every consumer checked out here
 pnpm use:local --list    # show what it would write to, and stop
 ```
 
-It finds the consumers by reading their `package.json`, and finds where each one
-keeps the installed copy by following the link its own package manager made, so
-neither a version bump nor a switch of package manager breaks the loop. Nothing
-in the product's manifest or lockfile changes: `pnpm install` in the product puts
-the published build back.
+It finds each consumer at the `checkout` its entry in `consumers.json` declares,
+relative to this repository, with `{line}` standing for this checkout's version
+line, so a 2026.2 worktree pushes into the 2026.2 products. A declared checkout
+that is not there is named, not skipped in silence, and finding none at all is an
+error. It finds where each consumer keeps the installed copy by following the
+link its own package manager made, so neither a version bump nor a switch of
+package manager breaks the loop. Nothing in the product's manifest or lockfile
+changes: `pnpm install` in the product puts the published build back.
 
-Pass directories to narrow it, and `--no-build` to reuse the `dist` already on
-disk:
+Pass consumer ids or directories to narrow it, and `--no-build` to reuse the
+`dist` already on disk:
 
 ```bash
-pnpm use:local ../shio/2026.3/shio-react --no-build
+pnpm use:local shio --no-build
 ```
 
 One thing it refuses to do: push over a tree whose dependencies are behind. It
@@ -74,8 +91,8 @@ viglet-ds-check-duplicates src
 It fails, naming the import that replaces each local copy:
 
 ```
-src/components/page-header.tsx:18  declares PageHeader
-    replace it with:  import { PageHeader } from "@viglet/viglet-design-system/router"
+src/components/bento-hero.tsx:18  declares BentoHero
+    replace it with:  import { BentoHero } from "@viglet/viglet-design-system/bento"
 ```
 
 One-line re-export shims are the sanctioned pattern and are skipped. When a
@@ -98,6 +115,114 @@ worked through, and drop it once the count is zero. `--json` prints the findings
 for a bot to read; `--manifest <path>` checks against an export list other than
 the installed one.
 
+## Linting a page against the shell
+
+Two rules in [docs/BENTO-AUTHORING.md](docs/BENTO-AUTHORING.md) pass every other
+gate when broken: a page that sets its own width, gutter or vertical rhythm, and a
+stylesheet that sets `--vg-primary` directly instead of through its
+`--vg-primary-*-base` inputs. `viglet-ds-page-lint` checks both. Point it at the
+directories whose pages render inside `BentoShell`:
+
+```bash
+viglet-ds-page-lint src
+```
+
+```
+src/app/home.page.tsx:125  page.column  the page's outermost element sets max-w-7xl px-6 pb-12
+    remove them: BentoShell sets the column, and column="narrow" or "wide" names the other widths
+src/index.css:14  primary.direct  sets --vg-primary
+    claim it through the --vg-primary-base and --vg-primary-foreground-base inputs, light and -dark, at :root
+```
+
+A page is a file ending in `.page.tsx` or `.page.jsx`, and the lint checks the
+outermost element its default export returns. `--page-pattern <regex>` names your
+own convention. It reads pages with the TypeScript compiler, so `typescript` must
+be installed in the product. A deliberate exception takes a reason, in the file:
+
+```ts
+// viglet-ds-allow-page-column -- a kiosk rendered outside the shell
+```
+
+`viglet-ds-allow-primary -- <reason>` does the same for the second rule.
+`--warn` and `--json` work as they do for `viglet-ds-check-duplicates`.
+
+Pass the stylesheet where you re-key the palette to also measure it:
+
+```bash
+viglet-ds-page-lint src --contrast src/index.css
+```
+
+It lays your stylesheet over the preset the way the two cascade and measures every
+token pair your stylesheet changes on both grounds: each `--vg-X` with its
+`--vg-X-foreground`, text and muted text on the page, the accented label on the
+page, and the white label on the accent fill. A pair under 4.5:1 on either ground
+is a finding at the line that declares the token, with both grounds' ratios:
+
+```
+src/index.css:41  contrast.pair  --vg-accent-fg on --vg-background is 3.59:1 on the light ground and 7.53:1 on the dark ground; 4.5:1 needed
+```
+
+It reads `oklch()`, hex, `rgb()`, `hsl()`, `var()` chains and
+`color-mix(in oklab, …)`. Anything else is reported as unread rather than
+guessed. `viglet-ds-allow-contrast -- <reason>` in the stylesheet keeps a pair
+you have signed off.
+
+## Keeping your entry in the register true
+
+`consumers.json` records the subpaths each product takes, and this package's
+guards read it. `viglet-ds-consumer-entries` measures what your source actually imports and
+compares it with your entry there, in both directions. Run it from the product's
+package root, in its own test step:
+
+```bash
+viglet-ds-consumer-entries
+```
+
+It finds your entry by the `name` in your `package.json` (`--consumer <id>`
+names it outright), scans the `sourceRoots` that entry declares, and fails on a
+subpath you import and do not declare, or one you declare and import nowhere:
+
+```
+consumer-entries: shio's source and its entry in consumers.json disagree
+
+  imported, and not declared:
+    ./router  first at src/components/dialog.delete.tsx:17
+```
+
+Tests, stories and comments inside the roots are not counted. A failure means
+the entry here is wrong, so the fix is a change to `consumers.json` in this
+repository. `--json` prints the measurement; `--root <dir>` measures a checkout
+other than the current directory.
+
+## Using it from Claude Code
+
+This repository publishes a Claude Code plugin, `viglet-ds`, for a product that
+installs the package. It serves the component catalogue over MCP, loads a skill
+that points a session at it, adds `/viglet-ds-check` to run the CLIs above
+against the working tree, and denies a write that declares a component the
+package already exports, naming the import to use instead.
+
+The catalogue server is a bin of its own, `viglet-ds-mcp`, so any MCP client can
+start it from a product's install. It has two tools: `find_component` ranks the
+components that do a job, and `read_component` returns one component's purpose,
+props, the contract sections that govern it and an import to start from. The
+authoring contract, the boundary and the token reference are resources
+(`viglet-ds://authoring`, `viglet-ds://boundary`, `viglet-ds://tokens`). The data
+is `dist/catalogue.json`, generated at build time from the declarations you
+compile against and also exported as `./catalogue.json`. A component's purpose is
+its own doc comment, and every exported component has one: the build refuses a
+component that arrives without it.
+
+```
+/plugin marketplace add openviglet/viglet-design-system
+/plugin install viglet-ds@viglet-design-system
+```
+
+With the plugin enabled in a repository's `.claude/settings.json`,
+`viglet-ds-page-reference` writes only the artboards and leaves the skill to the
+plugin. [claude-plugin/README.md](claude-plugin/README.md) has the settings to
+commit and the package range the plugin supports.
+
 ## Setup
 
 ### 1. Import styles
@@ -147,6 +272,12 @@ one the catalogue shows.
 
 ### 2. Initialize i18n
 
+`/i18n` is the only way in. The root entry used to re-export these three, which
+meant every consumer of `.` resolved `i18next` and
+`i18next-browser-languagedetector` and carried the locale bundle whether or not
+it ever asked for a translation; since 2026.3 it does not, and a product that
+imported them from `.` changes the specifier and nothing else.
+
 ```ts
 import { initVigI18n } from "@viglet/viglet-design-system/i18n";
 
@@ -166,6 +297,31 @@ import i18n from "i18next";
 registerVigTranslations(i18n);
 ```
 
+**Both merge key by key, and your key always wins.** Shipping your own `common`
+does not cost you the package's — `common.save` stays yours and `common.next`
+still resolves to the word this package ships. `registerVigTranslations` never
+replaces a key the host already has, so calling it twice is safe.
+
+**`initVigI18n` takes any language, not only the two this package ships.** Pass
+`es`, `fr` or anything else and it arrives whole; `en` and `pt` still merge leaf
+by leaf with yours. The package's own strings exist in `en` and `pt` only, so
+`fallbackLng` stays `en` and a screen asking for a string the package ships
+reads English under a third language until you translate it yourself.
+
+This used to merge a namespace at a time: a product with its own `common`
+replaced the package's outright, and every string the package asked for under
+that namespace fell back to its English default — in a Portuguese product,
+silently. If you worked around it by renaming a namespace or copying the
+package's keys into yours, you can stop.
+
+**One string lands before any of this.** The boot loader from
+`@viglet/viglet-design-system/vite` is HTML written at build time and paints
+before a bundle runs, so it cannot ask i18next for anything. Its status region is
+named `"Loading <title>"` unless you say otherwise — pass `loadingLabel` for the
+phrase in your language, or `loadingLabels` (a language tag to a phrase) for a
+product that ships several, which the loader's inline script picks from
+`navigator.language`.
+
 ### 3. Setup providers
 
 ```tsx
@@ -260,6 +416,14 @@ import {
 } from "@viglet/viglet-design-system";
 ```
 
+`Button` and `GradientButton` take `loading` for an action in flight. The button
+shows a spinner, sets `aria-busy`, ignores a second press (including a form's
+submit) and keeps keyboard focus. Do not pass `disabled` for that: a disabled
+button drops the focus of the control just pressed, just as the result is
+announced. For a control that is unavailable for now, such as a Save with nothing
+to save, pass `aria-disabled="true"`. It stays focusable and ignores activation.
+Keep `disabled` for a control that is genuinely unavailable.
+
 ### App Components
 
 ```tsx
@@ -274,16 +438,25 @@ import {
 ```
 
 A page's chrome — its header, its list, its sidebar — comes from the
-[bento layer](#the-bento-layer) rather than from here. Read the next section
-before reaching for `PageHeader`, `GridList` or `InternalSidebar`.
+[bento layer](#the-bento-layer). It is the only page vocabulary this package
+ships; if you are upgrading from a release that still had `PageHeader`,
+`GridList` or `InternalSidebar`, read the next section.
 
-### Two eras, and which one a new page should use
+### Moving off the console era
 
-This package exports two complete page vocabularies. The **console era** is what the consoles ship on today; the **[bento layer](#the-bento-layer)** is the current one, and Turing has cut over to it. Every console-era export is marked `@deprecated` in its own types, so an editor strikes it through and offers the swap.
+This package used to export two complete page vocabularies. The **console era**
+is gone: `pnpm chrome:census` counts, per consumer checked out beside this
+repository, the source files taking a console-era component — directly or
+through a re-export shim — and it reads zero across all nine, so the eleven
+components below were removed. The **[bento layer](#the-bento-layer)** is what
+remains, and with one chrome left there is nothing to choose between: the
+`SectionCardChromeProvider` that used to declare which one a page rendered in
+went with them.
 
-Nothing is being removed. No product has started cutting over, and a removal will get its own roadmap line rather than arriving as a side effect of this notice — so existing pages keep working and need no rush.
+Each row is a swap rather than a rename: the replacement takes its own props,
+and the note says where the two differ.
 
-| Console era | Use instead | |
+| Removed | Use instead | |
 |---|---|---|
 | `PageHeader` | `BentoHero` | Same title/subtitle/icon, plus a tone — the chip follows the product accent. |
 | `SubPageHeader` | `BentoHero` | With `BentoBackLink` for the back target and `BentoActionsMenu` for the menu. |
@@ -294,9 +467,166 @@ Nothing is being removed. No product has started cutting over, and a removal wil
 | `NavMain` | `BentoNavRail` | |
 | `NavUser` | `BentoUserMenu` | Routes and feature flags arrive as props. |
 | `SubPage` | `BentoEntityShell` | Renders through a render prop, so the shell never learns what an entity is. |
-| `Page`, `PageContent` | — | No single replacement, deliberately: the shell is where a product is itself. Compose `BentoNavRail`, `BentoUserMenu` and `BentoCommandPalette`. |
+| `Page`, `PageContent` | `BentoShell` | Takes the rail, the header's two edges and the page; it owns `main` and the reading column, so a page sets no width. |
+
+`DialogDelete`, `LoadProvider` and `GradientButtonLink` were never console-era — the bento layer uses them itself, and they are the whole of `./router` now.
+
+### The mascot
+
+`VigletAvatar` is the Viglet mascot: a small sun that shows what the system is
+doing. It is one `<canvas>` and no new dependency — the faceted core is drawn
+directly, so a product gets the mascot by installing this package and nothing
+else.
+
+```tsx
+import { VigletAvatar } from "@viglet/viglet-design-system";
+
+<VigletAvatar state="working" size={128} />;
+```
+
+The five states are named for the toast kinds, so a product that already reports
+through `toast` has nothing to translate:
+
+| `state` | When | What it does |
+|---|---|---|
+| `idle` | nothing is happening | a slow, low glow |
+| `working` | a request is in flight | an orbit with a travelling arc |
+| `success` | it finished | a swell, then a pulse outward |
+| `error` | it failed | the light goes out — it does not turn red |
+| `attention` | something arrived | a ring rises from below |
+
+Four further props shape it rather than drive it: `compact` pulls the camera in
+and drops the pool of light, for a collapsed dock; `unread` holds a slow orbit
+while an answer waits; `activity` is a counter you bump to make the mascot react
+to something smaller than a state change, like a keystroke; and `seed` fixes the
+field of rising embers. The same props always draw the same sparks, so a product
+that wants a different field per visit passes a changing `seed` itself.
+
+The mascot is decorative (`aria-hidden`) and says nothing a screen reader can
+use — give the surface that wraps it the accessible name. It draws one frame and
+starts no animation loop for a reader whose system asks for reduced motion, and
+`paused` does the same for a product with its own motion switch. When nothing is
+happening it stops drawing altogether rather than holding a loop open.
+
+### The assistant dock
+
+`VigletAssistant` is the surface the mascot lives in. Collapsed it is a status
+light with the system's last sentence typed beside it; open it is a panel with a
+transcript and a composer.
+
+```tsx
+import { VigletAssistant } from "@viglet/viglet-design-system";
+
+<VigletAssistant
+  state={state}
+  caption="/q3-results published at 14:02."
+  messages={messages}
+  busy={busy}
+  onSend={(text) => ask(text)}
+/>;
+```
+
+**The dock knows no backend.** `messages`, `busy` and `onSend` are the whole
+contract — the endpoint, the prompt and the key stay in your product. Leaving
+`onSend` off is how you turn the chat off: the composer is not rendered at all
+and the dock becomes a place the system reports from, which is what a product
+that only wants notification feedback should mount.
+
+A message may carry one `action`, so an answer can offer something to do with
+it — the label is your copy, already translated:
 
-`DialogDelete`, `LoadProvider` and `GradientButtonLink` are **not** console-era — the bento layer uses them itself, and they are not deprecated.
+```tsx
+messages={[{
+  role: "assistant",
+  text: "Lead with the number.",
+  action: { label: "Use this title", onSelect: () => setTitle(suggested) },
+}]}
+```
+
+**What the system reports is a `report`, not an assistant message.** A publish,
+a failure or an arrival has a `tone` (one of the mascot's five states), a time,
+a `read` flag and up to three `actions`, and it renders apart from the
+conversation. It never opens a composer, so a dock with no `onSend` lists reports
+on their own. You own the list, as you own the messages:
+
+```tsx
+<VigletAssistant
+  messages={reports}
+  onRead={(id) => markRead(id)}
+  onDismiss={(id) => dismiss(id)}
+/>
+
+const reports = [{
+  id: "publish-q3",
+  role: "report",
+  tone: "error",
+  text: "Could not publish /q3-results.",
+  at: failedAt,
+  actions: [
+    { label: "Retry", onSelect: retry },
+    { label: "Open the page", onSelect: openPage },
+  ],
+}];
+```
+
+Collapsed, the orb counts the unread reports, and the caption is the newest one
+unless you pass `caption`. The mascot's state follows that report's tone unless
+you pass `state`. Pass `unread` a number to count something else. `onRead` fires
+for each unread report when the dock opens or closes, since it was on screen,
+and a dismiss button appears on each report once you pass `onDismiss`. A report
+is announced once, when it arrives, and not again when the dock opens or
+re-renders.
+
+It pins itself to the bottom-right of the viewport; pass `inline` to render it
+in flow and place it yourself. In a bento product, pass it to `BentoShell` as
+`dock` instead: the shell holds the corner, stacks `BentoBackToTop` above the
+dock, and keeps either from covering the other. `open` / `onOpenChange` make it controlled,
+Escape collapses it, and the caption is typed for everyone while a screen reader
+is handed the whole sentence at once.
+
+Its own words — the state names, the two buttons, the placeholder — come from
+the `assistant.*` keys this package ships in `en` and `pt`. See
+[Initialize i18n](#2-initialize-i18n); everything else it says is your copy.
+
+#### Letting notifications drive it
+
+You already report outcomes through `toast`. `useAssistantNotifications` reads
+the Toaster back, so the mascot moves without a second call beside each one:
+
+```tsx
+import {
+  Toaster,
+  VigletAssistant,
+  useAssistantNotifications,
+} from "@viglet/viglet-design-system";
+
+function Chrome() {
+  const { state, caption, activity } = useAssistantNotifications();
+
+  return (
+    <>
+      <Toaster />
+      <VigletAssistant state={state} caption={caption} activity={activity} />
+    </>
+  );
+}
+```
+
+It **wraps nothing**. Call sonner from anywhere in your app — from a module that
+has never heard of this hook — and the mascot still moves.
+
+| Toast | State |
+|---|---|
+| `toast.loading` | `working` |
+| `toast.success` | `success` |
+| `toast.error` | `error` |
+| `toast.warning`, `toast.info` | `attention` |
+| nothing on screen | `idle` |
+
+With several up, work in progress outranks an outcome and a failure outranks a
+success. `caption` is the toast's own title when it is a string — a toast
+rendered as JSX has no sentence to lift, so you get `null` rather than a guess.
+The hook is opt-in: pass `state` yourself and nothing here interferes.
 
 ### Hooks
 
@@ -306,6 +636,7 @@ import {
   useDateLocale,
   useGridAdapter,
   useSubPageBreadcrumb,
+  useAssistantNotifications,
   useTheme,
   useBreadcrumb,
   useCurrentUser,
@@ -357,19 +688,29 @@ import type {
 
 ## What's Included
 
-### UI Primitives (39 components)
+### UI Primitives (48 components)
+
+Accordion, Avatar, Badge, Breadcrumb, Button, Card, Checkbox, Dialog, Drawer, DropdownMenu, FloatingFormulasBg, Form, FormActions, FormItemTwoColumns, GlassCard, GradientButton, GradientSwitch, HoverCard, IconPickerDialog, Input, Label, NavigationMenu, Pagination, Popover, Progress, PulseRing, Resizable, SectionCard, Select, Separator, Sheet, Sidebar, Skeleton, Slider, Stepper, StickySaveBar, Switch, Table, Tabs, Textarea, Toaster (sonner), Toggle, ToggleGroup, Tooltip, UserAvatar, UserMenu, VigletAssistant ([the dock](#the-assistant-dock)), VigletAvatar ([the mascot](#the-mascot))
+
+### App Components (19 components)
 
-Accordion, Avatar, Badge, Breadcrumb, Button, Card, Checkbox, Dialog, Drawer, DropdownMenu, Form, FormActions, FormItemTwoColumns, GradientButton, GradientSwitch, HoverCard, Input, Label, NavigationMenu, Pagination, Popover, Progress, Resizable, SectionCard, Select, Separator, Sheet, Sidebar, Skeleton, Slider, Sonner (Toaster), Stepper, Switch, Table, Tabs, Textarea, Toggle, ToggleGroup, Tooltip
+AppFooter, AppSwitcher, BackendStatusBanner, BackendStatusProvider, BadgeColorful, BadgeLocale, DialogDelete, ErrorBoundary, GradientButtonLink, LanguageSelect, LanguageSwitcher, LoadProvider, Login, ModeToggle, ModeToggleSidebar, NavSecondary, StartupFirst, ThemeProvider, VigletAppSwitcher
 
-### App Components (23 components)
+`DialogDelete`, `GradientButtonLink` and `LoadProvider` are imported from `@viglet/viglet-design-system/router`; every other name above comes from the package root. `Login` and `StartupFirst` are compounds — each is a root with named parts on it, the way `Card` is.
 
-AppFooter, BadgeColorful, BadgeLocale, DialogDelete, GradientButtonLink, LanguageSelect, LoadProvider, ModeToggle, NavSecondary, ThemeProvider
+### Bento Layer (31 components)
 
-Console-era, `@deprecated`, still exported — see [the swap table](#two-eras-and-which-one-a-new-page-should-use): BlankSlate, GridList, InternalSidebar, NavMain, NavUser, Page, PageContent, PageHeader, StickyPageHeader, SubPage, SubPageHeader
+AdaptiveSectionCard, BentoActionsMenu, BentoBackLink, BentoBackToTop, BentoCommandPalette, BentoCountTile, BentoDataTable, BentoDiff, BentoEmptyState, BentoEntityShell, BentoEntityTile, BentoFilterBar, BentoFormHero, BentoFormSection, BentoHero, BentoHeroIconPicker, BentoInlineEdit, BentoListPage, BentoNavRail, BentoPaletteTrigger, BentoPanel, BentoSaveBar, BentoScrollSaveBar, BentoSection, BentoShell, BentoShortcutsDialog, BentoStatusMarker, BentoTile, BentoTileGrid, BentoUserMenu, BentoVersionRail
+
+All from `@viglet/viglet-design-system/bento`, with `@viglet/viglet-design-system/bento.css` beside it. [The bento layer](#the-bento-layer) is what each one is for and how a page composes them; this is the inventory.
+
+Removed with the console era — see [where each one went](#moving-off-the-console-era): BlankSlate, GridList, InternalSidebar, NavMain, NavUser, Page, PageContent, PageHeader, StickyPageHeader, SubPage, SubPageHeader
 
 ### Hooks
 
-`useIsMobile`, `useDateLocale`, `useGridAdapter`, `useSubPageBreadcrumb`
+`useIsMobile`, `useDateLocale`, `useGridAdapter`, `useSubPageBreadcrumb`, `useAssistantNotifications`, `useSidebarOptional`
+
+`useSidebarOptional()` is `useSidebar()` for a component that may not have a `SidebarProvider` above it — it returns `undefined` instead of throwing, which is what a Module Federation remote needs when the host owns the sidebar and the remote only renders into it.
 
 `useGridAdapter(data, config)` tracks each extractor in `config`, not the object holding them, so a `url` builder that closes over a route param or a locale re-maps the rows when it changes. Pass the config inline if you like — keep the extractors themselves stable (a field name, a module-level function, a `useCallback`) and the memo holds.
 
@@ -419,7 +760,7 @@ This is separate from a component's **colour palette**. `SectionCard` (`blue | v
 
 ### i18n
 
-Base translations (EN/PT) for common UI strings: buttons, form labels, dialog text, navigation, theme.
+Base translations (EN/PT) for common UI strings: buttons, form labels, dialog text, navigation, theme, and the assistant dock.
 
 ## Tech Stack
 
@@ -454,6 +795,7 @@ of it:
 ```ts
 import "@viglet/viglet-design-system/bento.css";
 import {
+  BentoShell,
   BentoEntityShell,
   BentoListPage,
   BentoFormHero,
@@ -466,11 +808,144 @@ The stylesheet is a separate import from the components, so a consumer taking
 only the layout maths does not pull CSS it never renders. It reads the preset's
 tokens, so import the preset too.
 
+`BentoShell` is the page frame. It reserves the gutter for the rail you pass,
+lays out the header's leading and trailing edges, holds the corner (the
+`VigletAssistant` you pass as `dock`, with `BentoBackToTop` stacked above it;
+`backToTop={false}` drops the button), and owns `main`: the width, the gutters
+and the vertical rhythm. A page
+inside it sets none of those. Choose the width by name with `column`: `default`,
+`narrow` for a single-question form, `wide` for a table, or `full` for a tool
+that fills the viewport. Each width is a custom property
+(`--bento-column-default`, `--bento-column-narrow`, `--bento-column-wide`) that
+you can redefine at `:root`.
+
+```tsx
+<BentoShell
+  column={isForm ? "narrow" : "default"}
+  rail={<BentoNavRail groups={groups} homeRoute={ROUTES.HOME} />}
+  headerStart={<ProductMark />}
+  headerEnd={<BentoUserMenu accountRoute={ROUTES.ACCOUNT} logoutUrl={ROUTES.LOGOUT} />}
+>
+  <Outlet />
+</BentoShell>
+```
+
+`BentoDataTable` is the list a curator sorts, range-selects and acts on at scale.
+It mounts only the rows in view, so ten thousand cost what twenty do. Pass `rows`,
+`getRowId`, `columns` (a header, a `cell`, and a `sortValue` to make it sortable),
+and optionally `rowActions` for a per-row menu and `selectionActions` for the bar
+that appears over a selection. The arrows move between rows, Shift with an arrow
+or a click extends a selection, and Enter calls `onRowOpen`. The column picker
+reports `onLayoutChange`, and you store the layout, as you do for `BentoListPage`.
+
+```tsx
+<BentoDataTable
+  rows={posts}
+  getRowId={(p) => p.id}
+  getRowLabel={(p) => p.title}
+  label={t("posts")}
+  columns={[
+    { id: "title", header: t("title"), cell: (p) => p.title, sortValue: (p) => p.title, hideable: false },
+    { id: "updated", header: t("updated"), cell: (p) => format(p.updated), sortValue: (p) => p.updated },
+  ]}
+  rowActions={[{ id: "trash", label: t("trash"), icon: IconTrash, tone: "destructive", onSelect: trash }]}
+  selectionActions={[{ id: "trash", label: t("trash"), icon: IconTrash, onSelect: trash }]}
+  onRowOpen={(p) => navigate(p.url)}
+/>
+```
+
+`AdaptiveSectionCard` renders the console's compound form markup — a `Header`
+child and a `Content` child — as a frosted bento section, so a form written that
+way moves without being rewritten. That compound API is the whole difference
+from `BentoFormSection`, which takes the same icon, title and description as
+props. A section whose header it cannot read keeps the frosted surface and all
+of its children; a frosted box that is not part of a form is `BentoPanel`.
+
+**`SectionCardChromeProvider`, `useSectionChrome`, the `SectionChrome` type and
+the `defaultOpen` prop were removed in this release.** They picked between the
+console card and the frosted section, and every consumer finished its cutover —
+so every remaining call site passed `chrome="bento"`, the value it would have got
+anyway. Delete the provider and the hook; the sections beneath render as they
+already did. A `useSectionChrome()` call that drove a product's own branch can be
+replaced by the bento arm of that branch.
+
+**Give every `BentoActionsMenu` item an `id`**, a stable name for the verb such as
+`"post.delete"`, and the same for `BentoEntityShell`'s `extraActions`. It is
+rendered as `data-action-id` and means nothing to the package, but it lets a
+product check its console verbs against its agent's, since a menu item is
+otherwise an anonymous `onSelect`. An item without one warns outside production
+in this release and stops type-checking in the next.
+
+`BentoFilterBar` is the query row above a list: a search field, the facets you
+declare (a `choice` of options, single or `multiple`, or a `date` range), the
+active filters as removable chips, and a clear-all. It holds no state. You pass
+`value` and get one `onChange` per action, typing included once it pauses, so the
+value can live in the URL and a filtered view is a link. Pass it to a
+`BentoDataTable` as `selectionScope` too, and a selection clears when the filters
+change the rows:
+
+```tsx
+<BentoFilterBar
+  value={filters}
+  onChange={setFilters}
+  facets={[
+    { id: "state", kind: "choice", label: t("state"), multiple: true, options: states },
+    { id: "updated", kind: "date", label: t("updated") },
+  ]}
+/>
+<BentoDataTable rows={filtered} selectionScope={JSON.stringify(filters)} … />
+```
+
+`BentoDiff` compares two versions of structured content field by field, for
+revision history, a review of what an agent changed, or a translation against its
+source. Pass `before`, `after` and the `fields` to compare. A field is `text`
+(compared by word), `rich` (HTML, compared on the blocks it renders, so markup
+alone is no change) or `value` (compared whole). Unchanged fields collapse behind
+a count. A side that is `null` renders the other whole, as a created or deleted
+item. Every change is named in text as well as coloured. `BentoVersionRail` lists
+the revisions (author, person or agent, time) as a listbox a reader picks two
+from, by keyboard or pointer. Neither fetches anything.
+
+`BentoCommandPalette` takes a second group whose items the product supplies per
+query, beside the nav items it matches itself. Pass `onQueryChange` to hear the
+query as typed and `group` to answer it:
+
+```tsx
+<BentoCommandPalette
+  open={open}
+  onOpenChange={setOpen}
+  items={navItems}
+  onQueryChange={setQuery}
+  group={{ label: t("documents"), items: hits, pending, onSelect: openDocument }}
+/>
+```
+
+Those items are rendered in the order given and never re-ranked — your search
+already ranked them by relevance it understands, and a substring match here
+would only undo that. Set `pending` while the query is in flight so the dialog
+says so rather than showing an empty list that is not empty yet.
+
+Bind the shell's keys with `useBentoShellShortcuts` rather than a keydown listener
+of your own. ⌘K on macOS, Ctrl+K elsewhere, or `/` calls `onPalette`, and `?`
+calls `onShortcuts`. A bare key typed into an input, a textarea, a select or an
+editable node is left to the field. `BentoPaletteTrigger` is the header button,
+with the same chord as its hint, and `BentoShortcutsDialog` lists the same set
+(`BENTO_SHELL_SHORTCUTS`), so the guide shows exactly the keys that work:
+
+```tsx
+useBentoShellShortcuts({
+  onPalette: () => setPaletteOpen((open) => !open),
+  onShortcuts: () => setShortcutsOpen((open) => !open),
+});
+
+<BentoShell headerStart={<><ProductMark /><BentoPaletteTrigger onClick={() => setPaletteOpen(true)} /></>}>
+```
+
 "Carries none of it" is measured rather than claimed. `pnpm run build` ends by
 bundling three fixtures through this package's own `exports` map, and fails if a
 bento module, a bento class name or a run of `bento.css`'s selectors reaches a
 consumer that imported only the root entry. `size-budget.json` records what each
-entry costs: today the whole root entry is 87 KB gzipped and `./bento` 22 KB,
+entry costs: today the whole root entry is 91 KB gzipped and `./bento` 31 KB,
 measured with everything the build externalises left out, so the numbers
 describe this package rather than its dependencies. The preset's
 `--vg-bento-tone-*` tokens are deliberately not counted as the layer: they ship
@@ -484,7 +959,7 @@ correct rather than a leak. The subpath is for a consumer who wants only that
 background.
 
 Every subpath in the table above is also **imported, required and type-checked
-as you would use it** on each build: one fixture pulls all fifteen through the
+as you would use it** on each build: one fixture pulls all seventeen through the
 real `exports` map, a CommonJS probe requires the seven that offer it, and a
 generated TypeScript probe imports a value from each typed entry and uses it —
 so a `types` field resolving to the wrong declarations fails here rather than
@@ -502,6 +977,14 @@ do, and npm cannot mark a peer required for one entry point and optional for
 another. `pnpm run build` fails if any other entry starts importing it, so the
 split above stays true rather than becoming folklore.
 
+**`react-hook-form` is a required peer, and `react-router-dom` is the only
+optional one.** It was a plain dependency until VDS77, which is the one case
+where that is wrong: every other library this package shares state through is a
+peer, and this is the one carrying a React context a duplicate would split. The
+build already left it for the consumer to supply, so the manifest was promising
+something the bundle did not deliver; `scripts/externals.test.ts` now fails if
+anything externalised as a peer is declared a dependency again.
+
 [docs/BENTO-AUTHORING.md](docs/BENTO-AUTHORING.md) is the contract for writing a
 bento page: the three page shapes, what the package will not hold for you, and
 the colour, i18n, accessibility and layout rules that keep two consoles looking
@@ -521,8 +1004,9 @@ The catalogue proves a component; these prove the arrangement.
 ## Contributing
 
 The package manager here is pnpm, matching the Shio, Turing, Dumont, Cloud Home
-and Schools workspaces. The Cloud Console and the Roadkeep GUI install with npm,
-which is a fact about those repositories and not about this one.
+and Schools workspaces. The Cloud Console, the Roadkeep GUI,
+the Openviglet Website and Viglet Docs install with npm, which is a fact about
+those repositories and not about this one.
 
 ```bash
 pnpm install