@antelopejs/interface-dms-builder 0.4.0 → 0.5.0

package/dist/table-view.d.ts

@@ -1,32 +1,54 @@
 import type { BlockPath } from "./addressing";
 import type { MutationOpts, OpResult } from "./results";
+/** The displays a table page can offer: the grid, a board, a card per row, rows under group headers. */
 export type TableDisplayId = "table" | "kanban" | "cards" | "grouped";
+/**
+ * A board of cards, one column per value of a single-choice column: a select that is not
+ * multiple, a boolean or a status.
+ */
 export interface KanbanSetting {
+    /** A single-choice column of the table. */
     groupBy: string;
+    /** Cards move between columns by drag and drop. Default true. */
     draggable?: boolean;
 }
+/** The grid with a header row per group of rows. */
 export interface GroupedSetting {
+    /** A sortable column of the table. `day` and `week` need a date column. */
     groupBy: string;
     by?: "value" | "day" | "week";
+    /** A click on a group header folds its rows. */
     collapsible?: boolean;
+    /** Group headers show how many rows they hold; needs a filterable `groupBy`. */
     count?: boolean;
 }
+/** A card per row: its title, then these columns. */
 export interface CardsSetting {
+    /** Listable columns of the table shown under the card's title; the first few when left out. */
     fields?: string[];
 }
+/** How a view compares a column with its value. */
 export type ViewFilterMode = "is" | "is_not" | "include" | "exclude" | "contains" | "not_contains" | "greater_than" | "less_than" | "greater_than_or_equal_to" | "less_than_or_equal_to" | "is_empty" | "is_not_empty";
+/** One filter of a view. A value may hold the tokens `{{user.id}}`, `{{now}}` and `{{now-7d}}`. */
 export interface ViewFilterSetting {
+    /** A filterable column of the table. */
     column: string;
+    /** Default `is`. */
     mode?: ViewFilterMode;
+    /** A list is joined with commas. Not needed for `is_empty` and `is_not_empty`. */
     value?: string | string[];
 }
