basalt-ui 1.28.0 → 1.29.0

package/agent/rules/basalt-tokens.md

@@ -8,7 +8,7 @@ paths:
 ---
 
 <!-- basalt:coverage -->
-<!-- GENERATED from src/surfaces.ts — `basalt-ui check-coverage --write`. Do not hand-edit. -->
+<!-- GENERATED from src/surfaces.ts — `bun scripts/check-coverage.ts --write`. Do not hand-edit. -->
 <!-- backed by: guard kinds — css-raw-surface, inline-font-size, off-identity-accent, off-system-surface-var, raw-color-fn, raw-font-family, raw-hex, raw-radius, raw-surface, surface-shadow-override, theme-allow-unscoped · oxlint rules — basalt/no-raw-font-size, basalt/raw-size-literal, basalt/token-layer-boundary -->
 <!-- not guarded: — -->
 <!-- /basalt:coverage -->
@@ -32,10 +32,9 @@ The accent is **split by ROLE**, and this is the one thing an author gets wrong:
   control always reads white on either page. **Never fill with `VX.accent`.**
 
 **The palette is DERIVED, not authored** (`tokens/derive.ts` from one seed + five bounded knobs), and
-a consumer retunes it through `createBasaltTheme(overrides?, { derive, fonts, radius, density })`.
-That is why no hex, no shade index and no pixel constant belongs in a rule, a doc or a component:
-every one of them is an output of a config the consumer may move. Read the values off `VX.*` and the
-theme; read the numbers, when you genuinely need them, off `tokens/palette.ts`.
+a consumer retunes it through `createBasaltTheme(overrides?, { derive, fonts, radius, density })` —
+no hex, shade index or pixel constant belongs in a rule, doc or component. Read values off `VX.*`
+and the theme; read raw numbers, if you need them, off `tokens/palette.ts`.
 
 ## Color — never a raw literal
 
@@ -44,28 +43,26 @@ theme; read the numbers, when you genuinely need them, off `tokens/palette.ts`.
   in non-component files) or through the Mantine theme (`color` / `c` / `bg`, `theme.colors`).
 - **Opacity is `alpha(token, a)`** (`color-mix`), never `rgba()` — so the hue keeps resolving per
   scheme.
-- **No off-identity Mantine accents.** `teal`/`violet`/`grape`/`indigo`/`pink` still render
-  on-palette (the theme reskins every family), and are rejected anyway because they signal
-  off-identity intent. Allowed: **`blue`** (the one earned hue), **`gray`**, and the status names
-  `red`/`green`/`orange`/`yellow`. A positive delta is `color="green"`, never `teal`.
-- **Never pin a shade index** — `c="yellow.7"`, `bg="blue.4"`, `var(--mantine-color-red-6)` each name
-  one fixed swatch that is identical in both schemes, so the shade that is legible on dark is the one
-  that fails on light. Use `VX.status.*` for a verdict, or the bare hue name and let the theme pick.
+- **No off-identity Mantine accents** — allowed: **`blue`** (the earned hue), **`gray`**, and the
+  status names `red`/`green`/`orange`/`yellow`. A positive delta is `color="green"`, never `teal`.
+- **Never pin a shade index** (`c="yellow.7"`, `var(--mantine-color-red-6)`) — one fixed swatch is
+  identical in both schemes, so what's legible on dark fails on light. Use `VX.status.*` or the
+  bare hue name.
 - **"Ink earns its color."** Default to neutral. A hue is justified by trend, signal/status, or
   genuine multi-series separation. The accent lands on the single primary CTA per view, focus rings,
   links and small status pops — never on borders, large fills, routine icons or secondary buttons.
 - **Categorical/series color is consumer data**, declared once through `defineSeries` →
