@antelopejs/dms 0.9.2 → 0.9.4

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)

package/skills/dms-pages/REFERENCE.md

@@ -1,51 +1,51 @@
 # dms-pages — reference
 
-Deep material for [SKILL.md](SKILL.md): the full component builder catalog and the DataTypes
+Deep material for [SKILL.md](SKILL.md): the block catalog, patterns by topic, and the DataTypes
 catalog.
 
-## Component builders
-
-Main builders: `Form`; `TableView(controller, options)`; the charts (`ChartLine`,
-`ChartArea`, `ChartBar`, `ChartColumn`, `ChartDonut`, `ChartPie`, `ChartScatter`,
-`ChartMixed`, `ChartRadar`, `ChartRadialBar`, `ChartHeatmap`, `ChartCandlestick`, usually
-inside `ChartCard`); layout `Grid` + `GridRow`, `HStack` / `VStack` / `Spacer`, `Tab`,
-`Guard`, `Placeholder`; dashboard widgets `KpiCard`, `TopListCard`, `PeriodSelector`; display blocks
-`StatGroup`, `KeyValueList`, `NavCardGrid`, `EmptyState` (its `code` shows a snippet to
-start with), `Banner`, `Card`, and `CodeBlock` (read-only highlighted code with a copy
-button: `code` + `language`, or `fetchUrl` answering `{ code, language? }` — see
-`docs/04.components/11.display-blocks.md`); and
-`CustomComponent` (deep import from `@antelopejs/interface-dms/base/custom` — not in the barrel). Nest with
-`.child("key", builder)`; `Grid` children must be `GridRow`s. Builders also carry a
-behavioral DSL — permissioned `.action()`s and `.watch()` reactivity — see
-`docs/02.building/05.actions-and-reactivity.md`.
+## Block catalog
+
+Every block is a registered type (`ListBlockTypes()` from `@antelopejs/interface-dms/base/block-types`
+lists them with their option schemas); `docs/04.components/` has one page per block.
+
+| Group | Blocks |
+| --- | --- |
+| Layout | `Grid` + `GridRow` (children must be rows; `{ colSpan }` child metadata), `HStack` / `VStack` / `Spacer`, `Card` (slots `actions`, `footer`), `Tab` (`{ slot }` per child), `Guard`, `Placeholder` |
+| Charts & widgets | `KpiCard`, `ChartCard` (wraps one chart), `TopListCard`, `PeriodSelector`, `LiveToggle`; charts `ChartLine`, `ChartArea`, `ChartRangeArea`, `ChartBar`, `ChartColumn`, `ChartScatter`, `ChartMixed`, `ChartRadar`, `ChartCandlestick`, `ChartDonut`, `ChartPie`, `ChartRadialBar`, `ChartHeatmap` |
+| Display | `StatGroup`, `KeyValueList`, `NavCardGrid`, `EmptyState` (its `code` shows a snippet), `Banner`, `CodeBlock` (`code` + `language`, or `fetchUrl` answering `{ code, language? }`) |
+| Lists & settings | `ActivityFeed`, `Meter`, `Section` + `FieldRow` |
+| Data | `Form`, `ResourceForm(controller, { mode: "new" \| "edit" \| "view" })` (from `/base/table-view`), `TableView(controller, options)` |
+| Escape hatch | `CustomComponent(name)` (deep import from `@antelopejs/interface-dms/base/custom` — not in the barrel), always with `.meta()` — see **dms-best-practices** |
+
+Nest with `.child("key", builder)`. Builders also carry a behavioral DSL — permissioned
+`.action()`s and `.watch()` reactivity — see `docs/02.building/05.actions-and-reactivity.md`.
 
 `Guard({ fetchUrl, field?, when?, fallback? })` wraps any blocks and shows one `EmptyState`
 (`fallback`) in their place when the route says there is nothing: `when: "empty"` (default)
 checks the value at `field` (absent / `null` / `false` / `0` / `""` / `[]`), `when: "notFound"`
 a 404. The children show while loading and on any other failure; an `emptyState` in the
-answer is laid over `fallback` — `docs/04.components/03.layout-and-containers.md#guard`.
+answer is laid over `fallback` — `docs/04.components/03.layout-and-containers/5.guard.md`.
 A block whose `fetchUrl` answers 404 shows its own "Not found" (no retry), the 404 body's
