@antelopejs/dms 0.9.1 → 0.9.3

package/frontend-vue/layers/dms-ui/app/components/block-preview/BlockPreview.vue

@@ -0,0 +1,172 @@
+<script setup lang="ts">
+import { markRaw, type Component } from "vue";
+import BlockPreviewIssue from "../../build/components/block-preview/BlockPreviewIssue.vue";
+import { useBlockPreviewEmbed } from "../../build/composables/block-preview/useBlockPreviewEmbed";
+import {
+  collectPreviewIssues,
+  decodePreviewState,
+  resolvePreviewTree,
+  type PreviewBlockTypes,
+  type PreviewIssue,
+  type PreviewResolvedNode,
+  type PreviewTree,
+} from "../../build/utils/blockPreview";
+import { childComponentId } from "../../utils/componentId";
+
+/**
+ * Draws a tree of registered DMS blocks exactly as a page would.
+ *
+ * In a dashboard, hand it the tree: `<DmsBlockPreview :tree="node" />`. On
+ * `/dms-preview` (`embed`), it reads `?state=` and the parent window's
+ * `postMessage` instead, and reports back its height. There, `transparent`
+ * marks the root so the preview layout paints no background.
+ *
+ * Only registered block types are drawn; any other node, a block needing a
+ * backend resource, or one whose URL options are not relative paths of this
+ * site, renders an inline notice.
+ */
+const props = withDefaults(
+  defineProps<{
+    tree?: PreviewTree;
+    /** The allowlist; fetched from the backend when absent. */
+    blockTypes?: PreviewBlockTypes;
+    /** Driven by `?state=` and `postMessage`, as `/dms-preview` is. */
+    embed?: boolean;
+    /** Pads the blocks off the edges; `?state=` may override it. */
+    padding?: boolean;
+    pageId?: string;
+    componentId?: string;
+  }>(),
+  {
+    tree: undefined,
+    blockTypes: undefined,
+    embed: false,
+    padding: false,
+    pageId: "dms-preview",
+    componentId: "preview",
+  },
+);
+
+const BLOCK_TYPES_ENDPOINT = "/api/block-preview/types";
+const STATE_QUERY = "state";
+
+const { t, locale, locales, setLocale } = useI18n();
+const route = useDmsRoute();
+const root = useTemplateRef<HTMLElement>("root");
+
+const stateParam = route.query[STATE_QUERY];
+const initialState =
+  props.embed && typeof stateParam === "string"
+    ? decodePreviewState(stateParam)
+    : undefined;
+const isStateInvalid = props.embed && !!stateParam && !initialState;
+
+function switchLocale(code: string): void {
+  const known = locales.value.some((entry) => entry.code === code);
+  if (known && code !== locale.value)
+    void setLocale(code as typeof locale.value);
+}
+
+const embed = props.embed
+  ? useBlockPreviewEmbed({ root, initialState, setLocale: switchLocale })
+  : undefined;
+
+const fetchedBlockTypes = ref<PreviewBlockTypes>();
+const blockTypes = computed(() => props.blockTypes ?? fetchedBlockTypes.value);
+const tree = computed(() => (embed ? embed.tree.value : props.tree));
+const revision = computed(() => embed?.revision.value ?? 0);
+const isTransparent = computed(() => embed?.transparent.value ?? false);
+const isPadded = computed(
+  () => initialState?.padding ?? (props.embed || props.padding),
+);
+
+const resolved = computed<PreviewResolvedNode[]>(() =>
+  tree.value && blockTypes.value
+    ? resolvePreviewTree(tree.value, blockTypes.value)
+    : [],
+);
+
+function toPageComponent(node: PreviewResolvedNode): ResolvedComponentInfo {
+  const component: Component | string = node.issue
+    ? markRaw(BlockPreviewIssue)
+    : (resolveDmsComponent(node.componentName) ?? "div");
+  return {
+    id: node.id,
+    component,
+    componentName: node.componentName,
+    options: node.issue ? { issue: node.issue } : node.options,
+    children: node.children.map(toPageComponent),
+    ...(node.slot ? { slot: node.slot } : {}),
+    ...(node.colSpan === undefined ? {} : { colSpan: node.colSpan }),
+  };
+}
+
+const components = computed(() => resolved.value.map(toPageComponent));
+
+function describeIssue(issue: PreviewIssue): string {
+  return t(`dms.block_preview.${issue.key}`, {
+    name: issue.name,
+    value: issue.value ?? "",
+  });
+}
+
+function reportIssues(nodes: PreviewResolvedNode[]): void {
+  const issues = collectPreviewIssues(nodes);
+  if (issues.length) embed?.reportError(issues.map(describeIssue).join("\n"));
+}
+
+watch(resolved, reportIssues);
+
+onMounted(async () => {
+  if (isStateInvalid) embed?.reportError(t("dms.block_preview.invalid_state"));
+  reportIssues(resolved.value);
+  // The page always hands the allowlist; fetching it is for a signed-in
+  // dashboard, and a public visitor would only be sent to the login page.
+  if (props.blockTypes || props.embed) return;
+  const { $authFetch } = useAuthFetch();
+  try {
+    fetchedBlockTypes.value =
+      await $authFetch<PreviewBlockTypes>(BLOCK_TYPES_ENDPOINT);
+  } catch (error: unknown) {
+    embed?.reportError(error instanceof Error ? error.message : String(error));
+  }
+});
+</script>
+
+<template>
+  <div
+    ref="root"
+    data-dms-block-preview
+    :data-dms-preview-transparent="isTransparent || undefined"
+    :class="{ 'p-4 sm:p-6': isPadded }"
+  >
+    <UAlert
+      v-if="isStateInvalid"
+      color="error"
+      variant="subtle"
+      icon="i-ph-warning-circle"
+      :title="t('dms.block_preview.invalid_state')"
+    />
+    <p
+      v-else-if="!components.length && embed"
+      class="text-muted py-8 text-center text-sm"
+    >
+      {{ t("dms.block_preview.empty") }}
+    </p>
+    <div v-else :key="revision" class="dms-page-stack space-y-6">
+      <div
+        v-for="component in components"
+        :key="component.id"
+        class="empty:hidden"
+        data-dms-preview-block
+      >
+        <DmsRecursiveComponent
+          :component="component"
+          :page-id="pageId"
+          :component-id="childComponentId(componentId, component.id)"
+          :layout-path="component.id"
+        />
+      </div>
+    </div>
+  </div>
+</template>

