@antelopejs/dms 0.0.1

package/skills/dms-dev/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: dms-dev
+description: Starts, stops, or restarts the AntelopeJS DMS backend and Inertia frontend.
+category: tooling
+tags: [dev-server, restart, backend, inertia, workflow]
+allowed-tools: Bash(bash:*), Bash(pkill:*), Bash(pgrep:*), Bash(tail:*), Bash(curl:*), Read, Write
+---
+
+# dms-dev
+
+Owns the dev-server lifecycle for an AntelopeJS DMS project. Ships with the
+`@antelopejs/dms` package's skills; the bundled `dms-dev.sh` (in this skill's
+`scripts/` directory) does the work, and this skill tells you how to drive it and how to
+resolve the project path. For authoring see the sibling **dms**, **dms-module**,
+**dms-pages**, and **dms-auth** skills.
+
+## Choose the process manager
+
+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. Inspect readiness with service logs and
+HTTP checks; share the returned portal URL for browser review. The bundled detached-shell
+script is for local shells, not managed orbs: its processes do not survive orb updates.
+
+## Why full restart, not hot reload
+
+The DMS has two coupled processes, both started from the DMS backend package directory:
+
+- **Backend**: the AntelopeJS project — `ajs project dev -w` (`ajs project run` is the legacy alias). Listens on `http://localhost:5010`. Ready when the log emits `Server started, listening on http://localhost:5010`.
+- **Frontend**: the `@antelopejs/dms-frontend` loader — `ajs-dms dev`. It auto-discovers the running backend via `.antelope/dev.json`, so `-b <backend-url>` is optional. Listens on `http://localhost:3001`. Ready when the log emits `Local: http://localhost:3001/`.
+
+By default the script runs each via the project's `pnpm dev` / `pnpm frontend:dev` scripts — a convention our playground projects adopt that expands to the two commands above. Those script names aren't shipped by the DMS, so if a project starts its servers differently, override the actual commands with the `DMS_BACK_CMD` / `DMS_FRONT_CMD` env vars (the script reads them; readiness detection and process cleanup already cover `ajs`, `ajs-dms`, and the loader's Node entry point directly).
+
+Order matters: start the backend first and wait for ready, **then** start the frontend. The frontend materializes the backend's layers into a `~/.antelopejs/dms-frontend/` workspace at startup; starting it before the backend is up produces stale or empty layer copies.
+
+The docs claim dev-mode watchers normally propagate edits (backend `-w` recompile, live layer resync into `~/.antelopejs/dms-frontend/`) — and they often do. But the failure modes are silent: `RegisterModule` can throw "already registered" on rebuild, and a missed resync serves a stale layer copy that *looks* like your bug. The documented troubleshooting recipe — and this skill's contract as an agent — is: **full restart both, backend first, before verifying any change**. A 60-second restart beats debugging a phantom.
+
+## Resolving the backend path (do this FIRST, eagerly)
+
+The script needs `DMS_BACK_DIR` set to the absolute path of the project's DMS backend package directory (the one whose scripts start the AntelopeJS backend and Inertia frontend). Resolve it the **first time this skill loads in a session**.
+
+Resolve in this order:
+
+1. **Inspect the current repository** for `package.json`, `antelope.config.ts`, and service configuration. Use the project they identify when the path is unambiguous.
+2. **Check project memory** for a reference memory named `dms-back-path`. If it exists, verify that the directory still exists and contains a `package.json`; otherwise treat the memory as stale.
+3. **Ask only if 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 future invocations skip the prompt:
+
+   ```markdown
+   ---
+   name: dms-back-path
+   description: Absolute path to the DMS backend package directory for this project, used by the dms-dev skill to run pnpm dev / pnpm frontend:dev.
+   metadata:
+     type: reference
+   ---
+
+   /absolute/path/to/the-backend-package
+   ```
+
+   Also add the index line to `MEMORY.md`: `- [DMS backend path](dms-back-path.md) — where dms-dev runs pnpm dev / pnpm frontend:dev`.
+
+Once resolved, export it for the script invocation:
+`DMS_BACK_DIR=<path> bash "<skill-base-dir>/scripts/dms-dev.sh" <command>`.
+
+## How to invoke
+
+```sh
+DMS_BACK_DIR=<resolved-path> bash "<skill-base-dir>/scripts/dms-dev.sh" restart
+```
+
+`<skill-base-dir>` is this skill's base directory — announced when the skill loads; the
+bundled script lives at `scripts/dms-dev.sh` under it. Subcommands:
+
+| Command           | Use when                                                                |
+|-------------------|-------------------------------------------------------------------------|
+| `restart`         | After any source edit, or unconditionally if you don't know the state.  |
+| `start`           | When you're sure nothing is running (fresh shell / after `stop`).       |
+| `stop`            | Before walking away, before destructive operations, on session cleanup. |
+| `status`          | Quickly check what's running.                                           |
+| `back-log [N]`    | Read the last N (default 60) backend log lines. Use to diagnose boot.   |
+| `front-log [N]`   | Same for the frontend log.                                              |
+
+The script writes the long-running server logs to `/tmp/dms-back.log` and `/tmp/dms-front.log`. The `Bash` tool invocation completes as soon as both servers print their ready strings (or after a 180 s timeout per server — worst case ~6 minutes for a restart; override with `DMS_DEV_TIMEOUT`). The servers themselves keep running detached via `setsid nohup` so they survive the Bash call exiting.
+
+## When to reach for the subcommands
+
+- The user edits any `.ts` or `.vue` file under the DMS backend package or under a DMS module's `src/` or `frontend-vue/` and then wants to test the change live. Run `restart` unconditionally — don't try hot reload.
+- The user says "restart the dms", "restart servers", "reload", or "test it now". Run `restart`.
+- A browser smoke test fails in a way that looks like stale state. Run `restart` before diagnosing.
+- The user asks "is the dms running?". Run `status`.
+- A boot fails (backend never prints "Server started" or frontend never prints "Local:"). Print the relevant `back-log` / `front-log` tail to diagnose; common causes include `RegisterModule … already registered` (a previous stop failed — run `stop` then `restart`), port already in use (kill the listed PID), or a missing dependency (run `pnpm install` in the offending module).
+- **You are handing off to the user for manual testing** (e.g. a plan phase whose acceptance criterion is "user verifies in browser"). Run `restart` yourself first, wait for both ready strings, and only *then* tell the user what to click. Never ask the user to start the servers themselves — that's the whole reason this skill exists.
+
+## Common pitfalls
+
+- **Zombie frontend processes.** The frontend CLI can spawn child processes that survive `pkill ajs`. The script's `stop` does an automatic second-pass kill via `pgrep | xargs kill -9` to catch them. If `start` reports servers already running, run `stop` and check that `status` shows `(none)` before starting again.
+- **Backend exits with "Module already registered".** Means a previous instance is still holding the registration. Run `stop` to clear it, then `restart`.
+- **Frontend's "auth redirect" 302** on `/modules/...` URLs is **normal** — it's the auth-protected admin routes. The frontend layer is loaded correctly even when curl returns 302. Don't restart on this alone; have the user log in.
+- **Don't run `start` or `restart` more than once concurrently** in a single session — the second invocation will hit a port/lock conflict. If multiple background Bash tasks are queued, use the foreground `restart`.
+- **Stale `dms-back-path` memory.** If the saved path no longer exists or the user has switched projects, the script will fail fast with a clear error. Re-prompt the user and overwrite the memory entry.
+- **Stubbornly stale frontend after restarts.** The loader serves layers from physical copies under `~/.antelopejs/dms-frontend/<hash>/`. If a layer edit still doesn't show after a full restart, reset the workspaces with `ajs-dms clean --all` (run in the backend package dir — bare `ajs-dms clean` exits with an error asking 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, exactly like `dev.json`, so a stopped instance leaves one behind whose pid no longer resolves. `restart` rewrites it. If the frontend runs outside the project tree, give it `DMS_BOOTSTRAP_SECRET` explicitly.
+
+## Don't
+
+- Don't try to hot-reload by editing files and refreshing the browser without `restart`. It will work intermittently and waste debugging cycles on phantom issues.
+- Don't `pkill -9 node` — it kills unrelated processes. The script targets specific patterns (`antelope-runner`, `ajs project run|dev`, `ajs-dms dev`, and paths ending in `dms-frontend/dist/index.js dev`).
+- Don't hardcode a backend path into a session. Always resolve via memory-or-prompt so the skill works across projects.
+- Don't ask the user to start or restart the servers themselves before manual testing. You have the script — run it, wait for ready, then hand off. Asking the user to do it defeats the point of the skill and breaks the testing loop.

package/skills/dms-dev/scripts/dms-dev.sh

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+# dms-dev — start / stop / restart the AntelopeJS DMS dev servers.
+# Run from the DMS backend package dir (DMS_BACK_DIR). By default it invokes that project's
+# `pnpm dev` / `pnpm frontend:dev` scripts — a convention our playground projects adopt, which
+# expand to `ajs project dev …` (the AntelopeJS backend; `ajs project run` is the legacy
+# alias) and `ajs-dms dev` (the Inertia frontend loader — it auto-discovers the backend, -b optional).
+# Those script names aren't shipped by the DMS, so override the actual commands with
+# DMS_BACK_CMD / DMS_FRONT_CMD when a project starts its servers differently.
+# Dev watchers cover many edits, but the deterministic recipe when verifying a change is:
+# stop both → start backend → wait for "Server started, listening" → start frontend.
+
+set -uo pipefail
+
+DMS_BACK_DIR="${DMS_BACK_DIR:-}"
+BACK_CMD="${DMS_BACK_CMD:-pnpm dev}"
+FRONT_CMD="${DMS_FRONT_CMD:-pnpm frontend:dev}"
+BACK_LOG="${DMS_BACK_LOG:-/tmp/dms-back.log}"
+FRONT_LOG="${DMS_FRONT_LOG:-/tmp/dms-front.log}"
+BACK_READY_PATTERN='Server started, listening'
+FRONT_READY_PATTERN='Local:.*localhost:'
+# Patterns that indicate a fatal startup error — detecting any of these aborts
+# the wait immediately instead of burning the full timeout.
+BACK_ERROR_PATTERN='Failed to load module|Module load failed|Error loading module|UnhandledPromiseRejection|Cannot find module|ENOENT.*package\.json|TypeError:.*at .*ajs|FATAL'
+FRONT_ERROR_PATTERN='Cannot find module|Failed to compile|Vite error|ENOENT.*package\.json|EADDRINUSE'
+WAIT_TIMEOUT="${DMS_DEV_TIMEOUT:-180}"
+
+PROC_PATTERN='antelope-runner|ajs project (run|dev)|(^|[[:space:]/])ajs-dms dev|dms-frontend/dist/index\.js dev'
+
+log() { printf '[dms-dev] %s\n' "$*"; }
+
+require_dms_back_dir() {
+  if [ -z "$DMS_BACK_DIR" ]; then
+    log "error: DMS_BACK_DIR is not set. Pass it as an env var, e.g.:"
+    log "  DMS_BACK_DIR=/path/to/backend-package $(basename "$0") $1"
+    exit 2
+  fi
+  if [ ! -d "$DMS_BACK_DIR" ]; then
+    log "error: DMS_BACK_DIR=$DMS_BACK_DIR does not exist or is not a directory."
+    exit 2
+  fi
+  if [ ! -f "$DMS_BACK_DIR/package.json" ]; then
+    log "error: DMS_BACK_DIR=$DMS_BACK_DIR has no package.json — not a DMS backend project."
+    exit 2
+  fi
+}
+
+stop_servers() {
+  log "stopping dev servers…"
+  pkill -9 -f "antelope-runner" 2>/dev/null || true
+  pkill -9 -f "ajs project (run|dev)" 2>/dev/null || true
+  pkill -9 -f "(^|[[:space:]/])ajs-dms dev" 2>/dev/null || true
+  pkill -9 -f "dms-frontend/dist/index\.js dev" 2>/dev/null || true
+  sleep 2
+  if pgrep -af "$PROC_PATTERN" >/dev/null 2>&1; then
+    log "warning: some processes are still running, killing again:"
+    pgrep -af "$PROC_PATTERN" | sed 's/^/  /'
+    pgrep -af "$PROC_PATTERN" | awk '{print $1}' | xargs -r kill -9 2>/dev/null || true
+    sleep 2
+  fi
+  if pgrep -af "$PROC_PATTERN" >/dev/null 2>&1; then
+    log "error: could not stop all processes:"
+    pgrep -af "$PROC_PATTERN" | sed 's/^/  /'
+    return 1
+  fi
+  log "stopped."
+}
+
+wait_for() {
+  local log_file="$1" pattern="$2" label="$3" error_pattern="$4" proc_pattern="$5" started
+  started=$(date +%s)
+  # Grace period: pnpm forks/execs into the actual dev process, so pgrep can
+  # legitimately return nothing for the first second or two. Don't treat that
+  # as a failure.
+  local grace_until=$((started + 8))
+  while ! grep -qE "$pattern" "$log_file" 2>/dev/null; do
+    if grep -qE "$error_pattern" "$log_file" 2>/dev/null; then
+      log "FAILED TO START: $label — fatal error detected in $log_file:"
+      grep -nE "$error_pattern" "$log_file" | head -5 | sed 's/^/  /'
+      log "tail of $log_file:"
+      tail -40 "$log_file" | sed 's/^/  /'
+      return 1
+    fi
+    if [ "$(date +%s)" -gt "$grace_until" ] && ! pgrep -f "$proc_pattern" >/dev/null 2>&1; then
+      log "FAILED TO START: $label — process exited before becoming ready. Tail of $log_file:"
+      tail -40 "$log_file" | sed 's/^/  /'
+      return 1
+    fi
+    if [ $(($(date +%s) - started)) -gt "$WAIT_TIMEOUT" ]; then
+      log "FAILED TO START: $label — timed out after ${WAIT_TIMEOUT}s waiting for readiness pattern. Tail of $log_file:"
+      tail -40 "$log_file" | sed 's/^/  /'
+      return 1
+    fi
+    sleep 2
+  done
+  log "$label ready."
+}
+
+start_backend() {
+  require_dms_back_dir start
+  log "starting backend in $DMS_BACK_DIR (logs → $BACK_LOG)…"
+  : > "$BACK_LOG"
+  # shellcheck disable=SC2086  # word-splitting of the command is intentional
+  ( cd "$DMS_BACK_DIR" && setsid nohup $BACK_CMD >> "$BACK_LOG" 2>&1 < /dev/null & )
+  wait_for "$BACK_LOG" "$BACK_READY_PATTERN" "backend (http://localhost:5010)" \
+    "$BACK_ERROR_PATTERN" 'pnpm.*\bdev\b|antelope-runner|ajs project (run|dev)'
+}
+
+start_frontend() {
+  require_dms_back_dir start
+  log "starting frontend in $DMS_BACK_DIR (logs → $FRONT_LOG)…"
+  : > "$FRONT_LOG"
+  # shellcheck disable=SC2086  # word-splitting of the command is intentional
+  ( cd "$DMS_BACK_DIR" && setsid nohup $FRONT_CMD >> "$FRONT_LOG" 2>&1 < /dev/null & )
+  wait_for "$FRONT_LOG" "$FRONT_READY_PATTERN" "frontend (http://localhost:3001)" \
+    "$FRONT_ERROR_PATTERN" 'pnpm.*frontend:dev|(^|[[:space:]/])ajs-dms dev|dms-frontend/dist/index\.js dev'
+}
+
+status() {
+  log "running processes:"
+  if ! pgrep -af "$PROC_PATTERN"; then
+    echo "  (none)"
+  fi
+}
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") <command>
+
+Commands:
+  restart       Stop both servers, start backend, wait, start frontend, wait.
+                Use this after ANY edit to the DMS backend or any DMS module's sources.
+  start         Same as restart but does not stop first (errors if already running).
+  stop          Kill both servers and any zombie processes.
+  status        Show running DMS dev processes.
+  back-log [N]  Tail the last N (default 60) lines of the backend log.
+  front-log [N] Tail the last N (default 60) lines of the frontend log.
+
+Environment:
+  DMS_BACK_DIR    REQUIRED for start/restart. Absolute path to the DMS backend package
+                  directory of the AntelopeJS DMS project to run.
+  DMS_BACK_CMD    Command to start the backend, run in DMS_BACK_DIR (default: "pnpm dev",
+                  the playground convention for "ajs project dev -w" / legacy "run -w").
+  DMS_FRONT_CMD   Command to start the frontend, run in DMS_BACK_DIR (default:
+                  "pnpm frontend:dev", the playground convention for "ajs-dms dev").
+  DMS_BACK_LOG    (default: /tmp/dms-back.log)
+  DMS_FRONT_LOG   (default: /tmp/dms-front.log)
+  DMS_DEV_TIMEOUT (default: 180 seconds per server)
+EOF
+}
+
+cmd="${1:-}"
+case "$cmd" in
+  restart)
+    stop_servers || true
+    if ! start_backend; then
+      log "aborting restart: backend failed to start."
+      exit 1
+    fi
+    if ! start_frontend; then
+      log "aborting restart: frontend failed to start."
+      exit 1
+    fi
+    ;;
+  start)
+    if pgrep -af "$PROC_PATTERN" >/dev/null 2>&1; then
+      log "error: servers already running. Use restart, or stop first."
+      status
+      exit 1
+    fi
+    if ! start_backend; then
+      log "aborting start: backend failed to start."
+      exit 1
+    fi
+    if ! start_frontend; then
+      log "aborting start: frontend failed to start."
+      exit 1
+    fi
+    ;;
+  stop)
+    stop_servers
+    ;;
+  status)
+    status
+    ;;
+  back-log)
+    tail -n "${2:-60}" "$BACK_LOG"
+    ;;
+  front-log)
+    tail -n "${2:-60}" "$FRONT_LOG"
+    ;;
+  ""|-h|--help|help)
+    usage
+    ;;
+  *)
+    usage
+    exit 2
+    ;;
+esac

