@antelopejs/dms 0.9.2 → 0.9.3

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`.

package/skills/dms-project/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: dms-project
-description: Sets up an AntelopeJS project that uses the DMS, including its Inertia frontend module and lifecycle.
+description: Sets up and runs an AntelopeJS project that uses the DMS — template, `antelope.config.ts`, the `src/index.ts` lifecycle, `AddFrontendModule`, or the embedded mode of an AdonisJS app that calls `createRuntime` — and starts, stops or restarts its backend and frontend dev servers with a bundled script. Use when creating or configuring a DMS app, wiring or adding the modules it loads (including in an AdonisJS or other host app), running or restarting the dev servers, reading their logs, or when a change does not show live.
+icon: i-ph-folder-simple-plus
 category: setup
-tags: [project, setup, config, lifecycle, frontend, inertia]
+tags: [project, setup, config, lifecycle, dev-server, restart]
+allowed-tools: Bash(bash:*), Bash(pgrep:*), Bash(tail:*), Bash(curl:*), Read, Write
 ---
 
-# Building a project on the DMS
+# Setting up and running a DMS project
 
 This is the **most common** way to use the DMS: a normal AntelopeJS **project** (an app) that loads
 the DMS as a dependency and registers *its own* admin pages, data, and logic — rather than a
 distributable DMS module (to ship a reusable extension instead, see **dms-module** — same APIs,
 different packaging). For the model see **dms**; for `ajs` CLI / module-loading mechanics
-the **antelopejs** plugin; full walkthrough: `docs/02.building/01.project-setup.md`.
+the **ajs-cli** skill; full walkthrough: `docs/02.building/01.project-setup.md`.
 
 ## Starting a new application
 
@@ -19,9 +21,14 @@ Use [template-dms-demo](https://github.com/AntelopeJS/template-dms-demo) for the
 CLI-owned backend and Nuxt dashboard. Follow `docs/01.getting-started/03.quickstart.md`
 through first-admin setup before adding pages. Use
 [template-dms-adonis](https://github.com/AntelopeJS/template-dms-adonis) only when
-AdonisJS must own the process. Evaluate these existing templates before proposing another.
+AdonisJS must own the process (**embedded** mode, below; walkthrough:
+`docs/01.getting-started/07.adonisjs.md`). Evaluate these existing templates before proposing another.
 
-Preserve the package names declared by the template.
+Preserve the package names declared by the template. Both templates ship `.claude/settings.json`, which makes Claude Code offer the
+**antelopejs** plugin; elsewhere, install it once with `claude plugin marketplace add
+AntelopeJS/agent-skills` and `claude plugin install antelopejs@antelopejs`. In Codex, run
+`codex plugin marketplace add AntelopeJS/agent-skills` and `codex plugin add antelopejs@antelopejs`, and
+sync the skills with `npx -y github:AntelopeJS/agent-skills sync --target codex`.
 
 ## What a project is
 
@@ -65,6 +72,34 @@ both; remaining DMS keys: `docs/02.building/02.configuration.md`. Optional infra
 file storage, email), the standalone `data-api` note, and `envOverrides` / `environments` are in
 [REFERENCE.md](REFERENCE.md).
 
+## Embedded mode (AdonisJS and other host apps)
+
+Everything above and below describes **standalone** mode, where the `ajs` CLI owns the process. In
+**embedded** mode a host application owns it and starts the runtime itself. Recognize it before
+you run any `ajs project` command: the project has **no `antelope.config.*`**, depends on
+`@antelopejs/core`, and a host file calls `createRuntime(...)` from it — in template-dms-adonis,
+`providers/antelope_provider.ts`, an AdonisJS provider that starts the runtime in `start()` and stops
+it in `shutdown()`.
+
+- **The module list is code.** Each module is a key of the `modules` map passed to `createRuntime`,
+  with its options under `config` (read from AdonisJS's `env`, not `envOverrides` / `environments`).
+- **Adding a module** (e.g. `@antelopejs/dms-lang`): `pnpm add` the package (modules resolve from
+  the app's `node_modules`, or a local path — not the `~/.antelopejs` cache), add
+  `'@antelopejs/dms-lang': {}` to the `modules` map, restart `pnpm dev`, then rebuild the dashboard
+  with `pnpm frontend:build` and restart `pnpm frontend:start`. Never `ajs project modules add`:
+  no `ajs project …` command applies here.
+- **No `ajs dms dev`.** The embedded runtime forces `dev: false`, so the DMS does not publish the
+  layer source paths the hot-reload server needs. The dashboard runs from `pnpm frontend:build` +
+  `pnpm frontend:start` (`:3001`), rebuilt after a module is added or removed; it reads
+  `DMS_BOOTSTRAP_SECRET` (the DMS `frontend.bootstrapSecret`) and `DMS_SESSION_SECRET` from `.env`.
+- **Separate API port.** `@antelopejs/api` listens on its own port (`DMS_API_PORT`, `5010`), not in
+  the AdonisJS server (`3333`), and needs `publicBaseUrl`.
+- **Host code calls `runtime.use()`**, never an `@antelopejs/interface-*` import (the template's
+  `GET /dms/info` route shows it). The `src/index.ts` lifecycle below applies to standalone projects.
+
+Mechanism and limitations: the framework's embedded runtime guide
+(<https://framework.antelopejs.com/docs/guides/embedded-runtime>).
+
 ## The project lifecycle (`src/index.ts`)
 
 Your project is a module with the standard lifecycle. `construct(config)` gets the `local` config;
@@ -109,13 +144,66 @@ and custom Vue → the doc map in [REFERENCE.md](REFERENCE.md). Pages usually at
 under the built-in `pagesCategory` (`RegisterModule` is for distributable modules). DB models use
 `@antelopejs/interface-database-decorators`; routes use `@antelopejs/interface-api`.
 
-## Running
+## Running the dev servers
+
+A standalone DMS project runs two coupled processes, both started from the project's DMS backend
+package directory (embedded mode: `pnpm dev`, then build + start the dashboard, as above — the
+script below does not apply):
+
+- **Backend**: `ajs project dev -w` (`ajs project run` is the legacy alias; `-e STAGING` picks an
+  environment). Ready when its log prints `Server started, listening on <url>`;
+  `.antelope/dev.json` records the real endpoint (`http://localhost:5010` by default). Projects
+  often start Mongo / Redis in Docker first (`docker-compose up -d`).
+- **Frontend**: the `@antelopejs/dms-frontend` loader, `ajs dms dev`. It finds the running backend
+  through `.antelope/dev.json`, so `-b <apiBaseUrl>` is optional. Ready when its log prints
+  `Dev server ready` and a `Local: <url>` line (`http://localhost:3001` by default).
+
+Start the backend first and wait for its ready line, **then** the frontend: the loader copies the
+backend's layers into `~/.antelopejs/dms-frontend/` at startup, and a frontend started too early
+serves stale or empty copies. Every `ajs dms` command and flag, a frontend module's files, and
+building or deploying the frontend server belong to the **dms-frontend** skill (shipped by
+`@antelopejs/dms-frontend`); production is `docs/02.building/11.deployment.md`.
+
+### Never from inside the DMS
+
+An agent running inside the DMS (the dms-ai assistant, whose sidecar the backend spawns, or any
+process these dev servers started) **leaves the servers running**: stopping the backend takes the
+agent down with it. It relies on hot reload and, when a change needs a full restart, asks the user
+to run it. The script refuses to stop a process tree that contains its calling shell.
 