-  `seriesTokens`/`groupTokens` and wired into `buildPaletteCss`, never a Mantine accent prop and
-  never an inline pair. `groupTokens(GROUP, MAP)` assumes the same map reaches
-  `BasaltProvider`'s `paletteOptions.groups` under the key `` `${GROUP}-` `` — **with the trailing
-  dash**, which is a CSS-var prefix and not a group name. Derive both from one `GROUP` constant;
-  a mismatch emits refs to variables the stylesheet never declares, with no tsc error and no
-  runtime throw — just unstyled charts.
+  `seriesTokens`/`groupTokens` and wired into `buildPaletteCss`, never a Mantine accent prop.
+  `groupTokens(GROUP, MAP)` assumes the map reaches `BasaltProvider`'s `paletteOptions.groups`
+  under the key `` `${GROUP}-` `` — **with the trailing dash**. Derive both from one `GROUP`
+  constant; a mismatch emits refs to variables the stylesheet never declares, silently.
 
 ## Surfaces — one collapsed token set
 
 `VX.surface` is exactly: `bg` · `panel` · `panelHover` · `elevated` · `subtle` · `overlay` ·
-`field` · `border` · `hairline`. Plus `VX.divider` — NOT a surface, the ONE seam/line token (every `AppShell` region edge + between-rows rule, ink-/white-alpha, holds under the derive knobs); `hairline` is the card ring, `border` the control/overlay line — neither is ever a seam.
+`field` · `border` · `hairline`. `VX.divider` is NOT a surface — the one seam/line token (every
+`AppShell` region edge + between-rows rule); `hairline` is the card ring, `border` the
+control/overlay line — neither is ever a seam.
 
 The theme **collapses Mantine's raw ramp steps onto those tokens** (`cssVariablesResolver` + theme
 `styles`), so every Mantine component — AppShell, Table, Input, Divider, Tabs, Popover, Accordion,
@@ -79,13 +76,12 @@ and never reach for a raw ramp-step var (`var(--mantine-color-gray-N)`).
   the integer that happens to equal `md` today; `radius="sm"`, never a numeric radius.
 - **Card radius has one source**, `VX.radiusCard` / `--vx-radius-card`: the Mantine chrome and the
   Mantine-free `ChartCard` resolve to the same token. Cards must never diverge.
-- **Sub-scale micro-spacing is legitimate and allowed raw** — a tight cluster below the scale's
-  first step has no token, so use the raw number rather than inventing a micro-token or peppering
-  `theme-allow`. The same permission holds in CSS modules: a declaration whose every literal is
-  micro does not fire. One non-micro value makes the whole declaration a finding, and an inline
-  style OBJECT in TSX still fires, because there the Mantine prop existed.
-- **Dense by default** — the framework targets compact surfaces; reach for the tighter step.
-- **Icons size through the icon's own `size` prop**, which is not spacing.
+- **Sub-scale micro-spacing is legitimate and allowed raw** — below the scale's first step, use the
+  raw number rather than inventing a micro-token. A CSS-module declaration whose every literal is
+  micro does not fire; one non-micro value makes it a finding, and an inline style OBJECT in TSX
+  still fires (there the Mantine prop existed).
+- **Dense by default** — reach for the tighter step. Icons size through their own `size` prop,
+  which is not spacing.
 
 ## Type
 