+/** A named state of the table: the rows and the way they are drawn. */
 export interface ViewSetting {
+    /** Stable, lower-case, used in the URL: `late-orders`. */
     id: string;
     label: string;
     icon?: string;
+    /** Shows how many rows the view lists. */
     count?: boolean;
     filters?: ViewFilterSetting[];
     search?: string;
+    /** The rows are sorted on the first entry. Sortable columns only. */
     sort?: {
         column: string;
         desc?: boolean;
@@ -36,39 +58,66 @@ export interface ViewSetting {
         hidden?: string[];
         order?: string[];
     };
+    /** One of the displays the table offers. */
     display?: TableDisplayId;
     density?: "default" | "compact";
 }
+/** The named views of a table. */
 export interface ViewsSetting {
     items: ViewSetting[];
+    /** Where the views are drawn. Default `tabs`. */
     layout?: "tabs" | "strip" | "menu";
+    /** The id of the view opened on arrival. */
     defaultView?: string;
+    /** Users may save the current state as a view of their own. */
     userViews?: boolean;
 }
+/** A figure of the footer band, computed over every row the table's filters list. */
 export interface FooterSummarySetting {
+    /** Shown before the figure: `Total`. */
     label: string;
+    /** `sum` adds up a number or price column; `count` counts the rows. */
     op: "sum" | "count";
+    /** The column summed. Required by `sum`. */
     field?: string;
+    /** Only the rows where `column` compares to `value` are summed or counted. */
     where?: {
         column: string;
         op: "equals" | "notEquals" | "in" | "notIn";
         value: string | number | boolean | (string | number | boolean)[];
     };
 }
+/** The footer band of a table. */
 export interface FooterSetting {
+    /** Replaces the footer's figures. An empty list removes them. */
     summary?: FooterSummarySetting[];
 }
+/**
+ * What to set on a table page. A key left out is left as the page has it; `null` removes it.
+ * Column names are the controller's, as `GetResourceStructure` lists them.
+ */
 export interface TableViewSettings {
     kanban?: KanbanSetting | null;
     grouped?: GroupedSetting | null;
+    /** Offers the cards display. `null` stops offering it. */
     cards?: CardsSetting | null;
+    /** The display shown first, one the table offers. `null` goes back to the first offered. */
     defaultDisplay?: TableDisplayId | null;
     views?: ViewsSetting | null;
     footer?: FooterSetting | null;
 }
+/** Options for `ConfigureTableView`. */
 export interface ConfigureTableViewOpts extends MutationOpts {
+    /** The name of the TableView block when the page holds several. */
     block?: string;
 }
+/**
+ * Sets displays, named views and footer figures on the TableView of a page, checking each
+ * against the columns of the table it reads: a kanban needs a single-choice column, a sum a
+ * number or price column, a view's filters filterable columns and its sort sortable ones. A
+ * footer figure also mounts the controller's summary route when it does not serve it. Nothing
+ * is written when a choice is refused, or when the page would not typecheck.
+ */
 export declare const ConfigureTableView: (page: string, settings: TableViewSettings, opts?: ConfigureTableViewOpts | undefined) => Promise<OpResult<{
     path: BlockPath;
 }>>;

package/dist/table-view.js

@@ -2,5 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConfigureTableView = void 0;
 const interface_core_1 = require("@antelopejs/interface-core");
+/**
+ * Sets displays, named views and footer figures on the TableView of a page, checking each
+ * against the columns of the table it reads: a kanban needs a single-choice column, a sum a
+ * number or price column, a view's filters filterable columns and its sort sortable ones. A
+ * footer figure also mounts the controller's summary route when it does not serve it. Nothing
+ * is written when a choice is refused, or when the page would not typecheck.
+ */
 exports.ConfigureTableView = (0, interface_core_1.InterfaceFunction)();
 //# sourceMappingURL=table-view.js.map

package/dist/table-view.js.map

@@ -1 +1 @@
-{"version":3,"file":"table-view.js","sourceRoot":"","sources":["../src/table-view.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA2IlD,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAMd,CAAC"}
+{"version":3,"file":"table-view.js","sourceRoot":"","sources":["../src/table-view.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAoI/D;;;;;;GAMG;AACU,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAMd,CAAC"}

package/dist/theme.d.ts

@@ -0,0 +1,144 @@
+import type { MutationOpts, OpResult } from "./results";
+/** The two color modes a theme value can be set for. */
+export type ThemeMode = "light" | "dark";
+/** CSS custom properties by name: `{ "--ui-bg": "#fafafa" }`. */
+export type ThemeVariables = Record<string, string>;
+/**
+ * The CSS custom properties a theme overrides: those both modes share, and
+ * those set for one mode only.
+ *
+ * A variable left out keeps the DMS default, so a theme only holds what it
+ * changes. A shared value, such as the font or the corner radius, applies to
+ * both modes unless a mode sets its own.
+ */
+export interface ThemeVariableSets {
+    shared: ThemeVariables;
+    light: ThemeVariables;
+    dark: ThemeVariables;
+}
+/** The Nuxt UI color roles a theme picks a palette for. */
+export type ThemeColorRole = "primary" | "success" | "warning" | "error" | "info";
+/**
+ * The palette each role takes, by name: a Tailwind palette (`violet`), or one
+ * the project's stylesheets declare (`brand` for `--color-brand-50…950`). A
+ * role left out keeps the DMS palette.
+ */
+export type ThemeColors = Partial<Record<ThemeColorRole, string>>;
+/** Where the dashboard shows a logo. */
+export type LogoSlot = "default" | "collapsed" | "email" | "favicon";
+/** Public paths, as the browser requests them: `/branding/logo.svg`. */
+export type LogoPathsByMode = Partial<Record<ThemeMode, string>>;
+/** A slot or a mode left out keeps the DMS logo. */
+export type ThemeLogos = Partial<Record<LogoSlot, LogoPathsByMode>>;
+/** A logo file sent with a save, for one slot in one color mode. */
+export interface LogoUpload {
+    slot: LogoSlot;
+    mode: ThemeMode;
+    /**
+     * `image/svg+xml`, `image/png`, `image/jpeg`, `image/webp`, or
+     * `image/x-icon` (also as `image/vnd.microsoft.icon`). The `email` slot
+     * takes `image/png` or `image/jpeg` only, the formats every mail client
+     * shows.
+     */
+    contentType: string;
+    base64Content: string;
+}
+/** The project's frontend layer a theme is read from and written to. */
+export interface ThemeLayer {
+    name: string;
+    /** Absolute path of the layer's source directory. */
+    sourcePath: string;
+}
+/**
+ * The files a theme lives in, relative to the layer's source directory. All
+ * but the entry are under the directory the DMS frontend loader reads them
+ * from: the layer itself, or the last of its `layers/` by name when it has
+ * that directory.
+ */
+export interface ThemeFiles {
+    /** The unlayered stylesheet holding the variables. */
+    stylesheetPath: string;
+    /** The app config holding `ui.colors` and `branding.logo`. */
+    appConfigPath: string;
+    /** The layer's entry, which imports the stylesheet. */
+    entryPath: string;
+    /**
+     * Where uploaded logos are written, under the theme's `public/`, and the
+     * files of the fonts it hosts, in its `fonts/`.
+     */
+    assetsDirectory: string;
+}
+/** A project's theme as its files hold it. */
+export interface ThemeStructure {
+    layer: ThemeLayer;
+    variables: ThemeVariableSets;
+    colors: ThemeColors;
+    logos: ThemeLogos;
+    files: ThemeFiles;
+    /**
+     * Whether the layer's entry already imports the stylesheet. If not, the
+     * first save adds the import, and the development server then reloads the
+     * whole page.
+     */
+    stylesheetImported: boolean;
+    /**
+     * Hash of the stylesheet, app config and entry (not the logo files) → pass
+     * back as `expectedVersion`.
+     */
+    version: string;
+}
+/**
+ * A theme as it should be written: the whole of it, replacing the one on disk.
+ *
+ * An upload replaces whatever `logos` says for its slot and mode, since the
+ * server names the file after a hash of its (sanitized) content.
+ */
+export interface ThemeDraft {
+    variables: ThemeVariableSets;
+    colors: ThemeColors;
+    logos: ThemeLogos;
+    uploads?: LogoUpload[];
+}
+/**
+ * The project's theme, read from its frontend layer.
+ *
+ * The layer is the highest-priority frontend module registered from inside the
+ * project root, unless the module config names one. Fails with:
+ * - `not_found` when the project has no layer, its `ref` naming where
+ *   `CreateThemeLayer` would create it; or when the layer's entry file is
+ *   missing, its `ref` naming that file (`CreateThemeLayer` does not fix it);
+ * - `unsupported` when the stylesheet holds rules the builder does not write,
+ *   or when the layer has a `layers/` directory with no layer in it.
+ */
+export declare const GetTheme: () => Promise<OpResult<ThemeStructure>>;
+/**
+ * Write a theme: its stylesheet, `ui.colors` and the logo paths of its app
+ * config, the logo files, and the entry's import of the stylesheet when it
+ * lacks one. One transaction: every file is checked before any is written.
+ *
+ * A variable whose value starts with a font the builder hosts
+ * (`--font-sans: "Inter", sans-serif`) gets that font's files, downloaded
+ * once from Fontsource, and its `@font-face` rules in the stylesheet; one the
+ * theme no longer uses is deleted. A download that fails is refused with
+ * `unsupported`, nothing written.
+ *
+ * SVG logos are written sanitized; the save warns (`svg_sanitized`) when that
+ * removed anything that runs or fetches. A palette or a logo path the
+ * builder cannot rewrite (anything but a string literal, or any key of an
+ * object with a spread) is kept as written; a draft that changes one is
+ * refused with `unsupported`, naming its key path. A draft not shaped like
+ * `ThemeDraft` is refused with `invalid_config`.
+ */
+export declare const SetTheme: (draft: ThemeDraft, opts?: MutationOpts | undefined) => Promise<OpResult<{
+    version: string;
+}>>;
+/**
+ * Create the frontend layer a theme is written to, for a project without one:
+ * `frontend-vue/` at the project root, with an entry importing the stylesheet,
+ * registered from the project's `start()` above the DMS. A project that
+ * already has a layer gets it back unchanged, and nothing is written.
+ *
+ * The backend reloads with the registration; the frontend dev server reads
+ * its frontend modules at startup, so it needs a restart to serve the layer.
+ */
+export declare const CreateThemeLayer: () => Promise<OpResult<ThemeLayer>>;

package/dist/theme.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateThemeLayer = exports.SetTheme = exports.GetTheme = void 0;
+const interface_core_1 = require("@antelopejs/interface-core");
+/**
+ * The project's theme, read from its frontend layer.
+ *
+ * The layer is the highest-priority frontend module registered from inside the
+ * project root, unless the module config names one. Fails with:
+ * - `not_found` when the project has no layer, its `ref` naming where
+ *   `CreateThemeLayer` would create it; or when the layer's entry file is
+ *   missing, its `ref` naming that file (`CreateThemeLayer` does not fix it);
+ * - `unsupported` when the stylesheet holds rules the builder does not write,
+ *   or when the layer has a `layers/` directory with no layer in it.
+ */
+exports.GetTheme = (0, interface_core_1.InterfaceFunction)();
+/**
+ * Write a theme: its stylesheet, `ui.colors` and the logo paths of its app
+ * config, the logo files, and the entry's import of the stylesheet when it
+ * lacks one. One transaction: every file is checked before any is written.
+ *
+ * A variable whose value starts with a font the builder hosts
+ * (`--font-sans: "Inter", sans-serif`) gets that font's files, downloaded
+ * once from Fontsource, and its `@font-face` rules in the stylesheet; one the
+ * theme no longer uses is deleted. A download that fails is refused with
+ * `unsupported`, nothing written.
+ *
+ * SVG logos are written sanitized; the save warns (`svg_sanitized`) when that
+ * removed anything that runs or fetches. A palette or a logo path the
+ * builder cannot rewrite (anything but a string literal, or any key of an
+ * object with a spread) is kept as written; a draft that changes one is
+ * refused with `unsupported`, naming its key path. A draft not shaped like
+ * `ThemeDraft` is refused with `invalid_config`.
+ */
+exports.SetTheme = (0, interface_core_1.InterfaceFunction)();
+/**
+ * Create the frontend layer a theme is written to, for a project without one:
+ * `frontend-vue/` at the project root, with an entry importing the stylesheet,
+ * registered from the project's `start()` above the DMS. A project that
+ * already has a layer gets it back unchanged, and nothing is written.
+ *
+ * The backend reloads with the registration; the frontend dev server reads
+ * its frontend modules at startup, so it needs a restart to serve the layer.
+ */
+exports.CreateThemeLayer = (0, interface_core_1.InterfaceFunction)();
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAyH/D;;;;;;;;;;GAUG;AACU,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAA2C,CAAC;AAE/D;;;;;;;;;;;;;;;;;GAiBG;AACU,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAKd,CAAC;AAEN;;;;;;;;GAQG;AACU,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAAuC,CAAC"}

package/dist/values.d.ts

@@ -1,22 +1,86 @@
+/**
+ * Config values (`AddBlockInput.config`, `ConfigureBlock` patches) are plain
+ * JSON by default. Two sentinel object shapes emit non-literal TypeScript:
+ * {@link DataTypeValue} for a DataType instance and {@link ExprValue} for a raw
+ * expression. Anywhere a catalog field is marked `x-dataType`, pass a
+ * {@link DataTypeValue} — not a raw `$expr`.
+ */
+/**
+ * A value of a block's configuration: plain data, never a function or a class
+ * instance. `undefined` stands for an absent member, which the builder skips
+ * when it writes. The sentinel objects {@link DataTypeValue}, {@link ExprValue},
+ * {@link RefValue} and {@link BlockValue} are {@link ConfigObject}s.
+ */
 export type ConfigValue = string | number | boolean | null | undefined | ConfigValue[] | ConfigObject;
+/** An object of {@link ConfigValue}s: a block's options, or a child's metadata. */
 export interface ConfigObject {
     [key: string]: ConfigValue;
 }
+/**
+ * A DataType value for a Form field's `type` (or a TableView `Column` `type`).
+ * Emitted as `new <DataType>(<config>)` with the import auto-added.
+ *
+ * ```ts
+ * { $dataType: "string", config: { placeholder: "Name" } }
+ * // → type: new DefaultDataTypes.StringType({ placeholder: "Name" })
+ * ```
+ */
 export type DataTypeValue = {
+    /** A `DataTypeDescriptor.id` from the catalog, e.g. `"string"` | `"select"`. */
     $dataType: string;
+    /** The DataType's options; omit for a no-arg `new <DataType>()`. */
     config?: ConfigObject;
 };
+/**
+ * A raw TypeScript expression, emitted verbatim. Required for values the builder
+ * cannot model structurally. The referenced symbol must already be importable in
+ * the target file; the builder does not add its import.
+ *
+ * Note: dms-ai's safe mode rejects `$expr` (arbitrary code defeats the
+ * structured guarantees). Only a direct file edit (vibe mode) should use it.
+ */
 export type ExprValue = {
     $expr: string;
 };
+/**
+ * A reference to a builder-generated resource class, emitted as the bare class
+ * identifier with its import auto-added. The structured, validated alternative to
+ * `$expr` for a class reference — e.g. a `RelationType`'s `dataApiController`.
+ *
+ * ```ts
+ * { $ref: { resource: "product" } }
+ * // → productDataAPI   (imported from the resource's data-api.ts)
+ * ```
+ *
+ * `as` selects which of the resource's classes: `"dataApi"` (default, the
+ * `DataController`), `"table"` (the `Table`), or `"model"` (the `BasicDataModel`).
+ * The resource must exist (unknown → `invalid_config`). Unlike `$expr`, this is
+ * **allowed in safe mode**.
+ */
 export type RefValue = {
     $ref: {
+        /** A `ResourceRef` — the resource's name, e.g. `"product"`. */
         resource: string;
+        /** Which class to reference; defaults to `"dataApi"`. */
         as?: "dataApi" | "table" | "model";
     };
 };
+/**
+ * A nested block, for the rare option that holds a component rather than data —
+ * a ChartCard's `chart`, which the catalog marks `x-component`. Emitted as the
+ * factory call with its import auto-added, and read back as this same shape.
+ *
+ * ```ts
+ * { $block: { type: "ChartArea", config: { xaxisType: "datetime" } } }
+ * // → chart: ChartArea({ xaxisType: "datetime" })
+ * ```
+ *
+ * Allowed in safe mode: the type is checked against the catalog and the config
+ * is serialized the same way any other config is.
+ */
 export type BlockValue = {
     $block: {
+        /** A `BlockTypeDescriptor.type` from the catalog. */
         type: string;
         config?: ConfigObject;
     };

package/dist/values.js

@@ -1,3 +1,10 @@
 "use strict";
+/**
+ * Config values (`AddBlockInput.config`, `ConfigureBlock` patches) are plain
+ * JSON by default. Two sentinel object shapes emit non-literal TypeScript:
+ * {@link DataTypeValue} for a DataType instance and {@link ExprValue} for a raw
+ * expression. Anywhere a catalog field is marked `x-dataType`, pass a
+ * {@link DataTypeValue} — not a raw `$expr`.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=values.js.map

package/dist/values.js.map

@@ -1 +1 @@
-{"version":3,"file":"values.js","sourceRoot":"","sources":["../src/values.ts"],"names":[],"mappings":""}
+{"version":3,"file":"values.js","sourceRoot":"","sources":["../src/values.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/docs/1.introduction.md

@@ -81,3 +81,6 @@ Hand-written declarations stay editable when the builder recognizes their shape.
 - [Results and errors](./8.results-and-errors.md) branches on `OpResult`, reads diagnostics, and makes a write conditional.
 - [Drafts and preview](./9.drafts-and-preview.md) writes the blocks of a page and the data they read in one transaction, and previews either.
 - [A chart without code](./10.a-chart-without-code.md) follows one chart from the choice of a measure to the reopened page.
+- [Theme and branding](./11.theme-and-branding.md) reads and writes a project's colors, corners, font and logos, and gives it the layer they live in.
+- [External databases](./11.external-databases.md) wires a database the project does not own, analyses its catalog and maps its relations.
+- [Connect a database](./12.connect-a-database.md) checks a database live, reads the project's database state, and edits, repairs or removes a connection.

package/docs/10.a-chart-without-code.md

@@ -6,7 +6,7 @@ mode: tutorial
 
 In this tutorial we save a revenue chart grouped by month without writing its data route by hand. We follow the interface calls that the visual builder makes when someone picks a table, a measure and a grouping. The calls run inside a project, so this page is not a standalone script.
 
-![The visual builder with a KPI card selected and its settings open](./images/captures/editor-selected.webp)
+![The visual builder with a KPI card selected and its settings open](./images/captures/editor-selected.webp "illustration")
 
 Before we start, we need an existing `/shop/board` page and an `order` resource with a numeric `amount` field, a date `createdAt` field and a `status` field. Run the calls inside a project that loads the builder. Use a disposable page for the save step, because its draft replaces the page's existing blocks.
 
@@ -132,17 +132,17 @@ A route on the page, guarded with the page's own permission:
 async revenueChart(
   @AuthUserWithPermission(BoardPage) _user: User,
   @Model(OrderModel) model: OrderModel,
-  @Parameter("from", "query") from: string,
-  @Parameter("to", "query") to: string,
-  @Parameter("compareFrom", "query") compareFrom: string,
-  @Parameter("compareTo", "query") compareTo: string,
+  @Parameter("from", "query") from: string | true | undefined,
+  @Parameter("to", "query") to: string | true | undefined,
+  @Parameter("compareFrom", "query") compareFrom: string | true | undefined,
+  @Parameter("compareTo", "query") compareTo: string | true | undefined,
 ): Promise<ChartCardData> {
   return chartCardData(
-    await model.revenueChart(new Date(from), new Date(to)),
+    await model.revenueChart(new Date(String(from)), new Date(String(to))),
     {
       measure: "sum",
       label: "Amount",
-      previous: await model.revenueChart(new Date(compareFrom), new Date(compareTo)),
+      previous: await model.revenueChart(new Date(String(compareFrom)), new Date(String(compareTo))),
     },
   );
 }

package/docs/11.external-databases.md

@@ -6,7 +6,7 @@ mode: reference
 
 ## Overview
 
-A DMS project can show pages over a database it does not own, such as a client's PostgreSQL, MongoDB or RethinkDB database. The engine's module (`@antelopejs/postgres`, `@antelopejs/mongodb` or `@antelopejs/rethinkdb`) reads and writes it live, in external mode. The builder takes such a database in four operations:
+A DMS project can show pages over a database it does not own, such as a client's PostgreSQL, MySQL or MariaDB, MongoDB or RethinkDB database. The engine's module (`@antelopejs/postgres`, `@antelopejs/mysql`, `@antelopejs/mongodb` or `@antelopejs/rethinkdb`) reads and writes it live, in external mode. The builder takes such a database in four operations:
 
 1. `ConfigureProject` wires the database into `antelope.config.ts`. It adds the provider module, a local module for the tables, the builder's catalog connection, and the DMS module's pin to the project's own database.
 2. `AnalyseDatabase` reads the catalog and proposes a mapping by fixed rules. It writes nothing.
@@ -34,6 +34,7 @@ The provider's entry depends on its engine:
 | Engine | Package | `env` | `disabledExports` |
 | --- | --- | --- | --- |
 | PostgreSQL | `@antelopejs/postgres` | `url` | none |
+| MySQL and MariaDB | `@antelopejs/mysql` | `url`, with the database as its path | none |
 | MongoDB | `@antelopejs/mongodb` | `url` and `database` | `@antelopejs/interface-mongodb` |
 | RethinkDB | `@antelopejs/rethinkdb` | `url`, with the database as its path | `@antelopejs/interface-rethinkdb` |
 
@@ -69,12 +70,12 @@ const result = await ConfigureProject([
   {
     op: "ConfigureModule",
     id: "dms",
-    entry: { importOverrides: [{ interface: "@antelopejs/interface-database", source: "mongodb" }] },
-  },
-  {
-    op: "ConfigureModule",
-    id: "dms-builder",
-    entry: { importOverrides: [{ interface: catalog, source: "postgres-erp", id: "erp" }] },
+    entry: {
+      importOverrides: [
+        { interface: "@antelopejs/interface-database", source: "mongodb" },
+        { interface: catalog, source: "postgres-erp", id: "erp" },
+      ],
+    },
   },
 ]);
 if (!result.ok) console.error(result.error);
@@ -82,19 +83,19 @@ if (!result.ok) console.error(result.error);
 
 - The provider's `exportPriority` of `-1` keeps the project's own database the default for every module that does not pin `interface-database`.
 - The tables module pins `interface-database` to the provider, and it uses the DMS. Core passes that pin on to the DMS, which every other module reaches with the default. The DMS therefore pins the project's own database to settle it. A DMS that already pins `interface-database` needs nothing more.
-- When the project loads `dms-ai`, the **Database** workspace gives it the same catalog connection as `dms-builder`.
+- The builder runs in the DMS, so the catalog connection is declared on the DMS's entry, `dms` here. `GetDatabaseProject` answers that id as `self`.
 
 The connection exists once the project restarts with the variable set.
 
 ### Remove a connection
 
-In the **Database** workspace, the **Remove <connection>** button takes a connection out of the configuration with `RemoveConnection` for its catalog connections and `RemoveModule` for its tables module. The tables module's folder is deleted with it. The database itself is untouched.
+`RemoveDatabaseConnection(connection, { dryRun? })` takes a connection out of the configuration with `RemoveConnection` for its catalog connections and `RemoveModule` for its tables module. The tables module's folder is deleted with it. The database itself is untouched.
 
 The tables module is the one whose `dmsBuilder.database` record names the connection. `CreateLocalModule` writes that record from `connection`. The single-operation `CreateLocalModule` takes it in its options. A module that reads through the provider without such a record is never removed or deleted.
 
 The provider is removed too, with the variables that supply its configuration in `envOverrides`, `.env` and `.env.example`, only when it was added for this connection alone. That holds when its `exportPriority` for `@antelopejs/interface-database` is below the project's own database, and no module or connection that the removal leaves names it. Otherwise the provider stays, since it may be the project's own database.
 
-A removal is all or nothing. The workspace moves the folders aside and edits `.env` first, and puts both back when the configuration cannot be written.
+A removal is all or nothing. It moves the folders aside and edits `.env` first, and puts both back when the configuration cannot be written.
 
 ## Analyse a database
 
@@ -112,7 +113,7 @@ if (started.ok) {
 }
 ```
 
-- `connection` must be a catalog connection on the `dms-builder` entry, and `module` a local module other than the project's own. Otherwise the call fails with `invalid_config`.
+- `connection` must be a catalog connection on the DMS's entry, and `module` a local module other than the project's own. Otherwise the call fails with `invalid_config`.
 - One job runs per connection. Starting another while one runs answers the running one.
 - A finished job is kept until the next one on its connection, or until a restart.
 - Relations that the module has mapped, or recorded as excluded, are not proposed again.
@@ -221,9 +222,13 @@ if (!result.ok) console.error(result.error);
   ```
 
 - **In a mapped module**, `CreateResource`, `AddField` and a `ConfigureField` that changes `dbField` fail with `invalid_config`, since the module's tables belong to the database. `DeleteResource` keeps the client's rows and warns `data_kept`.
+- **A read-only connection** gets no write path. The access is `config.externalConnections.<connection>.access` on the `dms-database` entry of `antelope.config.ts`, loaded before every call with core's own `ConfigLoader` for the launch environment, as `dms-database` receives it: the entry, that environment's member of `environments`, `antelope.dms-database.json` and `envOverrides`, merged in core's order. It is `"read-write"` only when that says so, and a configuration that cannot be loaded counts as `"read"`. Otherwise `MapResources` and `PreviewMapResources` refuse a resource with `writable: true` and a TableView, `AddBlock`, `ComposePage` and `SetPageBlocks` refuse a `ResourceForm` in `new` or `edit` mode over one of its tables and a block over one of its tables that still serves write routes, `ConfigureBlock` and `SetPageBlocks` refuse to turn a `ResourceForm` over one into one in `new` or `edit` mode, and `ConfigureResource` refuses write routes on one. Each fails with `invalid_config`, names the connection, the place that keeps it read-only and how to allow changes, and writes nothing.
+- **A mapped table's write routes follow the access at runtime.** Each data controller a mapping writes carries `@ExternalConnection("<connection>")`, so its `new`, `edit`, `delete`, `archive` and `restore` routes answer 403 while `dms-database` reports the connection's access as `"read"`, routes kept from a mapping made while it was `"read-write"` included, and whichever form or client posts to them.
+- **The interface is the owner path for an access.** `ConfigureProject`, `AddModule`, `ConfigureModule` and `CreateLocalModule` write `config.externalConnections.<connection>.access` as asked: owner-authenticated routes grant `"read-write"` through them, the `dms-database` route `PUT /api/database/connections/<id>/access` and the assistant's `POST /database/project`. Agents reach them only through the MCP tool `builder_configure_project`, which refuses a step that raises an access.
 
 ## Next steps
 
+- [Connect a database](./12.connect-a-database.md) lists the operations a connect flow drives: the live check, the project's database state, the repair and the connection's details.
 - [Resources](./5.resources.md) describes the resources a mapping writes. They are ordinary resources, read the same way.
 - [Queries](./6.queries.md) shows how stats over a mapped relation name it by its ref.
 - [Results and errors](./8.results-and-errors.md) shows how to branch on what every operation answers.