@antelopejs/dms 0.0.1

package/frontend-vue/tests/widget-label-i18n.test.ts

@@ -0,0 +1,179 @@
+import { createSSRApp, defineComponent, h, ref, type PropType } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import Chart from "../layers/dms-ui/app/components/chart/Chart.vue";
+import ChartCard from "../layers/dms-ui/app/components/chart/ChartCard.vue";
+import TopListCard from "../layers/dms-ui/app/components/top-list/TopListCard.vue";
+import TopListRow from "../layers/dms-ui/app/components/top-list/internal/TopListRow.vue";
+import { resolveI18nKey } from "../layers/dms-core/app/composables/translation/useTranslation";
+import { CHART_EVENT_NAMES } from "../layers/dms-ui/app/composables/chart/events";
+import type { ChartClickPayload } from "../layers/dms-ui/app/composables/chart/events";
+import type { ChartSeries } from "../layers/dms-ui/app/composables/chart/types";
+
+const MESSAGES: Record<string, string> = {
+  "my_module.sends": "Sends",
+  "my_module.sends_before": "Sends, previous period",
+  "my_module.domain": "Top domain",
+  "my_module.domain_sends": "Sends to this domain",
+};
+
+const LITERAL_TITLE = "example.test";
+const CHART_ID = "plot";
+
+vi.mock("../layers/dms-ui/app/composables/chart/useChartFetch", () => ({
+  useChartFetch: () => ({
+    data: ref({
+      value: 1,
+      series: [{ name: "$my_module.sends", data: [1] }],
+      comparisonSeries: [{ name: "$my_module.sends_before", data: [1] }],
+      items: [
+        {
+          id: "ranked",
+          title: "$my_module.domain",
+          description: "$my_module.domain_sends",
+          sparkline: [1, 2],
+          value: 1,
+          to: "/domains/ranked",
+        },
+        { id: "literal", title: "example.test", value: 0 },
+      ],
+    }),
+    isLoading: ref(false),
+  }),
+}));
+
+const sendComponentEvent = vi.fn();
+
+function stubNuxt() {
+  const translate = (key: string) => MESSAGES[key] ?? key;
+  vi.stubGlobal("useI18n", () => ({ locale: ref("en-US"), t: translate }));
+  vi.stubGlobal("useTranslation", () => ({
+    processI18n: (key: string) => resolveI18nKey(translate, key),
+  }));
+  vi.stubGlobal("useComponentEvent", () => ({ sendComponentEvent }));
+  vi.stubGlobal("useWatch", () => ({ state: ref({}) }));
+}
+
+interface ApexClickOptions {
+  dataPointIndex: number;
+  seriesIndex: number;
+}
+interface ApexProbeOptions {
+  chart: {
+    events?: { dataPointSelection?: (...args: unknown[]) => void };
+  };
+}
+
+/** Renders each series name and fires Apex's click hook so the payload is observable. */
+const SeriesProbe = defineComponent({
+  props: {
+    options: { type: Object as PropType<ApexProbeOptions>, required: true },
+    series: { type: Array as PropType<ChartSeries[]>, required: true },
+  },
+  setup: (props) => () => {
+    const click: ApexClickOptions = { dataPointIndex: 0, seriesIndex: 0 };
+    props.options.chart.events?.dataPointSelection?.(null, null, click);
+    return h(
+      "output",
+      props.series.map((entry) => h("span", { class: "series" }, entry.name)),
+    );
+  },
+});
+
+const Slot = defineComponent({
+  setup:
+    (_, { slots }) =>
+    () =>
+      h("div", slots.default?.()),
+});
+const Link = defineComponent({
+  props: ["to"],
+  setup: () => () => h("a"),
+});
+
+const SLOT_COMPONENTS = [
+  "DmsCard",
+  "DmsClientOnly",
+  "UAvatar",
+  "UBadge",
+  "UIcon",
+  "USkeleton",
+  "DmsSparkline",
+  "DmsTrendBadge",
+];
+
+function mountWidgets(widget: () => ReturnType<typeof h>) {
+  stubNuxt();
+  const app = createSSRApp({ render: widget });
+  for (const name of SLOT_COMPONENTS) app.component(name, Slot);
+  app.component("DmsApexChartHost", SeriesProbe);
+  app.component("DmsTopListRow", TopListRow);
+  app.component("DmsLink", Link);
+  return renderToString(app);
+}
+
+function renderTopList() {
+  return mountWidgets(() =>
+    h(TopListCard, {
+      title: "$my_module.domain",
+      componentId: "list",
+      pageId: "i18n",
+      showSparkline: true,
+    }),
+  );
+}
+
+function renderChartCard(onPointClick: (payload: ChartClickPayload) => void) {
+  return mountWidgets(() =>
+    h(
+      ChartCard,
+      { title: "$my_module.sends", componentId: "card", pageId: "i18n" },
+      () =>
+        h(Chart, {
+          type: "line",
+          componentId: CHART_ID,
+          pageId: "i18n",
+          onPointClick,
+        }),
+    ),
+  );
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  sendComponentEvent.mockClear();
+});
+
+describe("module-supplied widget strings and the $ convention", () => {
+  it("resolves top list row titles, descriptions and aria-labels", async () => {
+    const html = await renderTopList();
+
+    expect(html).toContain("Top domain");
+    expect(html).toContain("Sends to this domain");
+    expect(html).toContain(LITERAL_TITLE);
+    expect(html).not.toContain("$my_module.");
+    expect(html.split('aria-label="Top domain"')).toHaveLength(3);
+  });
+
+  it("resolves chart series names before Apex renders legend and tooltip", async () => {
+    const html = await renderChartCard(() => {});
+
+    expect(html).toContain('class="series">Sends</span>');
+    expect(html).toContain('class="series">Sends, previous period</span>');
+    expect(html).not.toContain("$my_module.");
+  });
+
+  it("carries the resolved series name in the click payload", async () => {
+    let clicked: ChartClickPayload | null = null;
+    await renderChartCard((payload) => {
+      clicked = payload;
+    });
+
+    expect(clicked).toMatchObject({ seriesName: "Sends" });
+    expect(sendComponentEvent).toHaveBeenCalledWith(
+      CHART_EVENT_NAMES.pointClick,
+      CHART_ID,
+      expect.objectContaining({ seriesName: "Sends" }),
+    );
+  });
+});

