@pilotiq/pilotiq 0.24.1 → 0.24.3

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.

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

@@ -0,0 +1,61 @@
+---
+name: pilotiq-resource
+description: Defining CRUD-managed entities in a pilotiq admin panel — Resource class, page base classes (ListPage/CreatePage/EditPage/ViewPage), and authorization
+license: MIT
+appliesTo:
+  - '@pilotiq/pilotiq'
+trigger: creating or editing a `Resource` subclass under `app/Pilotiq/`, customizing one of its four page roles (List/Create/Edit/View), or wiring authorization rules
+skip: working in a non-pilotiq route handler that just reads/writes a model directly — that's an `@rudderjs/router` concern
+metadata:
+  author: pilotiq
+---
+
+# Pilotiq Resource
+
+## When to use this skill
+
+Load when you're:
+
+- Creating a new `Resource` subclass that backs admin CRUD pages for an entity (`Article`, `User`, `Product`, …)
+- Customizing one of the four auto-generated pages — overriding `getHeader()`, `getFormActions()`, `beforeCreate()`, `afterUpdate()`, etc. on `ListPage` / `CreatePage` / `EditPage` / `ViewPage`
+- Wiring authorization — `canAccess` / `canView` / `canCreate` / `canEdit` / `canDelete` statics, or the `Pilotiq.user()` resolver
+
+For just-the-fields work (no page customization), `pilotiq-fields` is the more focused skill. For relation-backed tabs and nested data, `pilotiq-relations`.
+
+## Quick Reference
+
+| Task | Open |
+|---|---|
+| Define a Resource — `static label / icon / model / form / table / detail`, navigation metadata, soft deletes | `rules/defining-resources.md` |
+| Customize page roles — when to subclass `ListPage` / `CreatePage` / `EditPage` / `ViewPage`, override hooks, wizard create | `rules/page-overrides.md` |
+| Authorization — `canX` static predicates, `Pilotiq.user()`, fail-closed posture, per-record gates | `rules/authorization.md` |
+
+## Key concepts (load once)
+
+- **Everything is `static`.** `Resource.form(form: Form): Form`, `Resource.table(table: Table): Table`, `Resource.canEdit(user, record): bool` — the framework calls these on the class itself. Don't instantiate.
+- **The framework auto-generates 4 pages from one Resource:** list, create, edit, view. Routes: `${base}/${slug}` (list), `${base}/${slug}/create`, `${base}/${slug}/:id`, `${base}/${slug}/:id/edit`. URL slug auto-derives from class name (`ArticleResource` → `articles`); override via `static override slug = '…'`.
+- **`static model = SomeModel` auto-fills CRUD.** When set, the framework auto-wires `Form.save`, `Form.loadRecord`, `Resource.deleteRecord`, and `Table.records` — no manual ORM plumbing. Anything you set explicitly still wins.
+- **Page base classes only matter if you override hooks.** The framework ships sensible defaults — subclass `ListPage` / `CreatePage` / `EditPage` / `ViewPage` only when you need `getHeaderActions`, `getFormActions`, `beforeCreate`, `afterUpdate`, etc. Bare resources don't need page subclasses at all.
+- **Authorization is fail-closed.** Predicates default to `true`; the framework runs them through `safePolicy()` which catches throws and treats them as `false` (403). `Pilotiq.user(req => …)` is the resolver — it returns whatever shape your auth layer hands you; predicates receive that opaque type.
+- **Per-record gates run server-side per row.** On the list page, `canView` / `canEdit` / `canDelete` evaluate per row and stamp `_visibleActions` / `_disabledActions`. Predicates with a `record` arg are record-aware; bare `canCreate(user)` doesn't see a record.
+
+## Setup once at the panel
+
+```ts
+// app/Pilotiq/AdminPanel.ts
+import { Pilotiq } from '@pilotiq/pilotiq'
+
+export const adminPanel = Pilotiq.make('Admin')
+  .path('/admin')
+  .user(async (req) => req.session?.user ?? null)
+  .resources([ArticleResource, UserResource])
+  .pages([AnalyticsPage])
+```
+
+The user resolver returns `null` for anonymous; predicates that need a user must guard for that (or use `Pilotiq.guard()` to redirect to a sign-in route first).
+
+## Examples
+
+- `playground/app/Pilotiq/Articles/ArticleResource.ts` — minimal Resource using `static model` auto-fill.
+- `playground/app/Pilotiq/Posts/PostResource.ts` — folder-per-resource layout with split `Pages/`, `Schemas/`, `RelationManagers/`.
+- `playground/app/Pilotiq/Users/UserResource.ts` — authorization patterns (`canAccess` / `canEdit` / `canDelete`).