@antelopejs/dms 0.9.2 → 0.9.3

package/skills/dms/SKILL.md

@@ -1,130 +1,60 @@
 ---
 name: dms
-description: Provides the core mental model and router for the AntelopeJS DMS. Use whenever building an app that uses the DMS, working in the @antelopejs/dms package or any DMS module (e.g. the official dms-* modules), building an admin page or dashboard, or when the user mentions the AntelopeJS DMS. Routes to dms-project, dms-module, dms-dev, and the sibling dms-pages / dms-auth skills.
+description: Gives the mental model of the AntelopeJS DMS (backend-described pages and blocks rendered by a shared frontend) and routes to the right DMS skill. Use when the user mentions the AntelopeJS DMS, when building an app, admin page or dashboard on it, or when working in @antelopejs/dms or any dms-* module. Routes to dms-best-practices, dms-project, dms-pages, dms-auth, dms-module and dms-frontend.
+icon: i-ph-squares-four
 category: overview
 tags: [dms, architecture, mental-model, router]
 ---
 
 # AntelopeJS DMS
 
-The AntelopeJS DMS is a **backend-driven admin framework** built *on* AntelopeJS. Its own docs call
-it the **DMS** ("dashboard management system") — same product; historical module names keep the
-`dms-` prefix. It ships as the **`@antelopejs/dms`** package your project depends on — the
-package these skills ship with. You add an admin screen by writing backend TypeScript — a page and
-its components — and a shared Vue 3 + Inertia SSR frontend renders that description; you almost never write Vue.
-For the framework underneath (the core, `ajs` CLI, interfaces as versioned contracts,
-`ImplementInterface`), use the **antelopejs** plugin — the DMS assumes its mechanics.
+The AntelopeJS DMS ("dashboard management system") is a **backend-driven admin framework** built
+*on* AntelopeJS. It ships as **`@antelopejs/dms`**, the package these skills ship with. You add an
+admin screen by writing backend TypeScript — a page and its blocks — and a shared Vue 3 + Inertia SSR
+frontend renders that description; you almost never write Vue. For the framework underneath (the
+core, the `ajs` CLI, interfaces as versioned contracts, `ImplementInterface`), use the **antelopejs**
+skill (shipped with `@antelopejs/core`).
 
 ## The model in one screen
 