package/frontend-vue/vitest.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "vitest/config";
+import { resolve } from "node:path";
+import vue from "@vitejs/plugin-vue";
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      "#dms-core": resolve(__dirname, "layers/dms-core"),
+      "#dms-ui": resolve(__dirname, "layers/dms-ui"),
+      "#dms-layout": resolve(__dirname, "layers/dms-layout"),
+    },
+  },
+  esbuild: {
+    tsconfigRaw: "{}",
+  },
+  test: {
+    include: ["tests/**/*.test.ts"],
+  },
+});

package/package.json

@@ -0,0 +1,127 @@
+{
+  "name": "@antelopejs/dms",
+  "version": "0.0.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AntelopeJS/dms.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "frontend-vue",
+    "skills",
+    "package.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "license": "Apache-2.0",
+  "antelopeJs": {
+    "implements": [
+      "@antelopejs/interface-dms"
+    ],
+    "baseUrl": "dist",
+    "test": "src/test/antelope.test.ts",
+    "skills": [
+      "./skills"
+    ]
+  },
+  "dependencies": {
+    "2fa": "^0.1.2",
+    "@antelopejs/core": "^1.4.11",
+    "@antelopejs/interface-api": ">=0.0.13 <1.0.0",
+    "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
+    "@antelopejs/interface-core": "^0.0.12",
+    "@antelopejs/interface-data-api": ">=0.1.9 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.7 <1.0.0",
+    "@antelopejs/interface-database-decorators": ">=0.1.6 <1.0.0",
+    "@antelopejs/interface-email": ">=0.0.5 <1.0.0",
+    "@antelopejs/interface-file-storage": ">=0.1.3 <1.0.0",
+    "archiver": "^7.0.1",
+    "csv-stringify": "^6.7.0",
+    "defu": "^6.1.4",
+    "ignore": "^7.0.5",
+    "jsonwebtoken": "^9.0.3",
+    "node-cron": "^4.2.1",
+    "randomstring": "^1.3.1",
+    "semver": "^7.7.2",
+    "striptags": "^3.2.0",
+    "ua-parser-js": "^2.0.9",
+    "zod": "~3.24.2",
+    "@antelopejs/interface-dms": "0.0.1"
+  },
+  "devDependencies": {
+    "@antelopejs/tooling-configs": "^0.0.4",
+    "@types/archiver": "^6.0.4",
+    "@types/chai": "^4.3.20",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/mocha": "^10",
+    "@types/node": "^24.0.0",
+    "@types/node-cron": "^3.0.11",
+    "@types/randomstring": "^1.3.0",
+    "@types/semver": "^7.7.1",
+    "axios": "^1.7.9",
+    "chai": "^4.5.0",
+    "knip": "^6.34.0",
+    "mongodb": "^7.1.1",
+    "mongodb-memory-server-core": "^11.0.1",
+    "oxfmt": "^0.66.0",
+    "oxlint": "1.81.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "release-it": "^19.2.4",
+    "release-it-changelogen": "^0.1.0",
+    "rimraf": "^6.1.3",
+    "tsc-alias": "^1.9.1",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./pages": {
+      "types": "./dist/pages/index.d.ts",
+      "default": "./dist/pages/index.js"
+    },
+    "./interfaces/*": null
+  },
+  "typesVersions": {
+    "*": {
+      "pages": [
+        "dist/pages/index.d.ts"
+      ]
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "optionalDependencies": {
+    "@antelopejs/interface-dms-automation": ">=0.0.1 <1.0.0",
+    "@antelopejs/interface-redis": ">=0.0.8 <1.0.0"
+  },
+  "scripts": {
+    "build": "pnpm --filter @antelopejs/interface-dms build && rimraf dist && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "format": "oxfmt . && pnpm --dir frontend-vue format",
+    "dev": "ajs project run --inspect -w -p playground",
+    "frontend:dev": "pnpm --dir playground frontend:dev",
+    "lint:fix": "oxlint --fix --max-warnings=1000000 && oxfmt . && pnpm --dir frontend-vue lint:fix",
+    "lint": "oxlint && oxfmt --check . && pnpm --dir frontend-vue lint",
+    "performance:inertia-navigation": "node scripts/check-inertia-navigation.mjs",
+    "check:inertia-runtime": "node scripts/check-inertia-runtime.mjs",
+    "check:inertia-contracts": "node scripts/check-inertia-contracts.mjs",
+    "check:inertia-modules": "node scripts/check-inertia-modules.mjs",
+    "typecheck": "pnpm --filter @antelopejs/interface-dms build && tsc -p tsconfig.json",
+    "check:package": "node scripts/check-package.mjs",
+    "test": "pnpm run build && ajs module test . && pnpm run check:package",
+    "test:unit": "pnpm run build && DMS_TEST_DIR=dist/test/unit ajs module test .",
+    "test:integration": "pnpm run build && DMS_TEST_DIR=dist/test/integration ajs module test .",
+    "test:watch": "tsc -p tsconfig.build.json -w & tsc-alias -p tsconfig.build.json -w",
+    "release": "pnpm --dir frontend-vue install --frozen-lockfile && release-it",
+    "knip": "knip --dependencies",
+    "knip:all": "knip"
+  }
+}

package/skills/dms/REFERENCE.md

@@ -0,0 +1,39 @@
+# 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.
+
+## The DMS's own documentation
+
+List a section to see its files:
+
+| 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/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, tree, DataTypes, DataController, 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 layer's Vue calls: auth'd requests, realtime, page context, UI toolkit |
+
+## Exact interface surfaces: don't memorize, look them up
+
+Three ways to read a contract, depending on how it ships:
+
+1. **Host-package interfaces** — subpaths of this package (`interfaces/<group>`). Use the
+   **antelopejs** plugin's resolver (fetches from npm, honouring `.npmrc`, or a local checkout):
+
+   ```bash
+   node "<antelopejs-plugin>/scripts/resolve-interface.mjs" show dms:base             # the surface
+   node "<antelopejs-plugin>/scripts/resolve-interface.mjs" contract dms:base form    # a part's .d.ts
+   ```
+
+2. **Standalone interface packages** — a module's contract published as its own
+   `interface-*` package. Resolve it by package name (or bare name):
+
+   ```bash
+   node "<antelopejs-plugin>/scripts/resolve-interface.mjs" show <scope>/interface-<name>
+   ```
+
+3. **The sources shipped with this skill** — this package carries its interface sources;
+   read the interface package's `src/` directly.

package/skills/dms/SKILL.md

@@ -0,0 +1,98 @@
+---
+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.
+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 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`, `Tree`, `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; the backend stays the source of truth.
+- **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`.
+
+```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",
+  icon: "i-ph-cooking-pot",
+  category: pagesCategory, // attach under the dashboard's Pages section (the usual anchor)
+}) {
+  static form = Form({
+    title: "Submit a Recipe",
+    fields: [
+      { id: "chef",  label: "Chef Name", type: new DefaultDataTypes.StringType({ maxLength: 100 }) },
+      { id: "email", label: "Email",     type: new DefaultDataTypes.EmailType() },
+    ],
+  });
+}
+```
+
+## Where to go next
+
+| 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 six numbered sections. 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).
+
+## 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:
+
+- **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.

package/skills/dms-auth/SKILL.md

@@ -0,0 +1,105 @@
+---
+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.
+category: security
+tags: [auth, permissions, rbac, users, roles, tenants]
+---
+
+# Auth & permissions
+
+Authentication answers "who is calling"; permissions answer "may they see or do this". Depth:
+`docs/03.auth-and-tenancy/02.auth-and-permissions.md` (gating + RBAC) and
+`01.authentication.md` (shipped flows: JWT rotation, invites, 2FA, recovery). The surface is
+split across `@antelopejs/interface-dms/auth` (identity decorators),
+`@antelopejs/interface-dms/guards` (permission & tenant guards), and `@antelopejs/interface-dms/permissions`
+(permission registry).
+
+## Protecting routes
+
+Auth is applied with **parameter decorators** on controller route methods — each injects the
+resolved user (or rejects if the requirement fails):
+
+```ts
+import { Controller, Get } from "@antelopejs/interface-api";
+import { AuthUser, IfAuthUser } from "@antelopejs/interface-dms/auth";
+import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
+import { User } from "@antelopejs/interface-dms/auth/db";
+
+export class ThingController extends Controller("/api/things") {
+  @Get("")
+  async list(@AuthUser() user: User) { /* requires a logged-in user, else 401 */ }
+
+  @Get("/public")
+  async maybe(@IfAuthUser() user: User | undefined) { /* optional: undefined if anonymous */ }
+
+  @Get("/admin")
+  async admin(@AuthUserWithPermission(SomePageController) user: User) { /* requires permission, else 403 */ }
+}
+```
+
+From `@antelopejs/interface-dms/auth`: `@AuthUser()` (require login), `@IfAuthUser()` (optional), `@AuthRawUser()`,
+`@AuthOwnerOnly()` (platform owner only). From `dms/guards`: `@AuthUserWithPermission(target)`
+(permission tied to a page/component), `@AuthTenantOwner()`, `@AuthTenantMember()`.
+
+**`@IfAuthUser()` does not 401 on an expired token** — it silently treats the caller as
+anonymous and returns a normal 200. If a page must hard-fail for expired sessions (so a
+refresh interceptor fires), use `@AuthUser()` and give anonymous-allowed paths their own
+route. This optional-auth-returns-200 behavior has caused a real token-refresh bug.
+
+## Protecting pages
+
+A page's auth comes from its `PageController` options (see **dms-pages**): `publicAccess:
+true` (no auth), `authOnly: true` (login only), default (login **and** the auto-derived page
+permission), `permission: …` (a specific `Partial<Permission> | Action`),
+`noComponentPermissions: true` (skip per-component permission derivation). Routes under a
+controller that a page or `DataController` wraps **inherit** its auth — don't re-add login
+checks; only add finer ones (ownership, a specific permission).
+
+## Permissions & RBAC
+
+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
+platform **owner** holds everything. **Module pages are special**: prefixed
+`modules.<moduleId>.…`, never grantable in the Roles tree, owner-only regardless of grants.
+
+To contribute a standalone permission, register it in `construct`:
+
+```ts
+import { RegisterPermission } from "@antelopejs/interface-dms/permissions";
+
+RegisterPermission("cookbook.edit", {
+  id: "cookbook.edit",
+  title: "$dms_cookbook.perm.edit",   // i18n key — add to every locale file
+  icon: "i-ph-pencil",
+  defaultGranted: false,
+  // dependencies: ["cookbook.view"],  // declarative metadata only — not enforced or auto-granted
+});
+```
+
+Then gate with `@AuthUserWithPermission(...)` or the page/component permission options. To
+check imperatively, use `dms/permissions`: `GetEffectiveUserPermissions`, `HasPermission`,
+`GetPermission` / `GetPermissions` (`GetUserPermissions` for the base set). Two extension
+points reshape the model: `RegisterPermissionsResolver` (`dms/permissions-resolver`) rewrites
+a user's effective set, and `RegisterTenantAccessGate` (`dms/tenant-access`, checked via
+`CheckTenantAccess` / `AssertTenantAccess`) can block a whole tenant. The `dms/guards`
+decorators also run the tenant access gate; routes that must stay reachable for a denied
+tenant (billing, recovery) opt out with `@AuthTenantOwner({ bypassTenantAccessGate: true })`.
+
+## Users, roles, tenants
+
+Models are exposed as interfaces: `UserModel` and `SessionModel` under
+`@antelopejs/interface-dms/auth/db` (the `User` entity type — what `@AuthUser()` resolves to — lives
+there too); `RoleModel`, `UserInviteModel`, `TenantModel`, `TenantMemberModel` under
+`@antelopejs/interface-dms/db`. Tenant lifecycle events are observable through the DMS hooks — see
+`docs/02.building/06.backend-services.md`.
+
+The DMS is **multi-tenant by default** (single-tenant apps live in the `default` tenant).
+Primitives, covered in `docs/03.auth-and-tenancy/03.multi-tenant.md`: `@TenantScopedModel`
+(`dms/tenant-scoped-model`) scopes a model to the request's tenant, `getRequestTenantId`
+(`dms/request-tenant`) reads it, `applyTenantOwnership`
+(`dms/tenant-ownership`) upserts a user's tenant membership (roles + owner flag),
+`inviteUserToTenant` (`dms/invites`, expiry `INVITE_EXPIRY_DAYS`), and `CROSS_INSTANCE`
+(`@antelopejs/interface-database`) for cross-tenant queries. SaaS mode (Stripe billing,
+public registration, plans gating permissions) is `docs/03.auth-and-tenancy/04.saas-mode.md`.