@@ -113,48 +109,31 @@ An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin
 <Widget style={{ borderRadius: 3 }} />
 ```
 
-- **An annotation must START its comment** — after `//`, `/*`, `<!--`, a block gutter `*`, or
-  nothing but whitespace. Prose that merely MENTIONS the token waives nothing; a file documenting
-  its own waivers used to disarm itself.
-- **File scope is spelled, never inferred**: `theme-allow-file <id>… — <why>`, anywhere in the file.
-  A bare `theme-allow-file` waives nothing at all.
-- **A typo waives nothing.** A word in the id slot naming no rule is recorded as unknown; the
-  annotation still covers the ids it got right. Because the id slot is read strictly, a bare reason
-  needs a separator — `theme-allow: <why>` or `theme-allow <id> — <why>`, never `theme-allow <why>`.
-- **Three placements work, and both engines agree on all three**: the reported line, a comment-ONLY
-  line directly above it (reaching the first CODE line below, through the rest of its comment
-  block), and in CSS a trailing annotation reaching back over the declaration it terminates. A blank
-  line ends the reach — that is how you say "this comment is not about the next statement".
-- **JSON and `.webmanifest` take a member key**, since they cannot hold a comment. For a manifest
-  the first remedy is `basaltAppPlugin`, not a waiver: a hand-copied hex drifts from the palette.
-- **The three import-boundary rules honour no escape at all** (`visx-boundary`, `visx-tooltip`,
-  `token-layer-boundary`) — an architecture boundary a stray comment can switch off is the bypass
-  they exist to prevent. The agent-chat guards honour `basalt-agent-allow`, a separate token that
-  never waives a `theme-allow` finding, or the reverse.
-
-Unsupported shapes are asserted as unsupported in both engines' test grids (`src/guard/
-check-source.test.ts`, `configs/oxlint-plugin.test.ts`), so "unsupported" and "silently broken"
-cannot read the same. **Audit them**: `basalt-ui check-theme --audit-allows` re-runs the scan with each waiver
-neutralized, one at a time, and **exits 1 on a waiver that suppresses nothing** — a dead waiver
-silently covers the next real finding on that line. It judges plugin-rule waivers too, by re-running
-oxlint; where oxlint is unreachable the verdict is "cannot judge", never "dead". Its scope line is
-part of the report: `0 dead` is not `0 dead anywhere`.
+- **An annotation must START its comment** (`//`, `/*`, `<!--`, a `*` gutter, or bare whitespace) —
+  a mention mid-prose waives nothing.
+- **File scope is spelled, never inferred**: `theme-allow-file <id>… — <why>`, anywhere in the
+  file; a bare one waives nothing.
+- **A typo waives nothing** — an unrecognized id is recorded unknown, the rest of the annotation
+  still covers the ids it got right.
+- **Three placements agree in both engines**: the reported line, a comment-only line directly
+  above it, and (CSS) a trailing annotation reaching back over the declaration it terminates. A
+  blank line ends the reach.
+- **JSON/`.webmanifest` take a member key** — first remedy is `basaltAppPlugin`, not a waiver.
+- **The three import-boundary rules honour no escape at all**; the agent-chat guards honour
+  `basalt-agent-allow`, a separate token that never waives a `theme-allow` finding, or the reverse.
+
+**Audit them**: `basalt-ui check-theme --audit-allows` re-runs the scan with each waiver
+neutralized and **exits 1 on a waiver that suppresses nothing**; it judges plugin-rule waivers too
+by re-running oxlint. Scope is part of the report — `0 dead` is not `0 dead anywhere`.
 
 ## Wiring the guard
 
 `check-theme` reads `package.json`'s `"basalt"` key (`roots`, `exempt`, `include`, `profile`,
-`severity`, `exemptRules`, …). **`roots` is not optional in practice** — omitted, it falls back to
-`src` relative to cwd, which is zero files for anything under `apps/*/src`; `init` writes a real one
-and `doctor`'s `guard-scan` fails when it resolves to nothing. The scan also reaches each root's
-PARENT for its `index.html` and `public/` tree, because that is where a `theme-color` meta and a
-webmanifest's `background_color` live. Wire it as `oxlint . && basalt-ui check-theme` — what `init`
-seeds as `lint:basalt`.
-
-**When it fires, fix the source** — the right token first. `theme-allow` is for a documented
-exception; a palette-definition file belongs in `exempt`, not behind a comment.
-
-**The guard sees palette, not vocabulary.** A fork written by a token-fluent author uses exactly the
-right tokens, so no palette guard can see it — `basalt/shadow-basalt-export` catches an exact name
-collision and nothing else, and renaming the fork is what a fork's author does anyway. It is a
-tripwire, not coverage. The habit is the control: **check whether basalt already ships the thing
-before building it.**
+`severity`, `exemptRules`). **`roots` is not optional in practice** — omitted, it falls back to
+`src` relative to cwd (zero files under `apps/*/src`); `init` writes a real one. Wire it as
+`oxlint . && basalt-ui check-theme` — what `init` seeds as `lint:basalt`.
+
+**When it fires, fix the source** — the right token first; a palette-definition file belongs in
+`exempt`, not behind a comment. **The guard sees palette, not vocabulary** — a token-fluent fork
+uses exactly the right tokens, so `basalt/shadow-basalt-export` (an exact name collision) is a
+tripwire, not coverage. Check whether basalt already ships the thing before building it.