-- **Two coupled packages.** **`@antelopejs/dms`** is the backend: an AntelopeJS module
-  providing the page system, component builders, DataTypes, auth, and platform services,
-  auto-registering its **base Vue dashboard frontend** (`frontend-vue/`). **`@antelopejs/dms-frontend`**
-  is the frontend loader (the `ajs dms` CLI): an Inertia SSR app whose single catch-all
-  route renders the component tree the backend describes. In dev: two processes, `ajs project dev -w`
-  (legacy alias: `ajs project run`) and `ajs dms dev` (auto-discovers a backend; `-b <url>` optional) —
-  see **Running**.
-- **Two ways to build — usually a project.** Most commonly you build a **project**: your own app
-  loading the DMS via `antelope.config.ts`, registering *its own* pages and data — **dms-project**.
-  Rarer: a **distributable module** (like `dms-database`) — **dms-module**. Same APIs; only packaging.
-- **Pages are classes; UI is data.** A page extends `PageController(id, opts)` decorated with
-  `@RegisterPage()`. Its **static fields are components** — `Form`, `TableView`, `Chart*`,
-  `Grid`, `KpiCard`, … — fluent builders producing a **serializable description**, not live UI: the
-  frontend renders it. **Components fetch their own data** via URLs (`fetchUrl`, `submitUrl`, …) —
-  routes often declared `@Get`/`@Post` on the same page class, served under `/dms/pages<slug>`
-  (`pageRoutePath(slug, route)`); the backend stays the source of truth.
-  A URL names the record of its page with `{{params.id}}` / `{{query.X}}` (filled from the page URL, percent-encoded;
-  nothing is fetched while one is unresolved) — every token is `{{<scope>.<key>}}`: `params`, `query`, `row` (an
-  action's row), `response` (a form's redirect), and the same page tokens work in every URL and link option, and `.watch(FormEvents.SUBMIT_SUCCESS,
-  BlockFunctions.REFRESH_PAGE)` makes the page's data blocks (table views included) re-fetch after a form saves;
-  `periodScope` binds a card, chart, list block, `Meter` or `TableView.fromSource` to a `PeriodSelector`
-  (which keeps its period in the page URL, `?<id>.period=`), and
-  `realtimeTopic` re-fetches a chart, list block, `Meter`, `Tab` badges or `TableView` on each `PublishMessage`.
-  A monitoring page that must not refetch on every event declares `live: { maxRate }` in its page options
-  (`slowRateAfter: { period: "7d", maxRate: 60 }` for long periods, `rememberKey: "<module>"` to share the
-  choice between pages; `maxRate` is also the polling interval while the stream is down) and places a
-  `LiveToggle()` (Live / Pause, L key; `variant: "pill"`, `missedLabel` for "N new requests").
-  `liveHold: true` keeps a table's rows while paused; `liveHold: { whileRowOpen, whileScrolled,
-  whileSearching, whileSorted }` also holds the table alone, its strip saying why ("Table on hold ·
-  search active"); `liveHold.missedLabel` words its "N new", and paused, it adds the
-  `setMissedDetail()` breakdown ("12 new requests · 2 in 5xx"). Paused, an event counts as its `payload.ids` rows or its `payload.count`, so a
-  module may batch publishes with `{ count }`. A hidden tab and `?live=0` pause the page too.
-  A custom component follows that state with `usePageLive()`, holds the page with `hold(reason)` /
-  `release()` and adds a breakdown with `setMissedDetail()`; a custom component that reads its own data
-  on a topic calls `usePageLiveRefresh(refresh, { realtimeTopic, idleRefresh })`, gated exactly like a
-  built-in block (never a throttle of its own); `refreshPageBlocks()` (user actions) always
-  reads, `refreshLivePageBlocks()` (timers, feeds) is held while paused.
-  A custom component on a record page names its record at the end of the breadcrumb with
-  `usePageRecordLabel().setLabel(useDmsRoute().path, label)` (auto-imported; never the `build/` path).
-  A custom component formats through `useRegionalFormat()` (`formatNumber` & co. return `string` for a
-  number); `useRegionalFormat({ locale: "format" })` writes in `formatLocale`, the locale of the DMS's
-  texts (`en` → `en-GB`) — never a hand-rolled `en` → `en-GB` mapping.
-  A status the backend computes (health, outage) is a `Banner({ fetchUrl })`: the route answers
-  a `BannerContent` (its buttons may run `api` / modal / quick-action targets with `confirm`)
-  or `null` for no banner — the block then draws nothing.
-  A text naming values (an amount, a date, a count) is sent as a `ComposedText` —
-  `{ key, params: { amount: { type: "money", value: 92200, currency: "EUR" } } }` — that the
-  browser writes in the reader's language: StatGroup / KeyValueList / Banner / NavCardGrid /
-  ActivityFeed / Meter / TopListCard item texts (and ActivityFeed `params`, typed `count` for
-  plurals) and layout
-  banners (`RegisterLayoutBanner({ resolve })` → `{ text, actions }`) take it; never format text server-side.
-  A table cell's secondary line is a row field holding one (or `{ text, tone }`), named by
-  `StatusPillDisplay({ subField })`, `IdentityDisplay({ subtitleField })` or
-  `TwoLineDisplay({ subField })`; `IdentityDisplay({ emptyLabel, emptyIcon })` draws an empty row,
-  and `IdentityDisplay({ iconField })` reads each row's tile icon from a row field.
-  `StatusPillDisplay({ toneField })` reads the pill's tone from a row field (an HTTP status class);
-  `DurationDisplay({ toneField })` and `TextDisplay({ toneField })` colour their text with it (a slow
-  duration, an error message), and `DurationDisplay({ format: "ms" })` writes "2,149 ms" on every row;
-  and a `PillsDisplay` item may be `{ label, tone?, variant: "soft" | "outline" }`, styled per row.
-  A `StatGroup` detail and a `NavCardGrid` card title take up to two lines before their ellipsis.
-  An `ActivityFeed` whose entries must be read whole sets `wrap: true` (no ellipsis; leave `fillHeight`
-  off so the card grows) and `visibleItems: N` for a "Show N more" fold.
-  A unit after a number field is `NumberType({ suffix: "$…days" })`, a character counter on a
-  text field `StringType({ maxLength, showCount: true })` — no custom `inputComponent` for either.
-  A `TableView` over a shared controller hides a column on one page with
-  `columns: { hidden: ["workspace"] }` (as `isVisible: false`, for that table view only) — no view
-  just to hide it.
-  A long sectioned `Form` groups its navigation with `FormSection.navGroup` ("Billing", "Legal"),
-  in the side list and in the `sectionNav: "jump"` chips alike (a form whose side column holds a preview).
-  A module's own `inputComponent` submits its form, adds a validator and focuses a field with
-  `useEnclosingForm()` (never `closest("form")` / `requestSubmit()`), and a link ending in `#<fieldId>`
-  opens the form on that field, focused. `DmsInputNumber` emits `adjust` (`{ typed, value, reason:
-  "min" | "max" | "step" }`) when it keeps another value than the one typed, and redraws the kept
-  value itself: a note "1020 → 1,000" listens to it — never a forced remount (`:key`).
-  `TopListCard({ actions })` puts link buttons in its head ("Catalogue →"), and `Tab({ fit: true })`
-  keeps a pill tab list to its tabs' width; with `persistState` the URL names the open tab by its slot
-  (`?tab=tester`, an index still read), and a tab `badge` takes a `$` key or a `ComposedText`. A `ChartCard` plotting several series names them with
-  `showSeriesLegend: true` (placed by the chart's `legendPosition: "top" | "bottom"`) — never a raw
-  Apex `legend` in `rawOptions`.
-  A custom component brings a block of its page into view with `scrollToBlock("tabs.statistics")`
-  (the block's key path; `false` when it is not on screen) — never a DOM query of its own.
-  Code in a custom component is a `DmsCodeSnippet` (`language`, `title`, `maxLines` or a CSS
-  `maxHeight`, `wrap: true | "anywhere"`; without title and language its copy button floats in the
-  corner) — never a `<pre>` and copy button of the module's own.
-  A `KeyValueList` row takes `copy: true` (a copy button for its shown value) or `copyValue`
-  (the text to copy instead, e.g. a full URL behind a short label).
-  A table ordered by hand (`reorder: { field }`) moves its rows on the grid and its cards on
-  the `cards` display alike; a `card.component` receives a `reorder` prop and `v-bind`s
-  `reorder.handle` on a button — no custom display just to drag cards.
-- **It's interfaces all the way down.** Everything you consume from the DMS is an AntelopeJS
-  interface imported as an `@antelopejs/interface-dms/...` subpath (see the imports below);
-  a distributable module exposes its own from a companion `@antelopejs/interface-<name>` package listed in `antelopeJs.implements`.
+- **Two coupled packages.** **`@antelopejs/dms`** is the backend: the page system, the block
+  builders, DataTypes, auth and platform services, plus its base Vue dashboard (`frontend-vue/`).
+  **`@antelopejs/dms-frontend`** is the frontend loader (`ajs dms`): an Inertia SSR app whose
+  catch-all route renders what the backend describes. In dev: `ajs project dev -w` and `ajs dms dev`
+  (see **dms-project**).
+- **Usually a project.** Most work is a **project** loading the DMS via `antelope.config.ts` and
+  registering its own pages (**dms-project**). Rarer: a **distributable module** like `dms-database`
+  (**dms-module**). Same APIs; only the packaging differs.
+- **Pages are classes; UI is blocks.** A page extends `PageController(id, opts)` decorated with
+  `@RegisterPage()`. Its **static fields are blocks** — `Form`, `TableView`, `Grid`, `KpiCard`,
+  `ChartCard`, … — fluent builders producing a serializable description; every block type is
+  registered in the block catalog (`ListBlockTypes()`). Each field and `.child()` is a permission.
+- **Blocks fetch their own data** through URLs (`fetchUrl`, `submitUrl`), usually routes declared
+  with `@Get` / `@Post` on the same page class, served under `/dms/pages<slug>` (name them with
+  `pageRoutePath(slug, route)`); a plain `Controller` the frontend calls sits under
+  `/api/<module>/`. A URL names the page's record with `{{params.id}}` /
+  `{{query.X}}`; `periodScope` binds a block to a `PeriodSelector`; `realtimeTopic` re-fetches on a
+  `PublishMessage`. Texts are `$` i18n keys or `ComposedText`, never formatted server-side.
+- **It's interfaces all the way down.** Everything you consume is imported from an
+  `@antelopejs/interface-dms/...` subpath; a distributable module exposes its own API from a companion
+  `@antelopejs/interface-<name>` package listed in `antelopeJs.implements`.
 
 ```ts
 import { PageController, RegisterPage, pagesCategory } from "@antelopejs/interface-dms/page";
 import { Form } from "@antelopejs/interface-dms/base/form";
 import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types/default-types";
+
 @RegisterPage()
 export class SubmitRecipePage extends PageController("submit-recipe", {
-  displayName: "Submit Recipe",
+  displayName: "$cookbook.submit.title",
   icon: "i-ph-cooking-pot",
-  category: pagesCategory, // attach under the dashboard's Pages section (the usual anchor)
+  category: pagesCategory,
 }) {
   static form = Form({
-    title: "Submit a Recipe",
+    title: "$cookbook.submit.form_title",
     fields: [
-      { id: "chef",  label: "Chef Name", type: new DefaultDataTypes.StringType({ maxLength: 100 }) },
-      { id: "email", label: "Email",     type: new DefaultDataTypes.EmailType() },
+      { id: "chef", label: "$cookbook.submit.chef", type: new DefaultDataTypes.StringType({ maxLength: 100 }) },
+      { id: "email", label: "$cookbook.submit.email", type: new DefaultDataTypes.EmailType() },
     ],
   });
 }
@@ -134,40 +64,36 @@ export class SubmitRecipePage extends PageController("submit-recipe", {
 
 | Task | Skill |
 | --- | --- |
-| **Set up a project that uses the DMS** — `antelope.config.ts`, lifecycle, `AddFrontendModule`, running | **dms-project** |
-| Add an admin screen — pages, categories, components, DataTypes, routes that feed them | **dms-pages** |
-| Protect a page or route, define and check permissions, users/roles/tenants | **dms-auth** |
-| Run, stop, or restart the dev servers to test a change live | **dms-dev** |
-| Package a *distributable* module — `antelopeJs` manifest, `RegisterModule` | **dms-module** |
-
-The deep page/component and auth guidance ships **in this same package**: the sibling **dms-pages**
-and **dms-auth** skills (under `skills/`, declared via `antelopeJs.skills`), carrying the concrete
-package names and current API surface — route that work there. They are also auto-synced into
-consumer projects' `.claude/skills/` by the **antelopejs** plugin's hooks and loaded by the dms-ai
-chatbox.
-
-## Docs & exact interface surfaces (read for depth)
-
-Long-form reference docs live in this package's `docs/` directory (shipped with the package; also
-at the repo root), in seven numbered sections — the last, `docs/07.interfaces/`, is the contract
-reference for `@antelopejs/interface-dms` domain by domain. DataTypes, component builder options, and auth
-decorators are **versioned interface contracts** — look them up rather than hand-recalling; treat
-skill examples as patterns, not gospel. See [REFERENCE.md](REFERENCE.md) for the docs map and the
-resolver commands that fetch an interface's exact surface.
-
-## Running the DMS (use the dms-dev skill — don't reinvent it)
-
-Backend and frontend are **coupled**: the `@antelopejs/dms-frontend` loader materializes layers into `~/.antelopejs/dms-frontend/` and
-serves from those copies. Whenever anything looks stale (`RegisterModule "already registered"`, a
-layer edit not showing, phantom UI state), the documented fix is a **full restart, backend first,
-then frontend** — restart before verifying a change rather than trusting hot reload. The sibling
-**dms-dev** skill owns this dance — use its bundled `scripts/dms-dev.sh` (invocation documented there).
+| **Before building or changing any page**, before writing a `CustomComponent`, or when the user hands you a design, mockup or screenshot | **dms-best-practices** |
+| Set up a project that uses the DMS — `antelope.config.ts`, lifecycle, `AddFrontendModule` — and run, stop or restart its dev servers to test a change live | **dms-project** |
+| Add a screen — pages, categories, blocks, DataTypes, the routes that feed them | **dms-pages** |
+| Protect a page or route, define and check permissions, users / roles / tenants | **dms-auth** |
+| Package a *distributable* module — `antelopeJs` manifest, `RegisterModule`, its own skill | **dms-module** |
+| The `ajs dms` CLI, a frontend module's `dms.server.ts` / `dms.frontend.build.ts`, building and deploying the frontend server (ships with `@antelopejs/dms-frontend`) | **dms-frontend** |
+
+These skills ship in this package (`skills/`, declared via `antelopeJs.skills`). The **antelopejs**
+plugin links them into a project's `.claude/skills/`, and the dms-ai assistant loads them for every
+loaded module.
+
+## Docs & exact interface surfaces
+
+The long-form docs live in this package's `docs/` directory, and the exact surface of
+`@antelopejs/interface-dms` is a versioned contract: look it up rather than recall it, and treat skill
+examples as patterns. [REFERENCE.md](REFERENCE.md) maps the docs and gives the resolver commands.
+
+## Running the DMS
+
+Backend and frontend are **coupled**: the loader materializes layers into
+`~/.antelopejs/dms-frontend/` and serves those copies. When anything looks stale
+(`RegisterModule "already registered"`, a layer edit not showing), the fix is a **full restart,
+backend first, then frontend** — the **dms-project** skill and its `scripts/dms-dev.sh` own that.
 
 ## Conventions (enforced across all DMS repos)
 
-The general rules live in this package's `AGENTS.md` (**pnpm only**, no `switch`/`case`, named interfaces, TSDoc-only comments, …) — match the surrounding code. Four DMS-specific rules:
+The general rules live in the repo's `AGENTS.md` (**pnpm only**, no `switch` / `case`, named
+interfaces, TSDoc-only comments, …). Four DMS-specific rules:
 
-- **Table rows use `_id`, not `id`.** Database records carry `_id`; don't alias to `id`.
-- **Consumer-facing APIs must live in the interface package** — never a new runtime `package.json` export subpath.
-- **`/** @internal */` marks the provider-side `internal` namespaces of interface files** (a repo-wide convention) — never strip it.
-- **`pnpm build` only typechecks `src/`.** Frontend errors require the frontend lint/tests or a live verification (dms-dev); a clean root build does not mean the page renders.
+- **Table rows use `_id`, not `id`.** Database records carry `_id`; never alias it to `id`.
+- **Consumer-facing APIs live in the interface package** — never a new runtime `package.json` export subpath.
+- **`/** @internal */` marks the provider-side `internal` namespaces** of interface files — never strip it.
+- **`pnpm build` only typechecks `src/`.** Frontend errors need the frontend lint / tests or a live check (**dms-project**).

package/skills/dms-auth/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: dms-auth
 description: Wires authentication and RBAC permissions on the AntelopeJS DMS. Use when protecting a route with @AuthUser / @AuthUserWithPermission, gating a page via its PageController options, registering permissions, or working with the user, role, and tenant models under @antelopejs/interface-dms/auth and @antelopejs/interface-dms.
+icon: i-ph-lock-key
 category: security
 tags: [auth, permissions, rbac, users, roles, tenants]
 ---
@@ -61,7 +62,9 @@ checks; only add finer ones (ownership, a specific permission).
 Permissions are **hierarchical and auto-derived** from the page → component → action tree.
 A component's permission id is the page's **`fullId`** (category chain + page id) followed by
 the component key, then the action (e.g. `pages.recipes.submit-recipe.form.delete`), registered
-automatically when the page loads. Users hold roles; roles hold granted permission ids; the
+automatically when the page loads. The roles editor titles each one with the component's metadata: DMS blocks set
+their own, and a `CustomComponent` needs `.meta({ name, description, icon })` with `$` keys (see
+**dms-best-practices**). Users hold roles; roles hold granted permission ids; the
 platform **owner** holds everything. **Module pages are special**: prefixed
 `modules.<moduleId>.…`, never grantable in the Roles tree, owner-only regardless of grants.
 

package/skills/dms-best-practices/REFERENCE.md

@@ -0,0 +1,93 @@
+# dms-best-practices — reference
+
+Material for [SKILL.md](SKILL.md): mapping design elements to DMS blocks, the `PreviewBlocks` call with a sketch variant, the safe-mode question, and the text fallback. The block catalog is the source of truth: `ListBlockTypes()` from `@antelopejs/interface-dms/base/block-types`, or `docs/04.components/` (one page per block).
+
+## Design element → DMS block
+
+| In the design | DMS block | Usual visible differences |
+| ------------- | --------- | ------------------------- |
+| Big number with a trend arrow | `KpiCard` (`variant: "stat"` for the compact look) | Sparkline is a line, not bars |
+| Several small figures in a strip | `StatGroup` (`layout: "joined"` or `"cards"`) | One shared card vs separate tiles |
+| Chart with a headline value | `ChartCard` + a chart (`ChartArea`, `ChartLine`, `ChartColumn`…) | Legend placement, comparison style |
+| Bare chart | `ChartLine` / `ChartArea` / `ChartBar` / `ChartColumn` / `ChartDonut` / `ChartPie` / `ChartRadialBar` / `ChartHeatmap` / `ChartScatter` / `ChartRadar` / `ChartMixed` / `ChartRangeArea` / `ChartCandlestick` | Axis labels, tooltip look |
+| Ranked list, leaderboard | `TopListCard` | Bar position, rank badge style |
+| Date range picker | `PeriodSelector` (`variant: "segmented"` for pills) | Preset labels |
+| Live / pause switch | `LiveToggle` | Pill vs segmented |
+| Table, list with actions | `TableView` over a DataController (`displays` for cards / kanban) | Column widths, row height (`density`) |
+| Detail facts of a record | `KeyValueList` | Value alignment |
+| Recent events, audit log | `ActivityFeed` | Day separators vs relative times |
+| Usage bar, quota | `Meter` | Bar thickness (`size`) |
+| Notice, alert strip | `Banner` | Wash vs flat background |
+| Empty / first-run screen | `EmptyState` (or `Guard` around blocks) | Illustration vs icon well |
+| Links to sub-pages as cards | `NavCardGrid` | Card height |
+| Code snippet | `CodeBlock` | Theme of the highlighting |
+| Panel with a title and actions | `Card` | Head layout |
+| Settings card with rows | `Section` + `FieldRow` | Label column width (`layout`) |
+| Form, settings form | `Form` / `ResourceForm` | Field layout (`fieldsOrientation`, sections) |
+| Tabs | `Tab` (`variant: "pill" \| "link"`) | Tab style |
+| Columns / rows of panels | `Grid` + `GridRow`, `HStack` / `VStack` / `Spacer` | Exact gutters |
+
+Nothing matches — a canvas, a map, a bespoke visualization — → a custom block, under the rules of SKILL.md.
+
+## `PreviewBlocks` (dms-ai only)
+
+`PreviewBlocks({ title, description?, label?, tree?, sketch?, reference?, variants?: [{ label, tree?, sketch? }] })` — non-blocking; it shows an attachment card in the chat, and a click opens a modal rendering the real blocks next to the reference image, one tab for the main view (named by `label`, default "Proposed") and one per variant. Every view needs a `tree`, a `sketch` or both (both are drawn side by side). `reference` is `{ attachmentId?, url?, caption? }`: `attachmentId` is the file name of an image the user attached in the conversation, or `"latest"`; `url` is a same-origin path. `tree` is one `PreviewNode` or a list: `{ type, options?, children? }`, children also taking `id`, `slot` and `colSpan`. Use `static*` options (`staticValue`, `staticDataset`, `staticItems`, `items`) so the preview shows data without a route; URL options must be relative paths. `TableView` and `ResourceForm` need a backend class and render as a notice — describe them in the question instead.
+
+A variant holds a `tree` (the DMS block with other options), a `sketch` (`{ html, css?, caption?, height? }`: static HTML and CSS standing for the custom block you would build, `height` in px from 80 to 1200, default 320), or both, so the user compares it with the DMS option before any Vue exists. Keep a sketch to the element alone: static markup with no script, event handler, `@import` or external URL (the tool refuses them with `invalid_sketch`), images as `data:` URLs, and the `--sketch-*` theme variables the tool describes for colors, so it follows light and dark mode.
+
+```ts
+PreviewBlocks({
+  title: "Revenue tile",
+  description: "Your tile as a DMS KPI card, adjusted, and as a custom block",
+  label: "DMS KpiCard",
+  tree: { type: "KpiCard", options: { title: "Revenue", valueFormat: "currency", currencyCode: "EUR",
+    staticValue: 48200, staticDelta: 12.4, showDelta: true, showSparkline: true,
+    staticSparkline: [31, 34, 33, 38, 41, 39, 44, 48] } },
+  reference: { attachmentId: "latest", caption: "Your design" },
+  variants: [
+    { label: "DMS, compact", tree: { type: "KpiCard", options: { title: "Revenue", variant: "stat", staticValue: 48200 } } },
+    { label: "Custom sketch", sketch: {
+      html: "<div class='tile'><span>Revenue</span><strong>€48,200</strong><div class='bars'><i style='height:40%'></i><i style='height:70%'></i><i style='height:100%'></i></div></div>",
+      css: ".tile{padding:16px;border:1px solid;border-radius:8px}.bars{display:flex;gap:4px;height:32px;align-items:end}.bars i{width:8px;background:currentColor}",
+      caption: "Bars under the figure, as in your design" } },
+  ],
+});
+// then
+AskUser({ questions: [{
+  header: "Revenue tile",
+  question: "Keep the DMS KPI card, adjust it, or build a custom block?",
+  options: [
+    { label: "Keep the DMS block", description: "KpiCard as previewed; themed, permissioned, editable in the builder" },
+    { label: "Adjust it through its options", description: "Same block, e.g. the compact variant; tell me what to change" },
+    { label: "Build a custom block", description: "A Vue component matching the sketch, declared with .meta(); the rest stays blocks" },
+  ],
+}] });
+```
+
+## Safe mode: a custom block is out of reach
+
+The Builder tools cannot write Vue. Show the closest composition with `PreviewBlocks`, then:
+
+```ts
+AskUser({ questions: [{
+  header: "Seat map",
+  question: "Safe mode cannot build a custom block. Use the closest DMS composition, or switch to Code mode for this block only?",
+  options: [
+    { label: "Use the DMS composition", description: "A Grid of KpiCard per zone, as previewed" },
+    { label: "Switch to Code mode for this block", description: "Only the seat map becomes custom, with .meta(); then back to safe mode" },
+  ],
+}] });
+```
+
+## Text fallback (no `PreviewBlocks`)
+
+One table per batch of components, then one closed question per row:
+
+| Your design | DMS block | Visible difference |
+| ----------- | --------- | ------------------ |
+| Revenue tile with bars under the figure | `KpiCard` with a sparkline | A line instead of bars |
+| Orders table with avatars in the first column | `TableView` with `IdentityDisplay` | None beyond spacing — no question |
+
+> Revenue tile: keep the DMS block, adjust it through its options, or build a custom block?
+
+When the custom option is hard to picture, add its sketch as a short markup snippet under the table (a few lines of HTML, no styling detail). Leave rows whose only difference is theme-level (colors, spacing, fonts) out of the questions.

package/skills/dms-best-practices/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: dms-best-practices
+description: Enforces the rules for building AntelopeJS DMS pages — every page described backend-side as DMS blocks, custom code only for the missing block, `.meta()` on every custom block — decides when to leave DMS blocks and proposes that deviation to the user, and runs the design-fidelity protocol. Use when creating or changing any DMS page, dashboard or screen, before writing a CustomComponent or Vue for one, or when the user provides a design, mockup, Figma frame or screenshot to reproduce.
+icon: i-ph-seal-check
+category: dashboard
+tags: [pages, blocks, custom-component, permissions, design, mockup]
+---
+
+# DMS best practices
+
+Three rules hold for every page, a path runs before any custom block, and a protocol runs whenever a design is involved. They keep each part of a screen a permission of its own, editable by the page builder, and driven by the theme. **dms-pages** has the APIs; this skill decides what to build.
+
+## The rules
+
+1. **A page is always blocks.** Describe every page on the backend as a tree of DMS blocks — `PeriodSelector`, `Grid` / `GridRow`, `KpiCard`, `TableView`, `Form`, … Each static field and each `.child()` is a line in the roles editor, a `.watch()` target, a `periodScope` subscriber and a node the builder can move. One block that draws the whole screen loses all of that.
+2. **Custom = the missing block only.** When a part has no DMS equivalent, build **that block** as a `CustomComponent` and keep everything around it — toolbar, filters, stats, tables — as DMS blocks on the backend.
+3. **Every custom block carries `.meta()`.** `.meta({ name, description, icon })` in its backend declaration, `name` and `description` as `$` i18n keys added to every locale file. Without it the roles editor shows the raw component name. Every other text (page names, titles, labels) is a `$` key too.
+
+```ts
+// Good — blocks around the one custom block, which carries its metadata
+static period = PeriodSelector({ id: "api" });
+static kpis = Grid().child("row", GridRow()
+  .child("calls", KpiCard({ title: "$api.routes.calls", fetchUrl: "/api/routes/calls", periodScope: "api" })));
+static graph = CustomComponent("ApiRouteGraph")
+  .options({ fetchUrl: "/api/routes/graph", periodScope: "api" })
+  .meta({ name: "$api.routes.graph.name", description: "$api.routes.graph.description", icon: "i-ph-graph" });
+
+// Bad — one component draws the period picker, the KPIs and the graph; no .meta()
+static screen = CustomComponent("ApiRoutesScreen");
+```
+
+`CustomComponent` comes from `@antelopejs/interface-dms/base/custom` (not the `base` barrel); `.meta()` takes `Partial<ComponentMetadata>` (`name`, `description?`, `icon?`). Every DMS factory sets its own metadata; a custom block is the one place you must.
+
+## When to leave DMS blocks
+
+A custom block is a deviation, and you **propose** it: the user decides, after the path below. It is worth proposing only when one of these holds:
+
+| Leave DMS blocks when | Stay on DMS blocks when |
+| --------------------- | ----------------------- |
+| No block covers the need, even through its options or a composition of blocks | The difference is spacing, color, radius, font or a minor layout the theme or the block's options handle |
+| The interaction model differs: a drag-and-drop canvas, real-time collaborative editing | The DMS block only "looks slightly different" from the mockup |
+| The user asked for pixel perfect on **this** element | Another element of the page is custom: a custom block never pulls its neighbours along |
+| A measured constraint (performance, data volume) the block cannot meet | The constraint is a guess, not a measurement |
+
+## Before any custom block
+
+Run this path before writing a `CustomComponent` or its Vue, one element at a time:
+
+1. **Search the catalog.** In dms-ai with the Builder loaded, `BuilderCatalog`; otherwise the block catalog of the DMS (`GET /api/block-preview/types` on a running instance, or `docs-data/blocks.json` of AntelopeJS/dms); otherwise the exports of `@antelopejs/interface-dms/base`. Try the block's options first, then a composition of blocks (`Card` + `KeyValueList`, `ChartCard` + a chart, `Grid` of `KpiCard`).
+2. **Show the comparison.** In dms-ai, call `PreviewBlocks` with the closest DMS option as `tree`, the user's mockup as `reference`, and a **sketch variant** of the custom block (`label` naming the DMS tab, and `variants: [{ label, tree }, { label, sketch: { html, css?, caption?, height? } }]`). Elsewhere, write the text table of [REFERENCE.md](REFERENCE.md).
+3. **Ask.** One closed question (`AskUser` in dms-ai) with three options: *Keep the DMS block* / *Adjust it through its options* / *Build a custom block*.
+4. **Build.** On *Adjust*, change the block's options and preview again. Only on *Build a custom block*, build that block alone, under the rules above, with `.meta()`; the rest of the page stays blocks.
+
+In **safe mode** (dms-ai, Builder tools only), step 4 is impossible: say so, offer the closest DMS composition, and ask with `AskUser` whether to switch to Code mode for that one block.
+
+The path is done when the user has answered for the element. [REFERENCE.md](REFERENCE.md) has worked calls and the fallback table.
+
+## Design-fidelity protocol
+
+Run it whenever the user hands you a design, mockup or screenshot.
+
+1. **Frame once.** Before building, ask **one** question (`AskUser` when available, else a closed question in chat):
+   - *Pixel perfect* — reproduce the design, custom blocks allowed where nothing matches;
+   - *DMS equivalents* — map every component to its closest DMS block silently; an element no block or composition covers still goes through the path;
+   - *Component by component* — **recommended**: decide each visible difference together.
+2. **Map** every component of the design to its closest DMS block ([REFERENCE.md](REFERENCE.md) has the mapping table). Differences the right-hand column of the grid lists never trigger a question.
+3. **Decide.** *Component by component*: run [the path](#before-any-custom-block) for each visible difference (layout, a missing element, another chart kind), batching several components in one preview and one question. *Pixel perfect* answers step 3 of the path for every element, so skip that question but still run step 1: only the parts no block or composition matches become custom.
+4. **Build** under the rules above.
+
+The protocol is done when every visibly different component has an answer and every custom block in the page carries `.meta()`.
+
+## Checklist before handing back
+
+- Every page field and child is a DMS block, except custom blocks the user chose through the path.
+- Every `CustomComponent` has `.meta({ name, description, icon })` with `$` keys present in every locale file.
+- Data comes from routes (`fetchUrl`) rather than options computed at registration; a custom block reads its route with `useApiData` (server-rendered, refreshed with the page) and writes with `$authFetch`.
+- Verified live with **dms-project** (the build only typechecks `src/`).

package/skills/dms-module/REFERENCE.md

@@ -21,6 +21,7 @@ first-party modules follow `dms-<name>` purely for discoverability.
         implementations/<name>/index.ts  # implementation of the module's own interface
       frontend-vue/                 # Vue module: dms.frontend.ts, app/, i18n/locales/,
                                     # package.json (engines: the loader releases it supports)
+      skills/<name>/SKILL.md        # when and how agents use the module (antelopeJs.skills)
       package.json / tsconfig.json
     interface-<name>/               # the module's OWN interface, its own published package
       src/index.ts                  # (rare — many modules ship none)
@@ -34,7 +35,8 @@ first-party modules follow `dms-<name>` purely for discoverability.
   "main": "dist/index.js", "types": "dist/index.d.ts",
   "antelopeJs": {
     "baseUrl": "dist",
-    "implements": ["<your-interface-package>"]   // the interface THIS module provides (omit/[] if none)
+    "implements": ["<your-interface-package>"],  // the interface THIS module provides (omit/[] if none)
+    "skills": ["./skills"]                         // skills/<name>/SKILL.md, synced to agents
   },
   "exports": {
     ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
@@ -50,7 +52,7 @@ subpath of the runtime package — it goes in the companion interface package, w
 ## Defining the module's own interface
 
 Interface authoring (`InterfaceFunction`, `RegisteringProxy`, implementation shape) is pure
-AntelopeJS — see the **antelopejs** plugin's author/consume skills. The DMS-specific parts:
+AntelopeJS — see the **ajs-author-interface** and **ajs-consume-interface** skills. The DMS-specific parts:
 
 - **Define** in a companion package, `packages/interface-<name>/src/`, **implement** at
   `src/implementations/<name>/index.ts` in the module, **wire** with `ImplementInterface` in
@@ -75,12 +77,12 @@ AntelopeJS — see the **antelopejs** plugin's author/consume skills. The DMS-sp
    own interface published as a standalone `interface-*` package → `dms-automation`.
 3. **Scaffold the layout above**: `src/index.ts`, `src/pages/`, `src/routes/` (if it serves data),
    `packages/interface-<name>/` + `src/implementations/<name>/` (only if it exposes one),
-   `frontend-vue/` (components registered from the root `dms.frontend.ts`), and the manifest
-   (`antelopeJs` block, plus the interface package's `exports`).
+   `frontend-vue/` (components registered from the root `dms.frontend.ts`), `skills/<name>/SKILL.md`,
+   and the manifest (`antelopeJs` block with `skills`, plus the interface package's `exports`).
 4. **Wire the basics**: `RegisterModule({ id, title, icon, … })`, one `@RegisterPage()` page,
    the `AddFrontendModule` call. Add the `$dms_<name>.*` keys to **every** locale file under
    `frontend-vue/i18n/locales/`.
 5. **Load and verify**: add the module to a consumer project's `antelope.config.ts` (the
    backend's `playground` is the reference consumer) as a `package`/`git`/local-path module,
-   then **full-restart via dms-dev** — don't rely on hot reload. Keep the repo conventions
+   then **full-restart via dms-project** — don't rely on hot reload. Keep the repo conventions
    (**dms**: pnpm only, `_id` rows, no `switch`/`case`, TSDoc-only comments).

package/skills/dms-module/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: dms-module
-description: Packages a DISTRIBUTABLE DMS extension module (a reusable module other projects install, like the official dms-* modules — the package name itself is free). Use when creating a publishable DMS module, editing its package.json antelopeJs.implements manifest, registering it with RegisterModule, or defining the module's own AntelopeJS interface. For an app that just USES the DMS, see dms-project instead.
+description: Packages a distributable DMS extension module, one other projects install like the official dms-* modules. Use when creating a publishable DMS module, editing its package.json antelopeJs manifest (implements, skills), registering it with RegisterModule, or defining the module's own AntelopeJS interface package. For an app that only uses the DMS, use dms-project.
+icon: i-ph-package
 category: packaging
 tags: [module, packaging, distribution, interfaces, frontend, inertia]
 ---
@@ -13,7 +14,7 @@ tags: [module, packaging, distribution, interfaces, frontend, inertia]
 > The page/component/auth APIs are identical to a project; only the packaging differs.
 
 For the mental model see the **dms** skill; for the framework underneath
-(`ImplementInterface`, the `ajs` CLI) see the **antelopejs** plugin. A DMS module is an
+(`ImplementInterface`, the `ajs` CLI) see the **antelopejs** skill. A DMS module is an
 ordinary AntelopeJS module that (1) depends on **`@antelopejs/dms`**, (2) registers a
 module + pages on load, and (3) attaches a Vue 3 module via `AddFrontendModule` for any custom
 frontend. A consumer installs it and adds it to their `antelope.config.ts` as a
@@ -32,6 +33,11 @@ when they provide none (`dms-lang`, `dms-saas`); consumed interfaces are plain `
 `@antelopejs/interface-{core,api,api-util,auth,database,database-decorators}`. The frontend is
 attached at runtime by the `AddFrontendModule` call in `construct`; there is no manifest field for it.
 
+**Ship a skill.** Add `skills/<module-name>/SKILL.md` (frontmatter `name`, a trigger-rich
+`description`, `icon`, `category`, `tags`) saying when and how to use the module, list `"skills"` in
+`files`, and declare `"antelopeJs": { "skills": ["./skills"] }`. The **antelopejs** plugin links it into
+Claude Code and Codex projects and dms-ai loads it — `docs/08.ai-and-claude-code/7.module-skills.md`.
+
 ## The lifecycle entry (`src/index.ts`)
 
 The AntelopeJS loader calls four optional exports. Register everything in `construct`; start
@@ -107,7 +113,7 @@ in a **project** page instead.
 
 - `pnpm build` compiles `src/` only (`tsc`) — Vue template/compile errors surface only in the
   running frontend. When a change doesn't show — or `RegisterModule` throws "already
-  registered" on rebuild — **full-restart via the dms-dev skill** (its pitfalls also cover
+  registered" on rebuild — **full-restart via the dms-project skill** (its pitfalls also cover
   stubbornly stale `~/.antelopejs/dms-frontend` workspaces).
 
 ## Scaffolding (no DMS-specific generator)