package/frontend-vue/layers/dms-ui/app/components/table-view/KanbanBoard.vue

@@ -1,7 +1,9 @@
 <script setup lang="ts" generic="T extends Data">
-import Draggable from "vuedraggable";
 import { get } from "@nuxt/ui/runtime/utils/index.js";
 import type { Data } from "../../build/components/table/Table.vue";
+import SortableList, {
+  type SortableListChange,
+} from "../../build/components/sortable/SortableList.vue";
 import {
   AccessMode,
   type TableViewColumn,
@@ -184,6 +186,13 @@ const loadMore = async (col: KanbanColumnDef) => {
   }
 };
 
+// A drag hands each list it changed its new cards.
+const setColumnItems = (col: KanbanColumnDef, items: T[]) => {
+  const cell = cells.value[col.value];
+  if (cell) cell.items = items;
+  else cells.value[col.value] = { items, total: 0, loadingMore: false };
+};
+
 const hasMore = (col: KanbanColumnDef): boolean => {
   const cell = cells.value[col.value];
   return !!cell && cell.items.length < cell.total;
@@ -221,11 +230,6 @@ const canDeleteItem = (item: T): boolean =>
 const isItemLocked = (item: T): boolean =>
   isDragEnabled.value && !canDragItem(item);
 
-interface DraggableChangeEvent {
-  added?: { element: T; newIndex: number };
-  removed?: { element: T; oldIndex: number };
-}
-
 // The edit route requires the full editable field set in the body (absent
 // fields would fail the mandatory check or be blanked), so fetch the item and
 // resubmit it like the edit form does: localized fields as records
@@ -316,7 +320,7 @@ const notifyMoveError = (error: unknown) => {
 
 const onColumnChange = async (
   target: KanbanColumnDef,
-  event: DraggableChangeEvent,
+  event: SortableListChange<T>,
 ) => {
   const added = event.added;
   if (!added) return;
@@ -326,7 +330,7 @@ const onColumnChange = async (
 
   if (!itemId) {
     // No stable ID — the move cannot be persisted; refresh to undo the
-    // local reorder vuedraggable already applied.
+    // local move the list already applied.
     await refresh();
     return;
   }
@@ -507,20 +511,18 @@ const FieldValue = (fieldProps: { column: TableViewColumn; item: T }) => {
             </div>
           </div>
 
-          <Draggable
+          <SortableList
             v-else
             :list="cells[col.value]?.items ?? []"
             :group="`kanban-${componentId}`"
             :disabled="!isDragEnabled"
-            :item-key="rowIdKey"
+            :item-key="getRowId"
             filter=".kanban-card-locked"
-            :prevent-on-filter="false"
             class="flex min-h-16 flex-col gap-2"
+            @update:list="(items) => setColumnItems(col, items)"
             ghost-class="dms-kanban-ghost"
             drag-class="dms-kanban-drag"
-            @change="
-              (event: DraggableChangeEvent) => onColumnChange(col, event)
-            "
+            @change="(event) => onColumnChange(col, event)"
           >
             <template #item="{ element }">
               <div :class="{ 'kanban-card-locked': !canDragItem(element) }">
@@ -585,7 +587,7 @@ const FieldValue = (fieldProps: { column: TableViewColumn; item: T }) => {
                 </div>
               </div>
             </template>
-          </Draggable>
+          </SortableList>
         </div>
 
         <div v-if="hasMore(col)" class="px-2 pb-2">

package/frontend-vue/layers/dms-ui/app/components/table-view/TableView.vue

@@ -1214,10 +1214,7 @@ const refreshAll = async () => {
 // block's action): a topic of the backend or a page refresh reads them again,
 // keeping the current rows on screen until the answer lands. On a live page
 // the row events below go through the same gate.
-const liveGate = useRefreshTriggers(
-  props.realtimeTopic,
-  () => void refreshAll(),
-);
+const liveGate = useRefreshTriggers(props.realtimeTopic, () => refreshAll());
 // What the user asks for (a row action, the refresh button, ⌘R, a display's
 // own action) reads at once, even while the live page is paused, and brings
 // a held table up to date.

package/frontend-vue/layers/dms-ui/app/composables/chart/useChartFetch.ts

@@ -1,6 +1,8 @@
 import {
   computed,
+  getCurrentScope,
   onMounted,
+  onScopeDispose,
   ref,
   shallowRef,
   watch,
@@ -157,6 +159,40 @@ function useScopeWait(isWaiting: () => boolean): ComputedRef<boolean> {
   return computed(() => isWaiting() && !gaveUp.value);
 }
 
+function useDebouncedRefresh(
+  refresh: () => Promise<unknown>,
+  isPending: () => boolean,
+): () => Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let waiting: Promise<void> | null = null;
+  let resolveWaiting = () => {};
+  const finish = () => {
+    resolveWaiting();
+    waiting = null;
+  };
+  const finishIfSettled = () => {
+    if (!timer && !isPending()) finish();
+  };
+  watch(isPending, finishIfSettled);
+  if (getCurrentScope())
+    onScopeDispose(() => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      finish();
+    });
+  return () => {
+    if (timer) clearTimeout(timer);
+    waiting ??= new Promise<void>((resolve) => (resolveWaiting = resolve));
+    timer = setTimeout(() => {
+      timer = null;
+      // Cancellation ends one execution, not the refresh its callers await.
+      // Keep waiting while a replacement read is pending.
+      void refresh().then(finishIfSettled, finishIfSettled);
+    }, DEBOUNCE_FRAME_MS);
+    return waiting;
+  };
+}
+
 /**
  * The data of a block that reads `fetchUrl`, through `useApiData`: a server
  * render requests it and hands it to the browser, unless the URL waits for a
@@ -197,7 +233,9 @@ export function useChartFetch<T>(
   const { data, status, error } = loaded;
   // A 404 says what the block showed is gone (another tab deleted it, the
   // URL now names another record): its last values must not stay on screen
-  // as if they still belonged to it. Any other failure keeps them.
+  // as if they still belonged to it. Any other failure of a read of the same
+  // request keeps them; a failure of a different (reactive) request shows
+  // none, as they belong to the record it replaced.
   watch(error, (failure) => {
     if (failure && readFetchNotFound(failure)) data.value = null;
   });
@@ -218,14 +256,14 @@ export function useChartFetch<T>(
   // A realtime event or a page refresh (refreshPageBlocks) means the data
   // behind unchanged inputs moved: read again once a burst holds still. The
   // values on screen stay current until the new answer replaces them.
-  let refreshTimer: ReturnType<typeof setTimeout> | null = null;
-  useRefreshTriggers(options.realtimeTopic, () => {
-    if (refreshTimer) clearTimeout(refreshTimer);
-    refreshTimer = setTimeout(() => {
-      refreshTimer = null;
-      void loaded.refresh();
-    }, DEBOUNCE_FRAME_MS);
-  });
+  // `refreshPageBlocks()` waits for the read the burst ends with.
+  useRefreshTriggers(
+    options.realtimeTopic,
+    useDebouncedRefresh(
+      () => loaded.refresh(),
+      () => status.value === "pending",
+    ),
+  );
   return { data: data as Ref<T | null>, isLoading, error, refresh };
 }
 

package/frontend-vue/layers/dms-ui/app/composables/form/useForm.ts

@@ -629,7 +629,10 @@ export const useForm = (props: FormProps, options: UseFormOptions = {}) => {
       };
       return processBeforeStateMappers(fetchedData, props.fields, getDataType);
     } catch (error) {
-      showFetchErrorToast(error);
+      // A server render shows the failure in the form (FormLoadError) and
+      // hands it to the browser; a toast it added would show in its HTML
+      // alone, which the browser's toasts never hold.
+      if (!import.meta.env.SSR) showFetchErrorToast(error);
       throw error;
     }
   };

package/frontend-vue/layers/dms-ui/i18n/locales/ui-en-GB.json

@@ -763,6 +763,14 @@
       "not_found_description": "The link points to an entry that was deleted, or that this list cannot show.",
       "failed_title": "This entry could not be opened",
       "failed_description": "Loading it failed. Try again in a moment."
+    },
+    "block_preview": {
+      "unknown_block": "“{name}” is not a registered block type.",
+      "needs_backend": "{name} reads a backend resource, which a preview does not have.",
+      "unsafe_url": "{name} was not drawn: “{value}” is not a path of this site.",
+      "invalid_state": "The preview state could not be read.",
+      "empty": "Nothing to preview yet.",
+      "unsafe_method": "{name} was not drawn: a preview only reads its data, and {value} writes."
     }
   }
 }

package/frontend-vue/layers/dms-ui/i18n/locales/ui-fr-FR.json

@@ -764,6 +764,14 @@
       "not_found_description": "Le lien mène à une entrée supprimée, ou que cette liste ne peut pas afficher.",
       "failed_title": "Impossible d’ouvrir cette entrée",
       "failed_description": "Son chargement a échoué. Réessayez dans un instant."
+    },
+    "block_preview": {
+      "unknown_block": "« {name} » n’est pas un type de bloc enregistré.",
+      "needs_backend": "{name} lit une ressource du backend, qu’un aperçu n’a pas.",
+      "unsafe_url": "{name} n’a pas été affiché : « {value} » n’est pas un chemin de ce site.",
+      "invalid_state": "L’état de l’aperçu est illisible.",
+      "empty": "Rien à prévisualiser pour l’instant.",
+      "unsafe_method": "{name} n’a pas été affiché : un aperçu ne fait que lire ses données, et {value} écrit."
     }
   }
 }

package/frontend-vue/package.json

@@ -11,7 +11,7 @@
   "license": "Apache-2.0",
   "packageManager": "pnpm@10.6.5",
   "engines": {
-    "@antelopejs/dms-frontend": ">=0.6.1 <0.7.0"
+    "@antelopejs/dms-frontend": ">=0.6.3 <0.7.0"
   },
   "scripts": {
     "typecheck": "ajs dms verify-source --layer \"$PWD\" --local-package @antelopejs/dms=.. --local-package @antelopejs/interface-dms=../../interface-dms",
@@ -50,6 +50,7 @@
     "@tiptap/pm": "^3.30.2",
     "@tiptap/starter-kit": "^3.30.2",
     "@tiptap/vue-3": "^3.30.2",
+    "@types/sortablejs": "^1.15.8",
     "@vue-flow/background": "^1.3.2",
     "@vue-flow/controls": "^1.1.3",
     "@vue-flow/core": "^1.48.2",
@@ -64,17 +65,17 @@
     "jsonwebtoken": "^9.0.3",
     "reka-ui": "^2.6.0",
     "scule": "^1.3.0",
+    "sortablejs": "^1.14.0",
     "striptags": "^3.2.0",
     "tailwind-merge": "^3.3.1",
     "tailwind-variants": "^3.1.1",
     "ufo": "^1.6.1",
     "vue3-apexcharts": "1.10.0",
-    "vuedraggable": "^4.1.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {
-    "@antelopejs/core": ">=1.15.0 <2",
-    "@antelopejs/dms-frontend": ">=0.6.1 <0.7.0",
+    "@antelopejs/core": ">=1.16.0 <2",
+    "@antelopejs/dms-frontend": ">=0.6.3 <0.7.0",
     "@eslint/js": "^8.57.0",
     "@inertiajs/vue3": "^3.7.0",
     "@nuxt/ui": "4.10.0",

package/package.json

@@ -1,16 +1,39 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.9.1",
+  "version": "0.9.3",
+  "description": "The AntelopeJS dashboard management system: admin dashboards declared in TypeScript, with auth and tenancy, data management, file uploads, notifications and realtime.",
+  "keywords": [
+    "antelopejs",
+    "dms",
+    "dashboard",
+    "admin",
+    "backoffice",
+    "inertia",
+    "vue"
+  ],
+  "homepage": "https://dms.antelopejs.com/docs",
+  "bugs": {
+    "url": "https://github.com/AntelopeJS/dms/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/AntelopeJS/dms.git"
+    "url": "git+https://github.com/AntelopeJS/dms.git",
+    "directory": "packages/dms"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
     "!dist/.tsbuildinfo",
+    "!dist/test",
     "frontend-vue",
+    "!frontend-vue/tests",
+    "!frontend-vue/vitest.config.ts",
+    "!frontend-vue/eslint.config.mjs",
+    "!frontend-vue/.prettierrc",
+    "!frontend-vue/.vscode",
+    "!frontend-vue/pnpm-lock.yaml",
+    "!frontend-vue/pnpm-workspace.yaml",
     "skills",
     "data",
     "package.json",
@@ -31,15 +54,15 @@
   },
   "dependencies": {
     "2fa": "^0.1.2",
-    "@antelopejs/interface-api": ">=0.0.13 <1.0.0",
-    "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
-    "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.2.0 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.8 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.7.0 <0.8.0",
-    "@antelopejs/interface-email": ">=0.0.5 <1.0.0",
-    "@antelopejs/interface-file-storage": ">=0.1.3 <1.0.0",
+    "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
+    "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
+    "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.2.2 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
+    "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
+    "@antelopejs/interface-dms": ">=0.7.2 <0.8.0",
+    "@antelopejs/interface-email": ">=0.0.6 <1.0.0",
+    "@antelopejs/interface-file-storage": ">=0.1.4 <1.0.0",
     "archiver": "^7.0.1",
     "csv-stringify": "^6.7.0",
     "defu": "^6.1.4",
@@ -54,8 +77,8 @@
     "zod": "~3.24.2"
   },
   "devDependencies": {
-    "@antelopejs/core": ">=1.13.4 <2",
-    "@antelopejs/tooling-configs": ">=0.0.7 <1.0.0",
+    "@antelopejs/core": ">=1.16.0 <2",
+    "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
     "@types/archiver": "^6.0.4",
     "@types/chai": "^4.3.20",
     "@types/jsonwebtoken": "^9.0.10",
@@ -72,6 +95,7 @@
     "oxfmt": "^0.66.0",
     "oxlint": "1.81.0",
     "oxlint-tsgolint": "^7.0.2001",
+    "playwright-core": "~1.56.1",
     "release-it": "^19.2.4",
     "release-it-changelogen": "^0.1.0",
     "rimraf": "^6.1.3",
@@ -92,11 +116,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "optionalDependencies": {
-    "@antelopejs/interface-dms-automation": ">=0.1.0 <1.0.0",
-    "@antelopejs/interface-redis": ">=0.0.8 <1.0.0"
+    "@antelopejs/interface-dms-automation": ">=0.2.1 <1.0.0",
+    "@antelopejs/interface-redis": ">=0.0.9 <1.0.0"
   },
   "peerDependencies": {
-    "@antelopejs/core": ">=1.13.2 <2"
+    "@antelopejs/core": ">=1.16.0 <2"
   },
   "peerDependenciesMeta": {
     "@antelopejs/core": {
@@ -118,6 +142,9 @@
     "release": "pnpm --filter @antelopejs/interface-dms build && pnpm --dir frontend-vue install --frozen-lockfile && release-it",
     "country-database": "node scripts/fetch-country-database.mjs",
     "knip": "knip --dependencies",
-    "knip:all": "knip"
+    "knip:all": "knip",
+    "docs:catalog": "node scripts/docs-catalog.mjs",
+    "docs:catalog:check": "node scripts/docs-catalog.mjs --check",
+    "docs:screenshots": "node scripts/docs-screenshots.mjs"
   }
 }

package/skills/dms/REFERENCE.md

@@ -1,44 +1,46 @@
 # dms — reference
 
-Deep material for [SKILL.md](SKILL.md): the map of the DMS's own documentation and the commands
-to look up exact interface surfaces.
+Deep material for [SKILL.md](SKILL.md): the map of the DMS's own documentation and the commands to
+look up exact interface surfaces.
 
 ## The DMS's own documentation
 
-List a section to see its files:
+List a section to see its files. Guide paths below are relative to `packages/dms`; interface reference paths are relative to the repository root.
 
 | Doc | Covers |
 | --- | --- |
 | `docs/01.getting-started/` | Intro, installation, quickstart, tutorial, **architecture**, the built-in dashboard |
-| `docs/02.building/` | Project setup (**the common case**), every config key, pages & components, navigation, actions, backend services (hooks, notifications, realtime, replayable jobs, HTML/email rendering, export jobs), localization, frontend layer & `ajs dms` CLI, distributable modules, deployment, troubleshooting |
+| `docs/02.building/` | Project setup (**the common case**), every config key, pages & components, navigation, actions, backend services, localization, frontend layer & `ajs dms` CLI, distributable modules, deployment, troubleshooting, settings pages |
 | `docs/03.auth-and-tenancy/` | Auth flows (JWT, 2FA, invites), decorators & RBAC, multi-tenant data, SaaS mode |
-| `docs/04.components/` | Component catalog: charts/widgets, layout, forms, tables, DataTypes, DataController, file storage |
-| `docs/05.extending-the-dashboard/` | Dashboard chrome (header actions, command-palette sources and assistant mode, widgets, overlays), theming, custom DataTypes (frontend side), table-view displays, component events, period filtering |
+| `docs/04.components/` | One page per block, grouped: `02.block-fundamentals.md` (nesting, data, composed texts, permissions), `03.layout-and-containers/`, `04.charts-and-widgets/` (+ `6.charts/`, one page per chart type), `05.display-blocks/`, `06.lists-and-settings/`, `07.forms/`, `08.tables/`, `09.custom-component.md`, then DataTypes, DataController, derived controller, file storage |
+| `docs/05.extending-the-dashboard/` | Dashboard chrome, theming, custom DataTypes (frontend side), table-view displays, component events, period filtering |
 | `docs/06.frontend-composables/` | Composables a custom frontend module's Vue calls: auth'd requests, realtime, page context, UI toolkit |
-| `docs/07.interfaces/` | The contract reference for `@antelopejs/interface-dms`, one folder per domain: `core`, `auth`, `base`, `notifications`, `html-render` |
+| `packages/interface-dms/docs/` | The contract reference for `@antelopejs/interface-dms`, one folder per domain: `core`, `auth`, `base`, `notifications`, `html-render` |
+| `docs/08.ai-and-claude-code/` | The skill suite, installing it in Claude Code, dms-ai, best practices, design fidelity, the `/dms-preview` page, shipping a module skill |
 
 ## Exact interface surfaces: don't memorize, look them up
 
 Everything the DMS exposes to a consumer ships in **one** package, `@antelopejs/interface-dms`,
 split into subpaths: `/page`, `/component`, `/permissions`, `/guards`, `/db`, `/hooks`, `/realtime`,
 `/quick-actions`, `/layout-banners`, `/auth` (+ `/auth/db`), `/base` (+ `/base/form`, `/base/table-view`,
-`/base/data-types`, `/base/types`, …), `/notifications`, `/html-render`. There is no separate
-`dms-auth` or `dms-base` interface, and nothing is imported through the runtime package
-`@antelopejs/dms`. Other modules follow the same shape: one `interface-<name>` package per module.
+`/base/data-types`, `/base/block-types`, `/base/types`, …), `/notifications`, `/html-render`.
+Nothing is imported through the runtime package `@antelopejs/dms`. Modules that publish their
+own interface follow the same shape; a UI module does not necessarily have an interface package.
 
 Three ways to read a contract:
 
-1. **The resolver** — the **antelopejs** plugin's script, which fetches a published interface
-   package from npm (honouring `.npmrc`) or reads a local checkout:
+1. **The resolver** — `npx -y github:AntelopeJS/agent-skills interface` (`/antelopejs:interface`
+   when the **antelopejs** plugin is installed), which fetches a published interface package from
+   npm (honouring `.npmrc`) or reads a local checkout:
 
    ```bash
-   node "<antelopejs-plugin>/scripts/resolve-interface.mjs" show @antelopejs/interface-dms
-   node "<antelopejs-plugin>/scripts/resolve-interface.mjs" show <scope>/interface-<name>
+   npx -y github:AntelopeJS/agent-skills interface show @antelopejs/interface-dms
+   npx -y github:AntelopeJS/agent-skills interface show <scope>/interface-<name>
    ```
 
-2. **The prose reference** — `docs/07.interfaces/`, one folder per domain, with the whole subpath
-   map in its `index.md`.
+2. **The prose reference** — `packages/interface-dms/docs/` in this repository, or `docs/` in the
+   installed `@antelopejs/interface-dms` package, with the whole subpath map in `index.md`.
 
-3. **The sources shipped with this skill** — this workspace carries the interface package; read
-   `packages/interface-dms/src/<subpath>` (or the published package's `dist/<subpath>/*.d.ts`)
-   directly for the exact signatures.
+3. **The sources** — in this workspace, `packages/interface-dms/src/<subpath>`; in an installed
+   package, `dist/<subpath>/*.d.ts`. The block catalog (`ListBlockTypes()`) lists every block with
+   its options schema.