@pilotiq/pilotiq 0.23.1 → 0.24.2

package/boost/skills/pilotiq-fields/rules/validation.md

@@ -0,0 +1,198 @@
+# Validation
+
+Validators are functions: `(value, ctx?) => string | null | Promise<string | null>`. Return a message string to fail; return `null` to pass. The framework runs them in declaration order, awaits async ones, and aggregates per-field errors before calling the form's `save` handler.
+
+## Built-in validators
+
+```ts
+import { Field } from '@pilotiq/pilotiq'
+
+TextField.make('email')
+  .validate([
+    Field.required(),                              // or just .required()
+    Field.email(),
+    Field.maxLength(255),
+  ])
+
+TextField.make('password')
+  .password()
+  .validate([
+    Field.required(),
+    Field.minLength(8, 'At least 8 characters'),
+    Field.pattern(/[A-Z]/, 'Must contain an uppercase letter'),
+    Field.pattern(/[0-9]/, 'Must contain a digit'),
+  ])
+
+NumberField.make('age')
+  .validate([
+    Field.min(18, 'Must be 18 or older'),
+    Field.max(120),
+  ])
+
+TextField.make('slug')
+  .validate([
+    Field.required(),
+    Field.pattern(/^[a-z0-9-]+$/, 'Lowercase letters, numbers, hyphens only'),
+  ])
+```
+
+The full set: `required(message?) / email(message?) / minLength(n, message?) / maxLength(n, message?) / min(n, message?) / max(n, message?) / pattern(regex, message)`.
+
+`Field.required()` is auto-contributed when you call `.required()` directly — no need to add it twice.
+
+## Custom validators
+
+A validator is just a function. Inline:
+
+```ts
+TextField.make('username')
+  .validate(async (value, ctx) => {
+    if (typeof value !== 'string') return null
+    if (value.length < 3) return 'At least 3 characters'
+    if (value.startsWith('admin')) return 'Reserved prefix'
+    return null                                    // pass
+  })
+```
+
+The `ctx` shape:
+
+```ts
+{
+  record?: unknown                                 // current record on edit/view
+  values?: Record<string, unknown>                 // all form values
+  user?: unknown
+  mode?: 'create' | 'edit' | 'view'
+  basePath?: string
+}
+```
+
+Async is fine — the framework awaits each one.
+
+## `Field.unique()` async DB probe
+
+The standard "this field must be unique across all records" check:
+
+```ts
+import { Field } from '@pilotiq/pilotiq'
+
+TextField.make('slug')
+  .validate(Field.unique({
+    model: Article,
+    column: 'slug',                              // optional, defaults to field name
+    ignoreRecord: true,                           // skip the row matching ctx.record[pk]
+    where: { status: 'published' },               // optional scope
+    caseInsensitive: true,
+    message: 'Slug is already in use',            // optional custom message
+  }))
+```
+
+How it works:
+
+- Issues `M.query().where(column, value).paginate(1, 2)` — limit 2 to detect uniqueness without scanning the table.
+- `ignoreRecord: true` (default `true`) skips the row matching `ctx.record[primaryKey]` so edit-no-change saves don't conflict.
+- `caseInsensitive: true` switches to SQL `LIKE` with `%` / `_` / `\` escaped (SQLite + MySQL friendly; Postgres collation-dependent).
+- `where: { status: 'published' }` adds AND-clauses to the lookup query (useful for soft scopes — "unique among published rows").
+- Inside a `Repeater`, `unique()` probes the database but does NOT see unsaved sibling rows. Pair with `distinct()` for cross-row uniqueness within the form.
+
+`Field.unique` accepts a `Model`-like object (anything with `.query()`). The Resource doesn't need to be using the same Model.
+
+## `Field.distinct()` cross-row uniqueness inside Repeater / Builder
+
+Inside a `Repeater` or `Builder`, `unique()` only checks the database. To enforce that values are unique ACROSS rows in the form itself (before submit), use `distinct()`:
+
+```ts
+Repeater.make('contacts')
+  .schema([
+    TextField.make('email')
+      .validate(Field.email())
+      .distinct(),                                 // unique within this Repeater
+    TextField.make('label'),
+  ])
+```
+
+Options:
+
+```ts
+TextField.make('email')
+  .distinct({
+    caseInsensitive: true,                         // default false
+    ignoreNulls: true,                             // default true — skip empty rows
+    message: 'Email already used in another row',
+  })
+```
+
+For `Builder`, distinctness is per-block-type — `heading.text="X"` never conflicts with `paragraph.text="X"`.
+
+Pair with `unique({ model })` for in-form + cross-record uniqueness:
+
+```ts
+TextField.make('slug')
+  .validate(Field.unique({ model: Article }))     // unique in DB
+  .distinct()                                      // unique in this form too
+```
+
+## Form-level validators
+
+`Form.validate(fn)` runs after every field's validators have passed:
+
+```ts
+form
+  .schema([
+    DateField.make('startsAt').required(),
+    DateField.make('endsAt').required(),
+  ])
+  .validate(({ values }) => {
+    if (values.endsAt < values.startsAt) {
+      return { endsAt: 'Must be after start date' }
+    }
+    return null
+  })
+```
+
+Return shape:
+- `null` (or `{}`) — pass
+- `{ [fieldName]: 'message' }` — per-field errors (replaces any field-level errors)
+- `{ _form: 'Top-level message' }` — form-wide error, rendered at the top of the form
+
+Form-level validators run AFTER coercion (so values are typed) but BEFORE save.
+
+## Validation order
+
+For each form submit, the framework runs:
+
+1. **Coerce raw FormData values** to typed values (string → number for NumberField, JSON-string → object for KeyValueField, etc.). Coerce errors aren't reported per-field; raw values fall through.
+2. **Field-level validators** — for every Field with `validate([...])` or `.required()`. Aggregated by field name.
+3. **Form-level `validate(fn)`** — if present, runs only when no field errors fired (early exit).
+4. **`save(ctx)` / model.create / model.update** — only reached when validation passes.
+
+Important: **validate runs BEFORE coerce in `dispatchFormSubmit`**, then field-types do their own coerce-fold during their `runValidators`. The order is "validate the raw value, then coerce the validated value" — useful to remember when writing custom validators.
+
+## Errors on the wire
+
+Field errors land on `FormMeta.errors` as `Record<fieldName, string[]>`. The renderer auto-stamps them under each field's input. Repeater/Builder errors key as `items.<i>.<name>` / `name.<i>.data.<child>` respectively; `min/maxItems` lands under the bare field name.
+
+For form-level errors, the `_form` key is special — the renderer surfaces it as an Alert at the top of the form.
+
+## Throwing validators
+
+A validator that throws is treated as a failure. The message comes from `err.message`:
+
+```ts
+TextField.make('email')
+  .validate(async (value) => {
+    if (typeof value !== 'string') throw new Error('Email is required')
+    if (!value.includes('@')) return 'Invalid email'
+    return null
+  })
+```
+
+For unique-across-DB or other async lookups, prefer returning `null` for "skip the check" rather than throwing — throws log + fail with the error message verbatim.
+
+## Common pitfalls
+
+- **`required()` doesn't see `null` as empty** — by default `required()` checks for `value !== null && value !== undefined && value !== ''`. For domain-specific empty (`[]`, `{}`), write a custom validator.
+- **`Field.unique()` without `ignoreRecord: true`** trips on edit-no-change saves — the row's own value conflicts with itself. Default is `true`; only set to `false` for "even my own row counts."
+- **`distinct()` outside a Repeater/Builder** is a no-op. The framework only evaluates it inside an array-row container.
+- **Async validators in parallel** — validators within ONE field run serially in declaration order; validators across DIFFERENT fields run in parallel. Don't rely on cross-field ordering.
+- **`pattern(/regex/)` without anchors** matches anywhere in the string. Add `^…$` if you mean "the whole value."
+- **Validation result `{}`** (empty object) means "pass" — the framework treats no-keys as no-errors. Return `null` for clarity.

package/boost/skills/pilotiq-relations/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: pilotiq-relations
+description: Wiring related entities in pilotiq — RelationManager tabs (hasMany / morph / belongsToMany), Repeater.relationship for inline child rows, and Builder.relationship for heterogeneous child types
+license: MIT
+appliesTo:
+  - '@pilotiq/pilotiq'
+trigger: defining `Resource.relations()`, subclassing `RelationManager`, or wiring `Repeater.relationship` / `Builder.relationship` for relation-backed array rows
+skip: defining standalone fields with no parent-child semantics — that's `pilotiq-fields`
+metadata:
+  author: pilotiq
+---
+
+# Pilotiq Relations
+
+## When to use this skill
+
+Load when you're:
+
+- Adding a `comments` / `tags` / `attachments` tab to a record's edit page via a `RelationManager`
+- Choosing between a `RelationManager` (separate tab, full table + form) and `Repeater.relationship()` (inline rows on the parent form)
+- Wiring a polymorphic (`morphMany` / `morphTo`) or many-to-many (`belongsToMany`) relation
+- Building a Builder field whose rows persist as real child records with `{type, data}` shape (`Builder.relationship`)
+
+For standalone form fields (no relation), use `pilotiq-fields`. For Resource basics, `pilotiq-resource`.
+
+## Quick Reference
+
+| Task | Open |
+|---|---|
+| RelationManager — separate tab on the parent's edit/view page; full table + form for the related records. Covers hasMany / morph / M2M | `rules/relation-managers.md` |
+| Repeater.relationship — inline rows on the parent form backed by real `hasMany` / `morph*` / M2M children. Builder.relationship for `{type,data}` heterogeneous rows | `rules/repeater-relationship.md` |
+
+## Key concepts (load once)
+
+- **Two patterns, different UX.** A `RelationManager` is a separate tab with its own table — good for many children (Posts → Comments). A `Repeater.relationship()` is inline rows on the parent form — good for tight 1-to-few (Order → LineItems).
+- **`RelationManager` requires `static relationName` to match a key on the parent model's `static relations` map.** That string doubles as URL segment (`/posts/:id/comments`) and the relation accessor (`parent.related('comments')`).
+- **`RelationManager.mode` is auto-derived.** From `parent.constructor.relations[relationName].type` via `getRelationType + normalizeRelationMode`. `hasOne` / `hasMany` → `'hasMany'`; `morphMany` / `morphOne` → `'morphMany'`; `morphTo` → `'morphTo'`; M2M (`belongsToMany`, `morphToMany`, `morphedByMany`) → `'belongsToMany'`. Forms + actions adapt accordingly — M2M flips into pivot-mutation mode; morphMany auto-fills `<morphName>Id` / `<morphName>Type` on create + edit.
+- **`Repeater.relationship` persists rows as real children.** Diffs submitted rows vs `parent.related(rel).get()` on save — matching `__id` runs `M.update`, missing ID runs `M.create`, existing PK absent from submitted set runs `M.delete`. M2M variant calls `accessor.attach/detach` instead of `M.delete`.
+- **`Builder.relationship` adds a discriminator column** (default `'type'`, the block name) + a JSON payload column (default `'data'`, the per-block inner-schema values). Same diff persistence as Repeater.relationship, but each row carries its block type so the form can render the right inner schema.
+- **Authorization is two-layered.** Parent's `canView` / `canEdit` runs first; then the manager's `canViewAny` / `canCreate` / `canEdit` / `canDelete` (or `canAttach` / `canDetach` for M2M). Fall-through: manager predicates default to the related Resource's matching predicate when the manager hasn't overridden (except `canAttach` / `canDetach` — manager-only, no fall-through).
+
+## Examples
+
+- `playground/app/Pilotiq/Posts/RelationManagers/CommentsRelationManager.ts` — vanilla `hasMany` manager.
+- `playground/app/Pilotiq/Articles/RelationManagers/TagsRelationManager.ts` — `belongsToMany` with attach/detach.
+- `playground/app/Pilotiq/Comments/CommentResource.ts` — `morphTo` (child-side polymorphic) shared across multiple parents.
+- `playground/app/Pilotiq/Orders/Schemas/form.ts` — `Repeater.relationship('lineItems')` for inline child rows.

package/boost/skills/pilotiq-relations/rules/relation-managers.md

@@ -0,0 +1,256 @@
+# Relation Managers
+
+A `RelationManager` projects a related collection onto a parent record's edit / view page as a separate tab — full table chrome, create / edit / delete actions, optional attach / detach for M2M. Each manager runs against `parent.related(relationName).query()` and uses the related Resource's `Model` for persistence.
+
+## Basics — `hasMany`
+
+```ts
+import { RelationManager, Table, Form, Column, TextField, Textarea } from '@pilotiq/pilotiq'
+
+export class CommentsRelationManager extends RelationManager {
+  static override relationName       = 'comments'                // matches Post.relations.comments
+  static override label              = 'Comments'
+  static override labelSingular      = 'Comment'
+  static override icon               = 'message-square'
+  static override recordTitleAttribute = 'body'
+
+  static override form(form: Form, ctx) {
+    return form.schema([
+      Textarea.make('body').required().rows(4),
+    ])
+  }
+
+  static override table(table: Table, ctx) {
+    return table
+      .columns([
+        Column.make('body').limit(80).searchable(),
+        Column.make('author.name').label('Author'),
+        Column.make('createdAt').since().sortable(),
+      ])
+      .defaultSort('createdAt', 'desc')
+      .paginate(10)
+      .recordActions([
+        Action.relationEdit(this, ctx),
+        Action.relationDelete(this, ctx),
+      ])
+      .headerActions([
+        Action.relationCreate(this, ctx),
+      ])
+  }
+}
+
+class PostResource extends Resource {
+  static override model = Post
+  static override relations() {
+    return [CommentsRelationManager]
+  }
+}
+```
+
+The parent (`Post`) must declare the relation in its `static relations`:
+
+```ts
+export class Post extends Model {
+  static override relations = {
+    comments: { type: 'hasMany', model: () => Comment, foreignKey: 'postId' },
+  }
+}
+```
+
+That gives you:
+
+- New tab on `/admin/posts/:id` and `/admin/posts/:id/edit` labeled "Comments"
+- Tab content is the manager's `table()` — rows from `Post.find(id).related('comments').query()`
+- Routes: `GET ${base}/posts/:id/comments` (list), `GET/POST .../comments/create`, `GET/POST .../comments/:childId/edit`, `POST .../comments/:childId/delete`
+- IDOR check on edit/delete: framework re-runs the relation query before each, throws 404 if the child no longer belongs to the parent
+
+`ctx: RelationManagerContext` carries `basePath / parentSlug / parentId / relationship / parentRecord / mode` so factories can wire URLs without manual threading.
+
+## Polymorphic — `morphMany` / `morphTo`
+
+Parent-side (`morphMany`):
+
+```ts
+// Post.ts
+export class Post extends Model {
+  static override relations = {
+    comments: { type: 'morphMany', model: () => Comment, name: 'commentable' },
+  }
+}
+
+// Video.ts
+export class Video extends Model {
+  static override relations = {
+    comments: { type: 'morphMany', model: () => Comment, name: 'commentable' },
+  }
+}
+
+// Comment.ts (child-side morphTo)
+export class Comment extends Model {
+  static override relations = {
+    commentable: { type: 'morphTo', name: 'commentable' },
+  }
+  commentableId!: string
+  commentableType!: 'Post' | 'Video'
+  body!: string
+}
+```
+
+Same manager for both parents — register it on `PostResource.relations()` and `VideoResource.relations()`. The framework auto-fills `commentableId = parent.id` and `commentableType = 'Post' | 'Video'` (read from `parent.constructor.morphAlias ?? parent.constructor.name`) on create + edit. **The framework wins last** — a tampered POST body (`commentableId=v1&commentableType=Video`) cannot reassign a child to a different polymorphic parent.
+
+Child-side (`morphTo`) — the child class itself can be a Resource, but doesn't get auto-actions or auto-discovery:
+
+```ts
+export class CommentResource extends Resource {
+  static override model = Comment
+  // The morphTo column drives display only; the parent is dynamic
+}
+```
+
+Set `static relatedResource = SomeResource` explicitly on the manager if you want a custom view of the comment.
+
+## Many-to-many — `belongsToMany`
+
+```ts
+// Article.ts
+export class Article extends Model {
+  static override relations = {
+    tags: { type: 'belongsToMany', model: () => Tag, pivot: 'article_tag' },
+  }
+}
+
+// Tag.ts
+export class Tag extends Model {
+  static override relations = {
+    articles: { type: 'belongsToMany', model: () => Article, pivot: 'article_tag' },
+  }
+}
+
+// TagsRelationManager.ts
+export class TagsRelationManager extends RelationManager {
+  static override relationName = 'tags'
+  static override label        = 'Tags'
+
+  static override table(table: Table, ctx) {
+    return table
+      .columns([
+        Column.make('name').searchable(),
+        Column.make('slug'),
+      ])
+      .headerActions([
+        Action.relationAttach(this, ctx),                // modal picker
+      ])
+      .recordActions([
+        Action.relationDetach(this, ctx),                // unlink (don't delete tag)
+      ])
+      .bulkActions([
+        Action.relationBulkDetach(this, ctx),
+      ])
+  }
+
+  // M2M-only authorization predicates
+  static override async canAttach(user, parentRecord)         { return Boolean(user) }
+  static override async canDetach(user, child, parentRecord)  { return user.role === 'admin' }
+}
+```
+
+The framework dispatches via `parent[relationName]().attach() / .detach()` instead of `M.create() / M.delete()`. Important distinctions:
+
+- **`relationDetach` unlinks the pivot row only** — the related `Tag` still exists. `relationDelete` (which would delete the Tag itself) auto-hides under M2M.
+- **`relationAttach` modal-form** uses a `SelectField` populated by `loadAttachableCandidates()` — fetches up to 50 candidate rows server-side and filters out already-attached IDs.
+- **`relationCreate` / `relationEdit`** still auto-hide under M2M — the existing tag is edited via its own `TagResource` route, not the relation manager.
+
+Pivot extras (columns on the `article_tag` pivot itself) aren't editable through `RelationManager` in v1 — see `Repeater.relationship().pivotColumns([…])` for that pattern, or use a `Repeater.relationship` instead.
+
+## Authorization — manager + Resource fall-through
+
+`RelationManager` exposes seven async predicates:
+
+```ts
+class CommentsRelationManager extends RelationManager {
+  static override async canViewAny(user, parentRecord)                  { return true }
+  static override async canView(user, child, parentRecord)              { return true }
+  static override async canCreate(user, parentRecord)                    { return Boolean(user) }
+  static override async canEdit(user, child, parentRecord)              { return user.id === child.authorId }
+  static override async canDelete(user, child, parentRecord)            { return user.role === 'admin' }
+  static override async canAttach(user, parentRecord)                    { return false }   // not M2M
+  static override async canDetach(user, child, parentRecord)            { return false }
+}
+```
+
+Fall-through behavior:
+
+- Predicates that ARE overridden on the manager: use the manager's value.
+- Predicates that are NOT overridden: fall through to the related Resource's matching predicate via reference-equality check on the prototype.
+- `canAttach` / `canDetach` are manager-only — they DON'T fall through (attach/detach are pivot operations, not record operations).
+
+For the route handler, the framework runs `parent.canAccess + parent.canEdit` first, then the manager-scope predicate. Both must pass.
+
+## Reserved relation tokens
+
+Relation names are validated at panel boot. The following tokens are reserved and throw a clear error if used as `relationName`:
+
+`edit`, `delete`, `restore`, `force-delete`, `_form`, `_action`, `_search`, `_uploads`, `_attach`, `_detach`, `_bulk-detach`
+
+If you have a relation that collides (rare), rename the relation on the Model.
+
+## Soft-delete on relation children
+
+Same two-sided opt-in as Resources. When the related Model AND the related Resource both declare `softDeletes = true`, the manager auto-injects `TrashedFilter`, and `Action.relationRestore` / `relationForceDelete` factories become available.
+
+```ts
+class CommentsRelationManager extends RelationManager {
+  static override relationName = 'comments'
+
+  static override table(table, ctx) {
+    return table
+      .columns([...])
+      .recordActions([
+        Action.relationEdit(this, ctx),
+        Action.relationDelete(this, ctx),         // shows on active rows
+        Action.relationRestore(this, ctx),        // shows on trashed rows
+        Action.relationForceDelete(this, ctx),    // shows on trashed rows
+      ])
+  }
+}
+```
+
+## Replicate (clone) a child
+
+```ts
+.recordActions([
+  Action.relationReplicate(this, ctx, undefined, {
+    excludeAttributes: ['publishedAt'],            // strip these from the clone
+    beforeReplicaSaved: (replica, ctx) => {
+      replica.body = `[Copy] ${replica.body}`
+      return replica
+    },
+  }),
+])
+```
+
+The framework strips PK + soft-delete column + your `excludeAttributes`, runs `beforeReplicaSaved`, then **force-pins the parent attachment column back** so a tampered source row can't slip a different parent in by riding its own FK column. Auto-hides on M2M (replicate doesn't fit pivot semantics) and on `morphTo` (no single owner to pin to).
+
+## Nested relations (depth-2)
+
+A manager can register its own sub-managers — a Post → Comments → CommentReplies chain:
+
+```ts
+class CommentsRelationManager extends RelationManager {
+  static override relations() {
+    return [CommentRepliesRelationManager]
+  }
+}
+```
+
+The Comments tab on a Post shows the regular comments table; clicking a comment opens its edit/view page with the CommentReplies sub-tab. Sub-manager URLs are `${base}/posts/:postId/comments/:commentId/replies`.
+
+Depth-2 supports the full surface of depth-1 (form, table, actions, soft delete, replicate, M2M, polymorphic). Depth-3+ deferred — you'd usually denormalize at that point.
+
+## Common pitfalls
+
+- **`relationName` typo** — silently makes the manager point at a non-existent relation. The framework catches it at boot if the parent's `static relations` map doesn't contain the key (clear error message). If you skip declaring relations on the parent Model, the M2M / morph type can't be detected and falls back to `'hasMany'` — also caught at boot with a clear warning.
+- **`Action.relationEdit / relationDelete` outside `RelationManager.table()`** doesn't work — they need the `ctx` arg from the manager. Use `Action.edit(R, base, id)` for the related Resource's standalone edit page.
+- **Forgetting `static relatedResource`** on a `morphTo` manager means the framework can't resolve form / detail schemas for the child. Set it explicitly when the child is polymorphic.
+- **M2M `canCreate` semantics** — for M2M, `canCreate` controls whether the user can create a NEW tag (via the regular TagResource path). Use `canAttach` to control whether they can link an existing tag to this parent.
+- **Pivot reads aren't surfaced via `belongsToMany` v1** — if you need extra columns on the pivot table (e.g. `created_at` on `article_tag`), use a `Repeater.relationship('articleTags')` with the pivot model as a regular `hasMany` instead. The `RelationManager` route layer can't expose pivot extras without ORM changes.

package/boost/skills/pilotiq-relations/rules/repeater-relationship.md

@@ -0,0 +1,177 @@
+# Repeater.relationship and Builder.relationship
+
+`Repeater.relationship(name)` and `Builder.relationship(name)` are the inline-row alternatives to `RelationManager`. Instead of a separate tab with its own table, rows live ON the parent's form — typed inline, persisted to a real `hasMany` / `morph*` / M2M relation (Repeater) or a discriminator + JSON-payload child table (Builder).
+
+Use these for tight 1-to-few relations where you want inline editing on the parent form: line items on an order, slides in a presentation, blocks in a CMS page.
+
+## `Repeater.relationship` — uniform rows
+
+```ts
+Repeater.make('lineItems')
+  .relationship('lineItems')
+  .schema([
+    TextField.make('description').required(),
+    NumberField.make('quantity').min(1).required(),
+    NumberField.make('unitPrice').step(0.01).required(),
+  ])
+  .min(1)
+  .reorderable()
+  .orderColumn('position')                // optional — stamp index on save
+```
+
+The parent Model must declare the relation:
+
+```ts
+export class Order extends Model {
+  static override relations = {
+    lineItems: { type: 'hasMany', model: () => LineItem, foreignKey: 'orderId' },
+  }
+}
+
+export class LineItem extends Model {
+  static override table = 'line_items'
+  description!: string
+  quantity!: number
+  unitPrice!: number
+  position?: number                       // when orderColumn is set
+}
+```
+
+How it works:
+
+- **Load** — `applyRelationshipRepeaterFill()` reads rows from `parent.related('lineItems')` via the relation accessor, stamps `__id = String(child.pk)` on each, strips PK + FK from the rendered row.
+- **Save** — `dispatchFormSubmit` extracts the field's value before generic field coercion, then after the parent's `save()` returns runs `persistRelationshipRows`:
+  - Submitted rows with `__id` matching an existing PK → `M.update(__id, row)`. FK is NOT overwritten (defense against tampered re-link).
+  - Submitted rows with `__id` absent or non-matching → `M.create({ ...row, [foreignKey]: parentPk })`.
+  - Existing PKs missing from the submitted set → `M.delete(pk)`.
+  - When `orderColumn` is set: the row's 0-based index stamps on every create + update payload.
+
+**M2M variant** — when the relation is `belongsToMany` / `morphToMany` / `morphedByMany`, the framework dispatches through `parent[rel]().attach()` / `.detach()` instead. Row-create calls `M.create()` then `accessor.attach([newPk])`. Row-remove calls `accessor.detach([pk])` only — no `M.delete` (the related child may be linked to other parents).
+
+```ts
+// On Article: tags via M2M
+Repeater.make('tags')
+  .relationship('tags')                    // Article.tags = belongsToMany
+  .schema([
+    SelectField.make('id').options(allTagsAsOptions).required(),
+  ])
+```
+
+`pivotColumns([…])` adds editable columns on the pivot:
+
+```ts
+Repeater.make('tags')
+  .relationship('tags')
+  .schema([
+    SelectField.make('id').options(allTagsAsOptions).required(),
+  ])
+  .pivotColumns([
+    NumberField.make('weight').default(1),    // editable column on article_tag
+    TextField.make('note'),
+  ])
+```
+
+Pivot columns are read from the M2M pivot row, edited inline, persisted via `accessor.sync()` or `attach/detach`-with-pivot APIs.
+
+## `Builder.relationship` — heterogeneous rows
+
+When rows can be ONE OF N block types — paragraph vs heading vs image — `Builder.relationship` persists each row as a child record with a discriminator column + a JSON payload column:
+
+```ts
+Builder.make('content')
+  .relationship('blocks')                  // parent.blocks = hasMany ContentBlock
+  .blocks([
+    Block.make('heading').icon('heading').schema([
+      TextField.make('text').required(),
+      SelectField.make('level').options({ h1: 'H1', h2: 'H2', h3: 'H3' }),
+    ]),
+    Block.make('paragraph').icon('text').schema([
+      MarkdownField.make('body'),
+    ]),
+    Block.make('image').icon('image').schema([
+      FileUpload.make('src').accept('image/*').required(),
+      TextField.make('alt'),
+    ]),
+  ])
+  .reorderable()
+  .orderColumn('position')
+```
+
+Schema for `ContentBlock`:
+
+```ts
+export class ContentBlock extends Model {
+  static override table = 'content_blocks'
+  id!: number
+  pageId!: number                          // foreign key
+  type!: string                            // 'heading' | 'paragraph' | 'image'
+  data!: Record<string, unknown>           // per-block inner-schema values
+  position?: number
+}
+```
+
+Column names are overridable via the options object:
+
+```ts
+Builder.make('content').relationship({
+  name:         'blocks',
+  typeColumn:   'blockType',               // default 'type'
+  dataColumn:   'payload',                 // default 'data'
+  orderColumn:  'sortOrder',
+})
+```
+
+How it works:
+
+- **Load** — `applyRelationshipBuilderFill()` reads `{__id, type, data}` per row, JSON-parses string `data` columns, strips PK + FK + `type` + `data` from each rendered row's inner data.
+- **Save** — `persistRelationshipBuilderRows()`:
+  - Submitted rows with `__id` matching an existing PK → `M.update(__id, { [typeColumn]: row.type, [dataColumn]: row.data, [orderColumn]: idx })`. FK is NOT overwritten.
+  - Submitted rows with `__id` absent → `M.create({ [typeColumn]: row.type, [dataColumn]: row.data, [foreignKey]: parentPk, [orderColumn]: idx })`.
+  - Existing PKs missing from submitted set → `M.delete(pk)`.
+  - **Type column rewrites on update** — a block can switch types between submits.
+
+Unknown block types in submitted data round-trip verbatim (renderer shows a placeholder, server passes data through) — config rollbacks never silently lose content.
+
+v1 = `hasMany` + `morphMany` / `morphOne` only. M2M is deferred — heterogeneous `{type, data}` envelope doesn't compose cleanly with pivot semantics.
+
+## When to use which
+
+| Pattern | Use when |
+|---|---|
+| `RelationManager` (separate tab) | Many children (100s+ comments); separate URL feels natural; user expects pagination + search; permissions differ from parent |
+| `Repeater.relationship` (inline, uniform) | Tight 1-to-few (10ish line items); users edit children alongside the parent; consistent shape per row |
+| `Repeater` (no `.relationship()`, JSON storage) | Same as above but no relation table — rows live as a JSON column on the parent. Simplest setup |
+| `Builder.relationship` (inline, heterogeneous) | CMS content blocks, form-builder schemas — rows have varied shape; need querying child records (`pageId`-indexed) |
+| `Builder` (no `.relationship()`, JSON storage) | Same shape, JSON-blob storage. Use when you don't need to query children individually |
+
+## Per-row hooks
+
+```ts
+Repeater.make('lineItems')
+  .relationship('lineItems')
+  .schema([...])
+  .afterCreate(async (record, ctx) => {
+    await audit.log('lineItem.created', { orderId: ctx.parentId, lineItemId: record.id })
+  })
+  .afterUpdate(async (record, ctx) => {
+    // ctx: { parent, parentId, field, index, mode }
+    // mode is 'hasMany' | 'morphMany' | 'belongsToMany' | 'morphToMany' | 'morphedByMany'
+  })
+  .afterDelete(async (record, ctx) => {
+    // index is -1 on afterDelete (deleted rows aren't in submitted set)
+  })
+```
+
+Each setter throws at config time if `relationship()` wasn't called first.
+
+Errors propagate — a throwing handler stops the rest of the persist diff. v1 isn't transactional so earlier rows are already committed.
+
+## Common pitfalls
+
+- **`Repeater.relationship()` without a `static relations[name]` entry on the parent Model** throws a clear error pointing at the override paths. Add `{ type: 'hasMany', model: () => Child, foreignKey: 'parentId' }` to the parent's `static relations`.
+- **Mutually exclusive with `simple()` and `dehydrated(false)`** — relationship-backed Repeaters need full row shape. Calling either after `.relationship()` throws.
+- **No transaction wrapper in v1** — partial failure leaves the parent saved with some rows persisted and others not. For critical financial / inventory flows, use a separate `Action.handler` that wraps the save in a Model-level transaction explicitly.
+- **`orderColumn` rejected on M2M** — ORM has no `orderByPivot` in v1; pivot-ordered relations aren't supported. Use a regular `hasMany` with an explicit join table for ordered M2M.
+- **`Builder.relationship` doesn't support M2M** — heterogeneous `{type, data}` envelope doesn't compose with pivot semantics. Use `Repeater.relationship` with M2M, or model as `morphMany` instead.
+- **`pivotColumns` outside an M2M relation** is a no-op — the framework can't write pivot extras on a hasMany. The columns silently don't persist.
+- **Submitting a row with a tampered `__id`** (pointing at another parent's child) trips the framework's IDOR check — `persistRelationshipRows` re-queries via `parent.related(rel)` and refuses to update a child that doesn't belong. The submit returns a 422 with a clear error.