package/agent/skills/basalt-app/SKILL.md

@@ -36,6 +36,8 @@ own `.oxlintrc.json` costs.
 ```tsx
 // main.tsx — CSS order is load-bearing: every @mantine/*/styles.layer.css, THEN basalt's
 import '@mantine/core/styles.layer.css'
+import '@mantine/notifications/styles.layer.css' // one per MOUNTED battery: notifications, spotlight…
+import '@mantine/spotlight/styles.layer.css'
 import 'basalt-ui/styles.css'
 import { BasaltProvider, createBasaltTheme } from 'basalt-ui'
 import { BasaltOverlays } from 'basalt-ui/commands'

package/agent/templates/CLAUDE-block.md.tpl

@@ -2,32 +2,29 @@
 
 ## basalt-ui (managed — do not hand-edit)
 
-Placed by `bunx basalt-ui init` and refreshed by `basalt-ui sync` after every upgrade
-(`sync --check` gates drift in CI). Framework-owned: edit `DESIGN.md` or your own files instead —
-changes here are overwritten on the next sync.
+Placed by `bunx basalt-ui init`, refreshed by `basalt-ui sync` (`sync --check` gates drift in CI).
+Framework-owned: edit `DESIGN.md` or your own files — this block is overwritten on the next sync.
 
-**Stack:** React 19 + Mantine v9, themed by `basalt-ui` (`BasaltProvider` + `createBasaltTheme`), Bun
-runtime, oxlint + oxfmt (no ESLint/Biome/Prettier), no Tailwind. Color comes from the three-tier
-`--vx-*` token system — read `VX.*` or a series token, never a raw hex/`rgb()`/`hsl()`. Charts are
-visx via `basalt-ui/charts`. `basalt-ui check-theme` plus the `basalt/*` oxlint rules are the teeth.
+**Stack:** React 19 + Mantine v9 themed by `basalt-ui` (`BasaltProvider` + `createBasaltTheme`), Bun,
+oxlint + oxfmt (no ESLint/Biome/Prettier), no Tailwind. Color is the three-tier `--vx-*` token system —
+`VX.*` or a series token, never a raw hex. Charts are visx via `basalt-ui/charts`; `check-theme` + the
+`basalt/*` oxlint rules are the teeth.
 
 **Precedence — the only statement of it.** Highest wins; a lower layer fills gaps and never
 overrides a higher one:
 
 > consumer `DESIGN.md` (app deltas) > the six shipped `basalt-*` rules > the `basalt-*` skills
 
-**All six rules are law** — `basalt-tokens`, `basalt-mantine`, `basalt-charts`, `basalt-state`,
-`basalt-controls`, `basalt-batteries` in `.claude/rules/`, each carrying a generated
-`<!-- basalt:coverage -->` header naming what enforces it and what is only advisory. The skills
-(`/basalt-app`, `/basalt-design`, `/basalt-charts`) are the METHOD that obeys them, never law.
+**All six rules are law** — `basalt-{tokens,mantine,charts,state,controls,batteries}` in
+`.claude/rules/`, each with a generated `<!-- basalt:coverage -->` header naming what enforces it and
+what is only advisory. The skills (`/basalt-app`, `/basalt-design`, `/basalt-charts`) are METHOD, never law.
 
 **Run the LOCAL bin, not `bunx`** — `./node_modules/.bin/basalt-ui`, or a `package.json` script.
 `bunx` does not re-resolve a cached package, so it can answer for a version you upgraded away from;
 `init` is the one legitimate `bunx` invocation, because nothing is installed yet.
 
-**Before guessing an import, read the installed package's machine docs** — `llms.txt` (per-subpath
-import map) and `AGENTS.md`, at the install directory. In a workspace that is under the package that
-depends on basalt, not the repo root; `basalt-ui doctor`'s `basalt-resolves` line prints where.
+**Before guessing an import, read the installed package's `llms.txt` and `AGENTS.md`** — at the
+install directory (in a workspace, under the depending package; `basalt-ui doctor` prints where).
 
 @./DESIGN.md
 
@@ -37,4 +34,7 @@ noise/grain and dramatic motion. Here: the shipped three-font system, depth from
 with a 1px ring, neutral-by-default with the single accent spent only when earned — trend, signal,
 or genuine categorical separation. Restraint **is** the identity.
 
+**Chart-doctrine override.** A global `visx-charts` rule auto-loading on `**/charts/**` is generic
+non-basalt discipline; here `basalt-charts` supersedes it — compose `CartesianChart`.
+
 <!-- basalt:end -->

package/configs/oxlint-plugin.js

@@ -80,16 +80,30 @@ import { fileURLToPath } from 'node:url'
 
 // ── Shared helpers ──────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Guard kinds and plugin rules RETIRED — kept recognized by `KNOWN_RULE_IDS` (below) and the
+ * guard's own `PLUGIN_RULE_IDS` copy so an existing `theme-allow <id>` reads as a dead waiver via
+ * `check-theme --audit-allows`, never as a typo.
+ *
+ * - `unframed-chart` (regex: a `<ChartLegend items={[...]}>` array literal) →
+ *   `basalt/chart-legend-literal`, which also catches the `.map()`-over-a-non-series form the
+ *   regex never could reach.
+ * - `duplicate-notifications-mount` — its only case, `<BasaltNotifications />` mounted beside
+ *   `<BasaltOverlays notifications>`, is unreachable now that `BasaltNotifications` no longer
+ *   exists as a standalone export; the rule had nothing left to fire on.
+ */
+export const RETIRED_RULE_IDS = new Set(['unframed-chart', 'duplicate-notifications-mount'])
+
 /**
  * Rule ids a `theme-allow` may name — this plugin's own rules plus `src/guard`'s kinds. Duplicated
  * by hand for the same reason `majorOf` is: this file loads standalone out of a consumer's
  * node_modules and must not import from the package.
  *
  * Exported, and `oxlint-plugin.test.ts` asserts it is EXACTLY the plugin's own rule ids plus
- * `GUARD_RULES`'s keys. Forgetting an entry here is not a cosmetic omission — an id this set does
- * not know is treated as a typo, so the annotation naming it waives nothing (see
- * {@link parseThemeAllow}); before the fail-closed change it was worse still, silently widening to
- * a blanket waiver.
+ * `GUARD_RULES`'s keys plus `RETIRED_RULE_IDS`. Forgetting an entry here is not a cosmetic
+ * omission — an id this set does not know is treated as a typo, so the annotation naming it waives
+ * nothing (see {@link parseThemeAllow}); before the fail-closed change it was worse still, silently
+ * widening to a blanket waiver.
  */
 export const KNOWN_RULE_IDS = new Set([
   // this plugin
@@ -111,7 +125,6 @@ export const KNOWN_RULE_IDS = new Set([
   'search-literal-link',
   'use-search-from-literal',
   'provider-above-router',
-  'duplicate-notifications-mount',
   'query-dual-import',
   'query-fn-unwrap',
   'deprecated-export',
@@ -121,6 +134,7 @@ export const KNOWN_RULE_IDS = new Set([
   'visx-boundary',
   'visx-tooltip',
   'token-layer-boundary',
+  'no-import-meta-env',
   // These three honour `basalt-agent-allow`, never `theme-allow` — but they are real ids, so an
   // annotation naming one must parse as a (useless) scoped annotation rather than as prose.
   'agent-resume-guard',
@@ -142,7 +156,6 @@ export const KNOWN_RULE_IDS = new Set([
   'inline-display',
   'raw-visx-axis',
   'raw-motion-value',
-  'unframed-chart',
   'chart-missing-aria-label',
   'raw-form-control',
   'sub-16-input-font',
@@ -154,6 +167,9 @@ export const KNOWN_RULE_IDS = new Set([
   'hidden-inline-style',
   'in-body-page-title',
   'raw-selection-control',
+  // Retired guard kinds — no longer in GUARD_RULES, but a `theme-allow` naming one must still
+  // parse as a real (dead) waiver rather than an unknown-id typo. See RETIRED_RULE_IDS above.
+  ...RETIRED_RULE_IDS,
 ])
 
 const ALLOW_RULE_TOKEN = /^(?:basalt\/)?([a-z][a-z0-9-]*)(?=$|[\s,:—–])/
@@ -3338,125 +3354,6 @@ const providerAboveRouter = {
   },
 }
 
-// ── Rule 26 — duplicate-notifications-mount ─────────────────────────────────────────────────────
-
-const DUPLICATE_NOTIFICATIONS_MOUNT_MESSAGE =
-  '<BasaltNotifications /> mounted alongside <BasaltOverlays notifications> — the two double-mount ' +
-  "Mantine's <Notifications>, so a single notify() renders twice. BasaltOverlays already composes " +
-  'the notifications layer; drop the standalone mount, or pass `notifications={false}` to ' +
-  'BasaltOverlays if the standalone one is the mount you want. ' +
-  '(basalt/duplicate-notifications-mount)'
-
-/**
- * The ancestor chain from `node` up to its `Program`, OUTERMOST first — captured during the visit,
- * because `node.parent` is only walkable then, and compared at `Program:exit`. Unlike
- * {@link ancestorTagBindings} it keeps the NODES, which is what makes a nearest-common-ancestor
- * question answerable at all.
- */
-function ancestorChain(node) {
-  const chain = []
-  let current = node
-  for (let depth = 0; current !== null && current !== undefined; depth++) {
-    if (depth > ANCESTRY_MAX_DEPTH) break
-    chain.push(current)
-    if (current.type === 'Program') break
-    current = current.parent
-  }
-  return chain.toReversed()
-}
-
-/**
- * True when two nodes sit in DIFFERENT branches of ONE conditional — `a ? <X/> : <Y/>`, or the two
- * operands of one `&&`/`||`. Exactly one of the pair ever renders, so a double-mount rule firing on
- * them would be reporting a mount that cannot happen.
- *
- * Deliberately the NEAREST common ancestor only, and deliberately expression-level: two separate
- * `cond && <X/>` expressions under one parent are NOT exclusive (both conditions can hold), and an
- * `if`/`return` split across statements is a control-flow question this does not pretend to answer.
- * The runtime guard in `src/commands/overlays-mount.tsx` is the lane that counts real mounts.
- */
-function mutuallyExclusive(chainA, chainB) {
-  let i = 0
-  while (i < chainA.length && i < chainB.length && chainA[i] === chainB[i]) i++
-  const ancestor = chainA[i - 1]
-  const branchA = chainA[i]
-  const branchB = chainB[i]
-  if (ancestor === undefined || branchA === undefined || branchB === undefined) return false
-  const [first, second] =
-    ancestor.type === 'ConditionalExpression'
-      ? [ancestor.consequent, ancestor.alternate]
-      : ancestor.type === 'LogicalExpression'
-        ? [ancestor.left, ancestor.right]
-        : [undefined, undefined]
-  if (first === undefined || second === undefined) return false
-  return (branchA === first && branchB === second) || (branchA === second && branchB === first)
-}
-
-/**
- * `<BasaltOverlays notifications>` and `<BasaltNotifications />` in ONE file — F5, the second
- * `basalt-mantine.md` law with no guard, and the static half of a warning that already exists at
- * runtime (`src/commands/overlays-mount.tsx` warns in dev when both mount).
- *
- * A pair split across the two branches of one conditional is EXEMPT: `a ? <BasaltNotifications/> :
- * <BasaltOverlays/>` is a file with two mounts written and one mount rendered, and reporting it
- * taught a consumer to reach for a waiver over code that was already right.
- *
- * `notifications` DEFAULTS to true on `BasaltOverlays`, so the absence of the attribute counts as
- * enabled and only an explicit `notifications={false}` clears it — the same polarity the component
- * itself reads. Both tags are provenance-gated through {@link collectBasaltImportMap}.
- *
- * Same-FILE only, and deliberately so: the runtime warning is the lane that sees a cross-file
- * double mount, because it counts real mounts rather than JSX. This is the cheap half that catches
- * it before the app runs, which is the whole reason a static twin is worth having.
- */
-// Ships: warn (grace → 1.30.0)
-const duplicateNotificationsMount = {
-  meta: {
-    type: 'suggestion',
-    docs: {
-      description: 'Warn when BasaltOverlays and a standalone BasaltNotifications both mount.',
-    },
-    schema: [],
-  },
-  create(context) {
-    if (isTestFile(context)) return {}
-    const ownTree = isBasaltOwnSource(getFilename(context))
-    const basalt = new Map()
-    const mounts = []
-
-    return {
-      ImportDeclaration(node) {
-        collectBasaltImportMap(node, basalt, ownTree)
-      },
-      JSXOpeningElement(node) {
-        const root = jsxRootName(node.name)
-        if (root === undefined || !basalt.has(root)) return
-        // `notifications` DEFAULTS to true, so only an explicit `={false}` clears the layer.
-        const disabled = (node.attributes ?? []).some(
-          (attr) =>
-            attr.type === 'JSXAttribute' &&
-            attr.name?.name === 'notifications' &&
-            unwrapExpressionContainer(attr.value)?.value === false,
-        )
-        mounts.push({ node, root, disabled, chain: ancestorChain(node) })
-      },
-      'Program:exit'() {
-        const overlays = mounts.filter(
-          ({ root, disabled }) => basalt.get(root) === 'BasaltOverlays' && !disabled,
-        )
-        if (overlays.length === 0) return
-        for (const { node, root, chain } of mounts) {
-          if (basalt.get(root) !== 'BasaltNotifications') continue
-          // Every enabled overlays mount on the other branch of one conditional → nothing to report.
-          if (overlays.every((overlay) => mutuallyExclusive(overlay.chain, chain))) continue
-          if (hasThemeAllow(context, node, 'duplicate-notifications-mount')) continue
-          context.report({ node, message: DUPLICATE_NOTIFICATIONS_MOUNT_MESSAGE })
-        }
-      },
-    }
-  },
-}
-
 // ── Rule 27 — query-dual-import ─────────────────────────────────────────────────────────────────
 
 /** `@tanstack/react-query` and its subpaths — never `@tanstack/react-query-devtools`. */
@@ -3643,36 +3540,8 @@ const queryFnUnwrap = {
  * @type {readonly DeprecatedExport[]}
  */
 export const DEPRECATED_EXPORTS = [
-  {
-    subpath: 'basalt-ui/forms',
-    name: 'field',
-    replacement: 'inputProps',
-    removeIn: '1.29.0',
-    // Not a drop-in: `inputProps` no longer returns `key`, so a rename alone would silently drop
-    // the reconciler key. The nudge stays; the rewrite is `basalt/forms-field-key`'s job.
-    fix: false,
-  },
-  {
-    subpath: 'basalt-ui',
-    name: 'BasaltProvider',
-    prop: 'sseUrl',
-    replacement: 'connectivity={{ sseUrl }}',
-    removeIn: '1.29.0',
-  },
-  {
-    subpath: 'basalt-ui',
-    name: 'BasaltProvider',
-    prop: 'healthUrl',
-    replacement: 'connectivity={{ healthUrl }}',
-    removeIn: '1.29.0',
-  },
-  {
-    subpath: 'basalt-ui',
-    name: 'BasaltProvider',
-    prop: 'healthIntervalMs',
-    replacement: 'connectivity={{ healthIntervalMs }}',
-    removeIn: '1.29.0',
-  },
+  // Empty since 1.29.0: every 1.28.x deprecation was removed on schedule. The next
+  // deprecation adds a row here in the same commit as its @deprecated JSDoc and MIGRATING entry.
 ]
 
 function deprecatedExportMessage(row) {
@@ -3914,6 +3783,51 @@ const formsFieldKey = {
   },
 }
 
+// ── Rule 31 — no-import-meta-env ────────────────────────────────────────────────────────────────
+
+const NO_IMPORT_META_ENV_MESSAGE =
+  'import.meta.env is banned in shipped basalt-ui source — this package is consumed both as a ' +
+  'Vite-bundled dep AND resolved directly by a consumer whose own bundler may define no ' +
+  'import.meta.env at all (basaltViteConfig defines process.env.NODE_ENV precisely so basalt ' +
+  'code never needs it). Use process.env.NODE_ENV instead. (basalt/no-import-meta-env)'
+
+/**
+ * `import.meta.env` — a MemberExpression whose object is the `import.meta` MetaProperty and whose
+ * property is `env`. Repo-local only: a CONSUMER's own app code legitimately uses
+ * `import.meta.env.VITE_*` for its own config, so this must never reach the shipped preset — only
+ * `/.oxlintrc.json` wires it, scoped to `packages/basalt-ui/src/**` the same way the Mantine-free
+ * boundaries above are scoped, rather than through path logic in the rule itself (unlike
+ * `token-layer-boundary`, which every package resolves the plugin from and so has to self-scope).
+ */
+// Ships: repo-local only
+const noImportMetaEnv = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Disallow import.meta.env — basalt-ui source must use process.env.NODE_ENV.',
+    },
+    schema: [],
+  },
+  create(context) {
+    if (isTestFile(context)) return {}
+
+    return {
+      MemberExpression(node) {
+        const object = node.object
+        if (
+          object?.type !== 'MetaProperty' ||
+          object.meta?.name !== 'import' ||
+          object.property?.name !== 'meta'
+        )
+          return
+        if (node.computed || node.property?.name !== 'env') return
+        if (hasThemeAllow(context, node, 'no-import-meta-env')) return
+        context.report({ node, message: NO_IMPORT_META_ENV_MESSAGE })
+      },
+    }
+  },
+}
+
 // ── Grace ledger ────────────────────────────────────────────────────────────────────────────────
 
 /**
@@ -3990,17 +3904,6 @@ export const PLUGIN_RULE_GRACE = {
       'image-gen and the playground is measured — every one of them mounts a router, so the ' +
       'false-positive question has a real sample.',
   },
-  'duplicate-notifications-mount': {
-    since: '1.28.0',
-    promote: '1.30.0',
-    why:
-      'F5 — the static half of a double-mount the runtime already warns about in dev ' +
-      '(`src/commands/overlays-mount.tsx`). Same-file only, so like its sibling it guards a ' +
-      'fraction of the law and cannot claim `error`. It also reads a prop DEFAULT (`notifications` ' +
-      'is true when unwritten), which is the kind of polarity a consumer disagrees with exactly ' +
-      'once before it is worth knowing about — a minor at `warn` is how that disagreement arrives ' +
-      'as feedback rather than as a broken build.',
-  },
   'query-dual-import': {
     since: '1.28.0',
     promote: '1.30.0',
@@ -4097,7 +4000,6 @@ export default {
     'search-literal-link': searchLiteralLink,
     'use-search-from-literal': useSearchFromLiteral,
     'provider-above-router': providerAboveRouter,
-    'duplicate-notifications-mount': duplicateNotificationsMount,
     'query-dual-import': queryDualImport,
     'query-fn-unwrap': queryFnUnwrap,
     'deprecated-export': deprecatedExport,
@@ -4108,5 +4010,6 @@ export default {
     'agent-resume-guard': agentResumeGuard,
     'agent-no-raw-usechat': agentNoRawUseChat,
     'ai-sdk-major': aiSdkMajor,
+    'no-import-meta-env': noImportMetaEnv,
   },
 }