package/skills/dms-module/REFERENCE.md

@@ -0,0 +1,84 @@
+# dms-module — reference
+
+Deep material for [SKILL.md](SKILL.md): the directory layout, the full `package.json` manifest,
+defining the module's own interface, and the scaffolding checklist.
+
+## Directory layout
+
+One layout that works, not a requirement — mirror the module you copied rather than mixing shapes.
+The **package name is free** (nothing in the framework or DMS keys on it); the official
+first-party modules follow `dms-<name>` purely for discoverability.
+
+```
+<your-module>/
+  src/
+    index.ts                        # entry: construct/start/stop/destroy lifecycle
+    db/                             # schema, models, tables (if it owns data)
+    pages/                          # @RegisterPage classes + category.ts (see dms-pages)
+    routes/                         # HTTP controllers feeding the components
+    interfaces/<name>/index.ts      # the module's OWN interface (rare — many modules ship none)
+    implementations/<name>/index.ts # implementation of that interface
+  frontend-vue/                     # Vue module: dms.frontend.ts, app/, i18n/locales/
+  package.json / tsconfig.json
+```
+
+## The full `package.json` manifest
+
+```jsonc
+{
+  "main": "dist/index.js", "types": "dist/index.d.ts",
+  "antelopeJs": {
+    "baseUrl": "dist",
+    "implements": ["<your-interface-package>"]   // the interface THIS module provides (omit/[] if none)
+  },
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./package.json": "./package.json",
+    // the module's own interface, as an EXPLICIT subpath (only if it defines one):
+    "./interfaces/<name>": {
+      "types": "./dist/interfaces/<name>/index.d.ts",
+      "default": "./dist/interfaces/<name>/index.js"
+    }
+  },
+  "typesVersions": { "*": { "interfaces/<name>": ["dist/interfaces/<name>/index.d.ts"] } }
+}
+```
+
+## 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:
+
+- **Define** in a companion package, `packages/interface-<name>/src/`, **implement** at
+  `src/implementations/<name>/index.ts` in the module, **wire** with `ImplementInterface` in
+  `construct` (the lifecycle entry in [SKILL.md](SKILL.md)). Keep `/** @internal */` on the
+  `internal` namespace — the convention marking the registration surface as non-consumer API.
+- **Expose** each directory index as an explicit `exports` entry, plus the `typesVersions`
+  mapping that lets a consumer on `moduleResolution: node` resolve the types. Consumers add
+  the interface package to `dependencies` and
+  `import { … } from "@antelopejs/interface-<name>"`.
+- Anything consumer-facing lives in the interface package; never re-export internal modules —
+  if a helper needs internal infrastructure, use the hook-setter indirection pattern the
+  existing modules use rather than exposing the internals. Runtime behaviour stays in the
+  module and reaches consumers as an `InterfaceFunction` the module implements, so the
+  contract never drags the module's npm dependencies along.
+
+## Scaffolding checklist
+
+1. **Confirm the path and module id** — the short `id` in `RegisterModule` and pages'
+   `module:` field (e.g. a `dms-cookbook` module would register id `cookbook`). Module pages are **owner-only** (see
+   [SKILL.md](SKILL.md)): confirm an owner/admin area is wanted; end-user screens belong in a project.
+2. **Pick the closest reference shape**: pages + routes, no data or own interface → `dms-lang`
+   (`implements: []`); own data + interface published as `@antelopejs/interface-dms-database` → `dms-database`;
+   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`/`typesVersions`).
+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
+   (**dms**: pnpm only, `_id` rows, no `switch`/`case`, TSDoc-only comments).

package/skills/dms-module/SKILL.md

@@ -0,0 +1,104 @@
+---
+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.
+category: packaging
+tags: [module, packaging, distribution, interfaces, frontend, inertia]
+---
+
+# Building a distributable DMS module
+
+> **Most work on the DMS is a project, not a module.** An app that loads the DMS and registers
+> its own pages wants **dms-project** — not this. This skill is the rarer case: packaging a
+> reusable extension to *ship* to other projects (the way the official `dms-*` modules do).
+> 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
+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
+`package`/`git` module — not as the project's `local` module. The official modules are the
+reference implementations; full walkthrough: `docs/02.building/10.distributable-module.md`.
+See [REFERENCE.md](REFERENCE.md) for the directory layout, the full `package.json` manifest,
+defining the module's own interface, and the scaffolding checklist.
+
+## The `package.json` manifest
+
+The `antelopeJs` block is what makes it a DMS module ([REFERENCE.md](REFERENCE.md) has the full
+manifest, including the `exports`/`typesVersions` entries for an interface subpath).
+`implements` lists only the interfaces the module *provides* — the official modules keep it `[]`
+when they provide none (`dms-lang`, `dms-saas`); consumed interfaces are plain `dependencies`
+(no manifest field). Typical dependencies: `@antelopejs/dms` plus
+`@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.
+
+## The lifecycle entry (`src/index.ts`)
+
+The AntelopeJS loader calls four optional exports. Register everything in `construct`; start
+runtime work in `start`; tear down in `stop`/`destroy`. Side-effect imports (`import "./pages"`)
+run the `@RegisterPage` decorators.
+
+```ts
+import "./db";
+import "./pages";
+import path from "node:path";
+import { ImplementInterface } from "@antelopejs/interface-core";
+import { AddFrontendModule, RegisterModule } from "@antelopejs/interface-dms/page";
+
+export const myModule = RegisterModule({
+  id: "<name>",                       // the module id pages attach to (module: "<name>")
+  title: "$dms_<name>.title",         // i18n key — add it to every locale file
+  description: "$dms_<name>.description",
+  icon: "i-ph-cube",
+  // landingPage: "<page-id>",   defaultCategory: { displayName: "…", icon: "…", order: 0 },
+});
+
+export async function construct(config: Config): Promise<void> {
+  void ImplementInterface(            // wire the module's own interface to its implementation, if any
+    await import("<your-module-package>/interfaces/<name>"),
+    await import("./implementations/<name>"),
+  );
+  AddFrontendModule({
+    name: "<your-module-package>",
+    sourcePath: path.join(__dirname, "../frontend"),
+    renderer: { name: "vue", version: "3" },
+    options: {},
+    privateOptions: {},
+    // priority: -1,                  // negative only to override base-layer components (base sits at 0)
+  });
+}
+
+export async function start(): Promise<void> { /* RegisterSchema("<name>") once the DB is up; cron, caches */ }
+export function stop(): void { /* stop cron, release resources */ }
+export function destroy(): void { /* deactivate subscriptions */ }
+```
+
+`RegisterModule` runs at import time (top level), so the module exists before its pages
+register — it returns the module's root `CategoryInfo`. `AddFrontendModule` is what surfaces the
+module's frontend; without it the module is backend-only.
+
+## Navigation & access — module pages are owner-only
+
+Three constraints are enforced at registration: a page's `category` must **descend from the
+module root** (nest under what `RegisterModule` returned, or rely on `defaultCategory`),
+module pages cannot use the Settings category, and the module must exist before a page names
+it. Pages resolve at `/modules/<moduleId>/<urlSlug>`; entering the module lands on
+`landingPage` if set, else the first page by `order`. Access is **owner-only by design**: the
+Modules group is visible to the platform owner alone (the `*` holder), and the
+`modules.<moduleId>.…` permission ids are module-scoped — never grantable through Roles. On a
+SaaS deployment that means you, the maker, not your customers; a screen for end users belongs
+in a **project** page instead.
+
+## Build, verify, reload
+
+- `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
+  stubbornly stale `~/.antelopejs/dms-frontend` workspaces).
+
+## Scaffolding (no DMS-specific generator)
+
+`ajs module init <path>` scaffolds a **generic** AntelopeJS module shell; nothing generates the
+DMS shape (a companion interface package, `frontend-vue/`, `Dms<Name>` prefix, i18n keys) — follow the
+checklist in [REFERENCE.md](REFERENCE.md), and keep the repo conventions (**dms**:
+pnpm only, `_id` rows, no `switch`/`case`, TSDoc-only comments).

package/skills/dms-pages/REFERENCE.md

@@ -0,0 +1,27 @@
+# dms-pages — reference
+
+Deep material for [SKILL.md](SKILL.md): the full component builder catalog and the DataTypes
+catalog.
+
+## Component builders
+
+Main builders: `Form`; `TableView(controller, options)`; `Tree`; the charts (`ChartLine`,
+`ChartArea`, `ChartBar`, `ChartColumn`, `ChartDonut`, `ChartPie`, `ChartScatter`,
+`ChartMixed`, `ChartRadar`, `ChartRadialBar`, `ChartHeatmap`, `ChartCandlestick`, usually
+inside `ChartCard`); layout `Grid` + `GridRow`, `HStack` / `VStack` / `Spacer`, `Tab`,
+`Placeholder`; dashboard widgets `KpiCard`, `TopListCard`, `PeriodSelector`; 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`.
+
+## DataTypes
+
+A field's `type` is a **DataType instance**: `new DefaultDataTypes.StringType({ … })`. The
+catalog (21 built in, `@antelopejs/interface-dms/base/data-types`): `String`, `Number`, `Date`,
+`Boolean`, `Select`, `Price`, `Percentage`, `Email`, `Color`, `Password`, `Url`, `Phone`,
+`Tree`, `Relation`, `CascaderRelation`, `Address`, `Permissions`, `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
+`@RegisterDataType("id")` (frontend side: `docs/05.extending-the-dashboard/04.custom-data-types.md`).

package/skills/dms-pages/SKILL.md

@@ -0,0 +1,110 @@
+---
+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 / Tree / Chart / Grid builders imported from @antelopejs/interface-dms/base, or choosing DataTypes and wiring the routes and DataControllers that feed them.
+category: dashboard
+tags: [pages, components, forms, tables, data-types, navigation]
+---
+
+# Pages & components
+
+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).
+
+## Declaring a page
+
+A page is a class extending `PageController(id, options)` decorated with `@RegisterPage()`.
+Registration happens at import time — make sure `src/index.ts` imports your pages module.
+
+```ts
+import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
+
+@RegisterPage()
+export class RecipesPage extends PageController("recipes", {
+  displayName: "Recipes",     // sidebar label (use a "$dms_x.y" i18n key in real modules)
+  icon: "i-ph-cooking-pot",   // any iconify name
+  module: "cookbook",         // attach under a RegisterModule'd module by id; can be combined with a category inside the module
+  order: 0,
+}) {}
+```
+
+`options` is the `MenuOptions` shape (`@antelopejs/interface-dms/page`): `displayName`, `icon`,
+`module` and/or `category` (at least one required; a module page's explicit category must
+descend from the module's root), `urlSlug` (defaults to the id), `order`, `description`, `hidden`,
+`type`, plus auth knobs (`publicAccess`, `authOnly`, `permission`, `noComponentPermissions` —
+see **dms-auth**). `Category(id, options)` returns a `CategoryInfo` to pass as a page's
+`category`; `RegisterModule({ id, … })` creates a module root that pages attach to via
+`module: "<id>"`. Module pages live under `MODULE_URL_PREFIX` (`/modules`), e.g.
+`/modules/<moduleId>/<urlSlug>`, and are **owner-only by design** — a screen for regular
+users belongs under `pagesCategory` or a normal `Category`, not under a module.
+
+## Composing components
+
+Each **static field on the page class whose value is a component builder** becomes a named
+component. Builders are fluent; import from `@antelopejs/interface-dms/base` (barrel or subpaths):
+
+```ts
+import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
+import { Form } from "@antelopejs/interface-dms/base/form";
+import { DefaultDataTypes } from "@antelopejs/interface-dms/base/data-types/default-types";
+import { HttpMethod } from "@antelopejs/interface-dms/base/types";
+
+@RegisterPage()
+export class SubmitRecipePage extends PageController("submit-recipe", { displayName: "Submit Recipe", module: "cookbook" }) {
+  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() },
+    ],
+    submitUrl: "/api/recipes",   // a route — often declared on this same class
+    submitUrlMethod: HttpMethod.post,
+  });
+}
+```
+
+The full catalog — `Form`, `TableView`, `Tree`, the charts, layout containers, dashboard
+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`).
+
+## Feeding components with data
+
+Components pull data from URLs; declare routes with the `@antelopejs/interface-api`
+decorators (`Controller`, `Get`, `Post`, `@Parameter`, `@JSONBody`), return a plain object
+for 200 or throw `new HTTPResult(status, body)`. `GetModel(Model)` (from
+`@antelopejs/interface-database-decorators`) gives `get` / `getAll` / `insert` / `update` /
+`delete`. Routes under a controller that a page or DataController wraps **inherit** its auth —
+already gated to logged-in callers (see **dms-auth**).
+
+A **`TableView` is normally backed by a `DataController`**: a class
+`extends DataController(TableClass, TableViewRoutes.All, Controller("/path"))` registered
+with `@RegisterDataController()` (both from `@antelopejs/interface-data-api`).
+`TableViewRoutes` (from `@antelopejs/interface-dms/base/table-view`) provides the presets — `Get`, `List`,
+`Select`, `Count`, `New`, `Edit`, `Delete`, `Archive`, `Restore`, or `All`. Field decorators:
+`@Column` / `@Select` / `@Exported` / `@ArchiveField` / `@Searchable` from `@antelopejs/interface-dms/base` (plus
+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.md`). Database rows carry **`_id`**
+as the primary key — return and type it as `_id`, never alias to `id`.
+
+## DataTypes
+
+A field's `type` is a **DataType instance**: `new DefaultDataTypes.StringType({ … })`; the same
+types drive TableView columns and filters. See [REFERENCE.md](REFERENCE.md) for the catalog of
+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
+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.