-- Backend: `ajs project dev -w` (`ajs project run` is the legacy alias; `-e STAGING` picks an
-  environment). Projects often start Mongo/Redis in Docker first (`docker-compose up -d`).
-- Frontend: the `@antelopejs/dms-frontend` loader, `ajs dms dev` — auto-discovers the running
-  backend via `.antelope/dev.json`, so `-b <apiBaseUrl>` is optional.
+### Hot reload first, restart when it cannot apply
+
+The watchers propagate most edits (backend `-w` recompile, live layer resync). Restart only when
+hot reload cannot apply the change: a new module or dependency, a config edit, a backend log
+showing a failed rebuild, or a behaviour still stale after the watcher reported the rebuild
+(`RegisterModule` "already registered", a layer edit not showing). Then restart both, backend
+first.
+
+### Drive the bundled script
+
+`scripts/dms-dev.sh` (under this skill's base directory, announced when the skill loads) does the
+work. It needs `DMS_BACK_DIR`, the absolute path of the DMS backend package directory: take it from
+the current repository when `package.json` and `antelope.config.ts` make it unambiguous, otherwise
+follow [DEV-SERVERS.md](DEV-SERVERS.md#resolve-the-backend-path).
+
+```sh
+DMS_BACK_DIR=<resolved-path> bash "<skill-base-dir>/scripts/dms-dev.sh" restart
+```
 
-The `pnpm dev` / `frontend:dev` script names are **your project's conventions** — they expand to
-`ajs project dev` and `ajs dms dev`. Whenever a change doesn't show (or you're about to verify one),
-full-restart both, backend first — see **dms-dev**. Production: `docs/02.building/11.deployment.md`.
+| Command | Use when |
+| --- | --- |
+| `restart` | Hot reload cannot apply a change, or the state is unknown. |
+| `start` | Nothing is running (fresh shell, after `stop`). |
+| `stop` | Before walking away, before destructive operations, on session cleanup. |
+| `status` | The user asks whether the DMS is running. |
+| `back-log [N]` / `front-log [N]` | A boot fails: read the last N (default 60) lines of `/tmp/dms-back.log` / `/tmp/dms-front.log`. |
+
+The call returns once both servers print their ready line and reports the URLs they listen on; it
+fails fast when a server exits early, otherwise after 180 s per server (`DMS_DEV_TIMEOUT`). The
+servers keep running detached. By default the script runs the project's `pnpm dev` and
+`pnpm frontend:dev` scripts (a project convention that expands to the two commands above);
+override them with `DMS_BACK_CMD` / `DMS_FRONT_CMD`.
+
+When you hand off for manual testing, run `restart` yourself, wait for both ready lines, then tell
+the user what to click. Boot failures, stale frontends, a refused credential (401), stop scope and
+managed environments (Amp orbs): [DEV-SERVERS.md](DEV-SERVERS.md).

package/dist/test/antelope.test.d.ts

@@ -1,2 +0,0 @@
-declare const _default: import("@antelopejs/interface-core/config").ConfigInput;
-export default _default;

package/dist/test/antelope.test.js

@@ -1,148 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const promises_1 = require("node:fs/promises");
-const node_os_1 = require("node:os");
-const node_path_1 = require("node:path");
-const config_1 = require("@antelopejs/interface-core/config");
-const mongodb_memory_server_core_1 = require("mongodb-memory-server-core");
-const ANY_FREE_PORT = 0;
-const UNUSED_PUBLIC_BASE_URL = "https://api.test.example.com";
-const API_LOCAL_BASE_URL = "${@api.API_LOCAL_BASE_URL}";
-const JWT_SECRET = "test-jwt-secret";
-const BOOTSTRAP_SECRET = "test-bootstrap-secret";
-const MONGO_BINARY_VERSION = "8.0.8";
-const LOCAL_API_PATH = process.env.DMS_TEST_API_PATH;
-const LOCAL_MONGODB_PATH = process.env.DMS_TEST_MONGODB_PATH;
-const LOCAL_STORAGE_PATH = process.env.DMS_TEST_STORAGE_PATH;
-const LOCAL_INSTALL_COMMAND = process.env.DMS_PREBUILT ? [] : ["pnpm build"];
-function providerSource(path, packageName, version) {
-    if (path) {
-        return {
-            type: "local",
-            path,
-            installCommand: ["pnpm build"],
-        };
-    }
-    return { type: "package", package: packageName, version };
-}
-let mongod;
-let storageDir;
-exports.default = (0, config_1.defineConfig)({
-    name: "dms-test",
-    cacheFolder: ".antelope/cache",
-    logging: {
-        channelFilter: {
-            "*": "warn",
-        },
-    },
-    modules: {
-        local: {
-            source: {
-                type: "local",
-                path: ".",
-                installCommand: LOCAL_INSTALL_COMMAND,
-            },
-            config: {
-                auth: {
-                    jwtSecret: JWT_SECRET,
-                },
-                frontend: {
-                    bootstrapSecret: BOOTSTRAP_SECRET,
-                },
-            },
-        },
-        "attachment-host": {
-            source: {
-                type: "local",
-                path: "src/test/attachment-host",
-            },
-        },
-        "reload-host": {
-            source: {
-                type: "local",
-                path: "dist/test/reload-host",
-            },
-        },
-        "api-endpoint": {
-            source: {
-                type: "local",
-                path: "src/test/api-endpoint",
-            },
-            config: {
-                apiBaseUrl: API_LOCAL_BASE_URL,
-            },
-        },
-        mongodb: {
-            source: providerSource(LOCAL_MONGODB_PATH, "@antelopejs/mongodb", "1.4.2"),
-        },
-        "auth-jwt": {
-            source: {
-                type: "package",
-                package: "@antelopejs/auth-jwt",
-                version: "1.0.3",
-            },
-            config: {
-                secret: JWT_SECRET,
-            },
-        },
-        api: {
-            source: providerSource(LOCAL_API_PATH, "@antelopejs/api", "^1.3.0"),
-            config: {
-                publicBaseUrl: UNUSED_PUBLIC_BASE_URL,
-                servers: [{ protocol: "http", host: "127.0.0.1", port: ANY_FREE_PORT }],
-            },
-        },
-        "file-storage-local": {
-            source: providerSource(LOCAL_STORAGE_PATH, "@antelopejs/file-storage-local", "0.1.5"),
-        },
-        nodemailer: {
-            source: {
-                type: "package",
-                package: "@antelopejs/nodemailer",
-                version: "0.0.5",
-            },
-            config: {
-                ethereal: true,
-            },
-        },
-    },
-    test: {
-        folder: process.env.DMS_TEST_DIR ?? "dist/test",
-        async setup() {
-            mongod = await mongodb_memory_server_core_1.MongoMemoryReplSet.create({
-                replSet: { count: 1 },
-                binary: { version: MONGO_BINARY_VERSION },
-            });
-            storageDir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "dms-test-storage-"));
-            const mongoUrl = mongod.getUri();
-            process.env.TEST_MONGO_URL = mongoUrl;
-            process.env.TEST_JWT_SECRET = JWT_SECRET;
-            process.env.TEST_BOOTSTRAP_SECRET = BOOTSTRAP_SECRET;
-            return {
-                modules: {
-                    mongodb: {
-                        config: { url: mongoUrl, database: "dms-core" },
-                    },
-                    "file-storage-local": {
-                        config: {
-                            storagePath: storageDir,
-                            baseUrl: API_LOCAL_BASE_URL,
-                            defaultVisibility: "private",
-                        },
-                    },
-                },
-            };
-        },
-        async cleanup() {
-            try {
-                if (mongod)
-                    await mongod.stop();
-            }
-            finally {
-                if (storageDir)
-                    await (0, promises_1.rm)(storageDir, { recursive: true, force: true });
-            }
-        },
-    },
-});
-//# sourceMappingURL=antelope.test.js.map

package/dist/test/antelope.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"antelope.test.js","sourceRoot":"","sources":["../../src/test/antelope.test.ts"],"names":[],"mappings":"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"}

package/dist/test/api-endpoint/index.d.ts

@@ -1,5 +0,0 @@
-interface ApiEndpointConfig {
-    apiBaseUrl: string;
-}
-export declare function construct(config: ApiEndpointConfig): void;
-export {};