-`message` / `emptyState` over it; a `Guard` with `when: "notFound"` draws the same state once
-for the blocks it wraps — `docs/04.components/11.display-blocks.md#not-found`.
+`message` / `emptyState` over it — `docs/04.components/02.block-fundamentals.md#not-found`.
 
 A `TableView` scoped by the page URL takes `queryParamFilters: { status: { field: "status" } }`
 (hidden filters read from `?status=`; `routeParamFilters` for slug params like `:id`). No
 glue is needed around it: an active query filter shows the `filtered` empty state, and a
 link changing its value sends the table back to page 1. A drawer or modal row action already
 gets `navigation` (J / K, `index` / `total` in the order shown) —
-`docs/04.components/06.tables/8.row-drawers.md`.
+`docs/04.components/08.tables/8.row-drawers.md`.
 
 A page's `headerActions` follow its URL: a target URL takes `{{params.X}}` / `{{query.X}}`
 (`?workspace={{query.workspace}}`, a pair the page has no value for is dropped), a label's
 translation takes the page's route and query parameters (`"Download {locale}.json"`), and an
 `availability` reads `context.query`, asked again when the query changes — no need to build
 the header in Vue with `usePageHeaderActions` to carry the scope —
-`docs/07.interfaces/3.base/6.layout.md#buttons-that-follow-the-page-url`. An `availability`
+`packages/interface-dms/docs/3.base/6.layout.md#buttons-that-follow-the-page-url`. An `availability`
 answering `{ hidden: true }` leaves the button out for that query (`{ reason }` only
 disables it): no Vue header to hide "Add key" on a read-only workspace. `order` on a
 header button and `usePageHeaderActions(render, { order })` interleave served buttons with a
 component's client-side ones (default `0`, served first on a tie: `order: -1` puts a Vue
-"Export" before a served "Add key") — `docs/07.interfaces/3.base/6.layout.md#ordering-the-header`.
+"Export" before a served "Add key") — `packages/interface-dms/docs/3.base/6.layout.md#ordering-the-header`.
 
 A button or row action (`customButtons`, `rowActions.custom`, a page's `headerActions`)
 points at an `ActionTarget`. A `drawer` target opens from the bottom; give it
@@ -55,16 +55,102 @@ To read rows one after the other next to the table (a request log), use a `sideP
 target instead: a non-modal panel docked on the right whose header the DMS draws (title,
 `rowTitle` naming the row from its fields, `positionLabel` "x of y", previous / next, J / K, close), `?record=` kept by default (`deepLink: false` opts out), a "not found" state on a 404 (`notFound: { title, description }`) and the table's
 `rowClick: "single"` (a `TableView.fromSource` table reads a deep-linked row beyond its first page through `fetchRowUrl: "/api/x/{{row.id}}"`) — never bridge the table's DOM to build one —
-`docs/04.components/06.tables/8.row-drawers.md#side-panel`.
+`docs/04.components/08.tables/8.row-drawers.md#side-panel`.
 A button downloading a file the user's session may read (`/api/...`) takes a `download`
 target, `{ url, filename? }`, with the same `{{row.field}}` / `{{query.X}}` tokens — never a Vue
-header button or an `api` target for it — `docs/07.interfaces/3.base/2.types.md`.
+header button or an `api` target for it — `packages/interface-dms/docs/3.base/2.types.md`.
 
 A row that must stay on top of a table under any sort (a base language, a default
 workspace) takes `pinnedRows: { field: "isBase", equals: true }` — never sort on the
 server for it. A row action names its row with `{field}` braces in its `label`
 (`"Translate {name}"`), and `rowActions.menuLabel` (`"Actions for {name}"`) names the
-row's ⋯ button — `docs/04.components/06.tables/0.index.md#pinned-rows`.
+row's ⋯ button — `docs/04.components/08.tables/0.index.md#pinned-rows`.
+
+## Patterns by topic
+
+### Data, URLs and refresh
+
+- Every URL token is `{{<scope>.<key>}}`: `params` and `query` (the page URL, percent-encoded;
+  nothing is fetched while one is unresolved), `row` (an action's row), `response` (a form's
+  redirect). The same page tokens work in every URL and link option.
+- `.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=`).
+- `realtimeTopic` re-fetches a chart, list block, `Meter`, `Tab` badges or `TableView` on each
+  `PublishMessage`.
+
+### Live pages
+
+- 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; `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; `liveHold.missedLabel` words its "N new".
+  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()` (`hold(reason)` / `release()`,
+  `setMissedDetail()`); one that reads its own data on a topic calls
+  `usePageLiveRefresh(refresh, { realtimeTopic, idleRefresh })` — never a throttle of its own.
+  `refreshPageBlocks()` (user actions) always reads; `refreshLivePageBlocks()` (timers, feeds) is
+  held while paused.
+
+### Texts
+
+- A text naming values is a `ComposedText` — `{ key, params: { amount: { type: "money", value: 92200,
+  currency: "EUR" } } }` — written by the browser in the reader's language. StatGroup /
+  KeyValueList / Banner / NavCardGrid / ActivityFeed / Meter / TopListCard item texts, ActivityFeed
+  `params` (typed `count` for plurals), tab badges and layout banners (`RegisterLayoutBanner({ resolve })`
+  → `{ text, actions }`) take it. Never format text server-side.
+- 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.
+
+### Blocks
+
+- `StatGroup` details and `NavCardGrid` card titles take up to two lines before their ellipsis.
+- `ActivityFeed`: `wrap: true` for entries read whole (leave `fillHeight` off), `visibleItems: N`
+  for a "Show N more" fold.
+- `KeyValueList` rows take `copy: true` or `copyValue` (the text to copy instead).
+- `TopListCard({ actions })` puts link buttons in its head; `Tab({ fit: true })` keeps pill tabs to
+  their labels' width; with `persistState` the URL names the open tab by its slot (`?tab=tester`).
+- A `ChartCard` plotting several series names them with `showSeriesLegend: true` (placed by the
+  chart's `legendPosition`) — never a raw Apex `legend` in `rawOptions`.
+
+### Tables
+
+- A cell's secondary line is a row field holding text or a composed text (or `{ text, tone }`),
+  named by `StatusPillDisplay({ subField })`, `IdentityDisplay({ subtitleField })` or
+  `TwoLineDisplay({ subField })`; `IdentityDisplay({ emptyLabel, emptyIcon, iconField })`.
+- `StatusPillDisplay({ toneField })`, `DurationDisplay({ toneField, format: "ms" })` and
+  `TextDisplay({ toneField })` read a tone from a row field; a `PillsDisplay` item may be
+  `{ label, tone?, variant: "soft" | "outline" }`.
+- A `TableView` over a shared controller hides a column on one page with
+  `columns: { hidden: ["workspace"] }` — no view just to hide it.
+- A table ordered by hand (`reorder: { field }`) moves rows on the grid and cards on the `cards`
+  display alike; a `card.component` receives a `reorder` prop and `v-bind`s `reorder.handle`.
+
+### Forms
+
+- A unit after a number field is `NumberType({ suffix: "$…days" })`; a character counter is
+  `StringType({ maxLength, showCount: true })` — no custom `inputComponent` for either.
+- A long sectioned `Form` groups its navigation with `FormSection.navGroup`, in the side list and
+  the `sectionNav: "jump"` chips alike.
+- A module's own `inputComponent` submits its form, adds a validator and focuses a field with
+  `useEnclosingForm()` (never `closest("form")` / `requestSubmit()`); a link ending in `#<fieldId>`
+  opens the form on that field. `DmsInputNumber` emits `adjust` when it keeps another value than the
+  one typed — listen to it rather than forcing a remount.
+
+### Custom components
+
+- Name the record at the end of the breadcrumb with
+  `usePageRecordLabel().setLabel(useDmsRoute().path, label)`.
+- Format through `useRegionalFormat()`; `useRegionalFormat({ locale: "format" })` writes in the
+  locale of the DMS's texts (`en` → `en-GB`).
+- Bring a block into view with `scrollToBlock("tabs.statistics")` — never a DOM query.
+- Show code with `DmsCodeSnippet` (`language`, `title`, `maxLines` or `maxHeight`, `wrap`) — never a
+  `<pre>` and a copy button of your own.
 
 ## DataTypes
 
@@ -74,5 +160,5 @@ catalog (19 built in, `@antelopejs/interface-dms/base/data-types`): `String`, `N
 `Relation`, `CascaderRelation`, `Address`, `RichText`, `StringTime`,
 `File`, `Image` (each as `<Name>Type`), plus `StatusType` via the `data-types` barrel. The
 same types drive TableView columns and filters — options per type are in
-`docs/04.components/08.data-types.md`. Custom types: subclass `DataType`, decorate with
+`docs/04.components/10.data-types.md`. Custom types: subclass `DataType`, decorate with
 `@RegisterDataType("id")` (frontend side: `docs/05.extending-the-dashboard/04.custom-data-types.md`).

package/skills/dms-pages/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: dms-pages
-description: Declares admin pages and composes backend-driven UI on the AntelopeJS DMS. Use when adding a dashboard screen, writing a @RegisterPage / PageController class, composing Form / TableView / Chart / Grid builders imported from @antelopejs/interface-dms/base, or choosing DataTypes and wiring the routes and DataControllers that feed them.
+description: Declares admin pages and composes backend-driven UI on the AntelopeJS DMS. Use when adding a dashboard screen, writing a @RegisterPage / PageController class, composing Form / TableView / Chart / Grid / KpiCard blocks imported from @antelopejs/interface-dms/base, or choosing DataTypes and wiring the routes and DataControllers that feed them.
+icon: i-ph-layout
 category: dashboard
 tags: [pages, components, forms, tables, data-types, navigation]
 ---
@@ -9,9 +10,10 @@ tags: [pages, components, forms, tables, data-types, navigation]
 
 The DMS is backend-driven: you declare a **page** and attach **components** to it as static
 fields. The builders produce a serializable description that the shared Vue 3 + Inertia frontend
-renders — you write no Vue for standard screens. Depth: `docs/02.building/03.pages-and-components.md`
-(pages), `docs/02.building/04.navigation.md` (nav tree), and the `docs/04.components/`
-catalog (one chapter per component family).
+renders — you write no Vue for standard screens. **Before composing a page, apply
+dms-best-practices** (blocks only, custom for the missing block, `.meta()`, design fidelity). Depth:
+`docs/02.building/03.pages-and-components.md` (pages), `docs/02.building/04.navigation.md` (nav
+tree), and `docs/04.components/` (one page per block, with its options).
 
 ## Declaring a page
 
@@ -70,11 +72,10 @@ The full catalog — `Form`, `TableView`, the charts, layout containers, dashboa
 widgets, `CustomComponent` — plus nesting rules and the behavioral DSL (permissioned
 `.action()`s, `.watch()` reactivity) is in [REFERENCE.md](REFERENCE.md).
 
-**Custom UI: decompose, don't monolith.** Never build a whole screen as one full-page
-`CustomComponent` SFC — that silently opts out of per-component permissions,
-`.action()`/`.watch()` reactivity, `PeriodSelector` scoping, and backend-driven layout. Use
-built-in builders wherever they suffice and one small `CustomComponent` per part that
-genuinely needs Vue (`docs/04.components/04.custom-component.md`).
+**Custom UI: only the missing block.** A screen is always a tree of DMS blocks; a part with no
+DMS equivalent becomes one `CustomComponent` (from `@antelopejs/interface-dms/base/custom`) carrying
+`.meta({ name, description, icon })` with `$` keys — the rules and the design-fidelity protocol are
+in **dms-best-practices** (`docs/04.components/09.custom-component.md`).
 
 ## Feeding components with data
 
@@ -97,7 +98,7 @@ with `@RegisterDataController()` (both from `@antelopejs/interface-data-api`).
 class-level `@ColumnGroup(id, config)`), `@Listable` / `@Sortable` from
 `@antelopejs/interface-data-api/metadata`. Read a
 real one first: `@antelopejs/interface-dms/data-controllers` (`members`); guide in
-`docs/04.components/09.data-controller.md` (+ `06.tables/`). Database rows carry **`_id`**
+`docs/04.components/11.data-controller.md` (+ `08.tables/`). Database rows carry **`_id`**
 as the primary key — return and type it as `_id`, never alias to `id`.
 
 ## DataTypes
@@ -109,6 +110,6 @@ built-in types and how to register custom ones.
 ## Verify in the browser
 
 The build only typechecks `src/` — it will not catch a Vue error in a custom component or a
-wrong URL. After editing pages, full-restart and click through (see **dms-dev**). A hand-written link
+wrong URL. After editing pages, full-restart and click through (see **dms-project**). A hand-written link
 to a module page must include the `/modules/<moduleId>` prefix (or read `fullSlug` from the
 layout) — a missing prefix 404s through the frontend catch-all even though the build is clean.

package/skills/dms-project/DEV-SERVERS.md

@@ -0,0 +1,74 @@
+# dms-project — dev servers reference
+
+Details behind the **Running the dev servers** section of [SKILL.md](SKILL.md): resolving the
+project path, choosing the process manager, what `stop` touches, and the failures that look like
+bugs.
+
+## Resolve the backend path
+
+`DMS_BACK_DIR` is the absolute path of the project's DMS backend package directory (the one whose
+scripts start the AntelopeJS backend and the frontend loader). Resolve it before the first script
+call of a session, in this order:
+
+1. **The current repository.** Use the project that `package.json`, `antelope.config.ts` and any
+   service configuration identify, when the path is unambiguous.
+2. **Project memory.** Read the reference memory named `dms-back-path`. Use it only if the
+   directory still exists and contains a `package.json`; otherwise treat it as stale.
+3. **The user**, when the path is still ambiguous: "Which AntelopeJS DMS project should I run?
+   Give me the absolute path to its DMS backend package directory." Verify the answer, then save it
+   as a reference memory so later sessions skip the question:
+
+   ```markdown
+   ---
+   name: dms-back-path
+   description: Absolute path to the DMS backend package directory for this project, used by the dms-project skill to run pnpm dev / pnpm frontend:dev.
+   metadata:
+     type: reference
+   ---
+
+   /absolute/path/to/the-backend-package
+   ```
+
+   Add the index line to `MEMORY.md`: `- [DMS backend path](dms-back-path.md) — where dms-project runs pnpm dev / pnpm frontend:dev`.
+
+A saved path that no longer exists makes the script fail fast with a clear error: ask again and
+overwrite the memory.
+
+## Choose the process manager
+
+The script is for local shells. In an Amp orb, use the repository's `.amp/services.yaml` with
+`amp orb services ensure`, or `amp orb service start` for a one-off service; check readiness with
+service logs and HTTP checks and share the returned portal URL. Processes the script detaches do
+not survive orb updates.
+
+## What `stop` and `restart` touch
+
+Only the project in `DMS_BACK_DIR`. The script records the pids it starts in
+`DMS_BACK_DIR/.antelope/dms-dev.pid`; without that file it matches only dev processes whose working
+directory or command line lies under `DMS_BACK_DIR`. Each process gets SIGTERM, then SIGKILL after
+`DMS_DEV_STOP_GRACE` seconds (default 10). Other projects' dev servers on the machine keep running,
+which is why the script replaces `pkill` by name (`pkill -9 node`, `pkill -f antelope-runner`).
+
+Run one `start` or `restart` at a time: a second concurrent call hits a port or lock conflict.
+
+## Pitfalls
+
+- **Zombie frontend processes.** The frontend CLI spawns children. `stop` signals the whole
+  session and process tree it started. If `start` reports servers already running, run `stop`
+  and check that `status` shows `(none)` before starting again.
+- **Backend exits with "Module already registered".** A previous instance still holds the
+  registration: `stop`, then `restart`.
+- **A boot that never gets ready.** Read `back-log` / `front-log`. Common causes: "already
+  registered" (above), a port already in use (kill the listed pid), a missing dependency
+  (`pnpm install` in the offending module).
+- **A 302 on `/modules/...` URLs is normal**: those admin routes require a login. The layer is
+  loaded; have the user log in rather than restarting.
+- **A frontend still stale after restarts.** The loader serves layers from copies under
+  `~/.antelopejs/dms-frontend/<hash>/`. Reset them with `ajs dms clean --all` in the backend
+  package directory (bare `ajs dms clean` asks for `-b` or `--all`, and `-b <url>` misses
+  autodiscovered workspaces, which are keyed by project path), then `restart`.
+- **`ajs dms` reports a refused credential (401), or the backend logs "no valid bootstrap
+  credential".** The frontend authenticates to the layer endpoints with the ephemeral secret a dev
+  backend publishes to `<project>/.antelope/dms-dev.json`. A 401 means that file is absent
+  (backend not in dev mode) or stale: it outlives the backend that wrote it. `restart` rewrites
+  it. A frontend running outside the project tree needs `DMS_BOOTSTRAP_SECRET`.