runlify 0.0.794 → 0.0.797

package/docs/09-options.md

@@ -0,0 +1,213 @@
+# Bootstrap Options (`BootstrapEntityOptions`)
+
+> **Load this file when:** you need to toggle a generation feature on/off, change
+> project identity settings, configure infrastructure (k8s, CI, Docker), or understand
+> what a specific option flag does.
+>
+> Source: `src/projectsGeneration/types.ts`
+> Consumed from: `src/meta/options.json` (read by `runlify regen`)
+
+---
+
+## How options are applied
+
+`options.json` is read once per `regen` and applied globally to all entities.
+Individual entities can receive their own options override by passing `options` as the
+third argument to `addCatalog`, `addDocument`, etc.:
+
+```ts
+system.addCatalog('specialCatalog', undefined, { ...defaultBootstrapEntityOptions, genUiResources: false })
+```
+
+Most projects use the same options object for all entities.
+
+---
+
+## All flags
+
+### Code generation toggles — Backend
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `genPrismaServices` | `true` | Generate Prisma-based service files |
+| `genPrismaSchema` | `true` | Generate `.prisma` schema files |
+| `genGraphSchema` | `true` | Generate GraphQL type definitions |
+| `genGraphResolvers` | `true` | Generate GraphQL resolvers |
+| `genContext` | `true` | Generate request context wiring |
+| `typesOnly` | `false` | Internal — first generation pass (types only). Do not set manually. |
+| `readOnly` | `false` | Skip write operations in generation. Rarely used. |
+| `corePrismaGetter` | `true` | Generate the Prisma client getter (`getPrisma.ts`) |
+| `coreIndex` | `true` | Generate the main `index.ts` entry point |
+
+---
+
+### Code generation toggles — Frontend
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `genFrontend` | `true` | Generate the entire frontend. Set `false` to generate backend only (`regen --backOnly` also sets this). |
+| `genUiResources` | `true` | Generate react-admin resource registrations |
+| `genUiResourcesPage` | `true` | Generate the `/resources` debug page |
+| `genUiEntityMapping` | `true` | Generate `entityMapping.ts` |
+| `genUiMenu` | `true` | Generate `getDefaultMenu.ts` |
+| `genUiElements` | `true` | Generate entity page components |
+| `genUiRoutes` | `true` | Generate `routes.tsx` |
+| `genUIApp` | `true` | Generate the root `App.tsx` |
+| `genUiFunctions` | `true` | Generate the functions page |
+| `genUiDashboard` | `true` | Generate `Dashboard.tsx` (created once) |
+| `genUiCountWidget` | `true` | Generate count widgets per entity |
+| `genUiListWidget` | `true` | Generate list widgets per entity |
+| `genUiAppBar` | `true` | Generate `AppBar.tsx` |
+| `showMetaPage` | `true` | Show the `/meta` debug page in the UI |
+
+---
+
+### Form generation toggles
+
+Nested under `forms`:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `forms.list.gen` | `true` | Generate list page components |
+| `forms.show.gen` | `true` | Generate show page components |
+| `forms.edit.gen` | `true` | Generate edit form components |
+| `forms.edit.idEditable` | `false` | Show `id` field in edit forms |
+| `forms.create.gen` | `true` | Generate create form components |
+| `forms.create.idEditable` | `false` | Show `id` field in create forms |
+| `forms.menu.show` | `true` | Show entity in sidebar menu |
+| `forms.resourcesPage.show` | `true` | Show entity on resources page |
+
+---
+
+### CI/CD — GitLab CI
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `genBackGitlabCi` | `true` | Generate `.gitlab-ci.yml` for backend |
+| `genUiGitlabCi` | `true` | Generate `.gitlab-ci.yml` for frontend |
+| `genBackCiNotify` | `true` | Include Slack/chat notifications in backend CI |
+| `genUiCiNotify` | `true` | Include Slack/chat notifications in frontend CI |
+
+---
+
+### CI/CD — Docker
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `genDockerfileBack` | `true` | Generate `Dockerfile` for backend |
+| `genDockerfileUI` | `true` | Generate `Dockerfile` for frontend |
+| `adminBaseDockerimage` | `'nginx:1.23-alpine'` | Base image for frontend Docker build |
+| `backendBaseDockerimage` | `'registry.gitlab.com/making.ventures/images/node-base'` | Base image for backend Docker build |
+
+---
+
+### Kubernetes / Helm
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `genBackChartValues` | `true` | Generate `chart/values.yaml` for backend |
+| `genBackChartIngress` | `true` | Generate `chart/templates/ingress.yaml` for backend |
+| `genBackChartBack` | `true` | Generate `chart/templates/back.yaml` for backend |
+| `genUiChartIngress` | `true` | Generate ingress chart for frontend |
+| `genUiChartFront` | `true` | Generate deployment chart for frontend |
+| `k8sChartName` | `''` | Helm chart name |
+| `k8sNamespacePrefix` | `''` | Kubernetes namespace prefix |
+| `k8sAppsDomain` | `'apps.making.ventures'` | Base domain for k8s ingress |
+| `k8sSubdomainPrefix` | `''` | Subdomain prefix applied to all ingress hosts |
+| `k8sImagePullSecrets` | `'docker-registry'` | k8s image pull secret name |
+| `ingressAnnotationBodySize` | `'50m'` | `nginx.ingress.kubernetes.io/proxy-body-size` annotation |
+
+---
+
+### Project identity
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `projectsGroup` | `''` | GitLab group or organisation name |
+| `projectPrefix` | `''` | Technical prefix (e.g. `'myapp'`) — used in k8s names, image tags |
+| `dbName` | `''` | Default database name in Postgres |
+| `projectName` | `''` | Human-readable project name |
+
+---
+
+### Feature flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `usersEnabled` | `true` | Generate user management entities and auth |
+| `tenantsAvailable` | `false` | Enable multi-tenancy support |
+| `themesEnabled` | `true` | Enable theme switching in UI |
+| `mainColorOfAppTitile` | `true` | Apply primary color to app title |
+| `sharding` | `false` | Enable sharding support globally |
+| `breadcrumb` | `false` | Enable breadcrumb navigation in UI |
+| `telemetry` | `false` | Enable OpenTelemetry tracing |
+| `mountebankEnabled` | `false` | Enable Mountebank mock server integration |
+| `exportHtmlEnabled` | `false` | Enable HTML export feature |
+| `auditableOnlyByUser` | `false` | Only audit changes made by users (not system) |
+| `useSortedFilter` | `false` | Use sorted filter UI in list pages |
+
+---
+
+### System menu visibility
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `showFunctionsInMenu` | `true` | Show system Functions page in menu |
+| `showResourcesInMenu` | `true` | Show Resources debug page in menu |
+| `showMetaInMenu` | `true` | Show Meta debug page in menu |
+
+---
+
+### Output paths
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `detachedBackProject` | `''` | Absolute path to the backend project. Auto-resolved to `../<prefix>-back` if empty. |
+| `detachedUiProject` | `''` | Absolute path to the frontend project. Auto-resolved to `../<prefix>-ui` if empty. |
+
+---
+
+### Other
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `skipWarningThisIsGenerated` | `false` | Suppress the `DO NOT EDIT! THIS IS GENERATED FILE` header |
+| `graphGeneratorCommand` | `''` | Command to run the local GraphQL schema generator (alternative to built-in) |
+
+---
+
+## Anti-patterns
+
+### Setting `typesOnly: true` in `options.json`
+
+**Wrong:** manually setting `typesOnly: true` in the options file.
+
+**Why:** this is an internal flag used by `generateProject` for the first generation
+pass. It produces an incomplete output — only TypeScript type files, no resolvers, no
+Prisma schema. If set permanently, your backend will be broken.
+
+**Correct:** never set `typesOnly` manually.
+
+---
+
+### Setting `genFrontend: false` in `options.json` permanently to skip frontend
+
+**Wrong:** permanently disabling frontend in `options.json` while the team still needs
+frontend generation.
+
+**Why:** other developers running `regen` won't regenerate the frontend, leading to
+divergent states.
+
+**Correct:** use the CLI flag `runlify regen --backOnly` for a one-off backend-only
+regen. It temporarily sets `genFrontend=false` without changing `options.json`.
+
+---
+
+### Leaving `projectPrefix`, `dbName`, `projectName` empty
+
+**Wrong:** keeping default empty strings in `options.json`.
+
+**Why:** these values are embedded into generated Helm chart names, Docker image tags,
+database names, and CI variables. Empty strings produce broken infrastructure configs.
+
+**Correct:** always set all three to meaningful values for your project.

package/docs/10-modules.md

@@ -0,0 +1,164 @@
+# Modules
+
+> **Load this file when:** you need to use a built-in module, understand what
+> `addCommonEntities` adds to the system, or write a reusable module function.
+>
+> Related: [02-system-meta-builder.md](./02-system-meta-builder.md) ·
+> [03-entity-types.md](./03-entity-types.md)
+
+---
+
+## What a module is
+
+A module is a plain function with the signature:
+
+```ts
+(system: SystemMetaBuilder) => void
+```
+
+It calls `system.addCatalog`, `system.addDocument`, `system.addConfigVar`, etc. to
+register a bundle of related entities and config in one call. There is no special
+registration mechanism — a module is just a function you call.
+
+---
+
+## `addCommonEntities(system)` {#addCommonEntities}
+
+Source: `src/projectsGeneration/commonEntities/addCommonEntities.ts`
+Import: `import { addCommonEntities } from 'runlify'`
+
+The standard foundation layer. Adds all infrastructure entities required by the
+framework itself. Most meta projects call this once near the top of `metadata.ts`.
+
+### What it adds
+
+| Entity | Type | Purpose |
+|--------|------|---------|
+| `languages` | Catalog | Supported UI languages |
+| `tenants` | Catalog | Tenants (only used when `tenantsAvailable=true`) |
+| `managers` | Catalog | Admin users |
+| `users` | Catalog | End users |
+| `auditLogs` | Catalog | Change history records |
+| `roles` | Catalog | Access roles |
+| `refreshTokens` | Catalog | JWT refresh token storage |
+| `autogeneration` | Catalog | Code generation tracking |
+| `aggregateTrackings` | Catalog | External search sync tracking |
+
+Plus:
+- Email module entities (see [`addEmailModuleEntities`](#addEmailModuleEntities))
+- Configuration variable entities (`configurationVariables` — stores runtime config in DB)
+- Standard system CLI commands
+
+**Anti-pattern — calling `addCommonEntities` after adding your own entities:**
+
+The common entities use fixed names. If you add a catalog named `users` or `roles`
+before calling `addCommonEntities`, the call throws (duplicate entity name).
+
+**Correct:** always call `addCommonEntities(system)` **before** adding your domain
+entities.
+
+---
+
+## `addEmailModuleEntities(system)` {#addEmailModuleEntities}
+
+Source: `src/projectsGeneration/modules/addEmailModuleEntities.ts`
+Import: `import { addEmailModuleEntities } from 'runlify'` (also called by `addCommonEntities`)
+
+Adds all entities required for the email / notification system.
+
+### What it adds
+
+| Entity | Type | Purpose |
+|--------|------|---------|
+| `messageTypes` | Catalog | Message type registry (e.g. `plain`) |
+| `templateStyles` | Catalog | HTML/CSS styles for email templates |
+| `messageTemplates` | Catalog | Email template definitions |
+| `mailingCampaignStatuses` | Catalog | Campaign lifecycle statuses |
+| `mailingCampaigns` | Catalog | Mailing campaign records |
+| `mailingMessages` | Catalog | Individual messages in a campaign |
+
+Called automatically by `addCommonEntities`. Only call it directly if you are NOT using
+`addCommonEntities` but still need the email module.
+
+**Anti-pattern — calling `addEmailModuleEntities` twice:**
+
+Called once by `addCommonEntities`. Calling it again throws duplicate entity name errors.
+
+---
+
+## Writing your own module {#custom-module}
+
+A module is just a function. Convention: one file per module, function named `add<ModuleName>`.
+
+```ts
+// src/meta/modules/addOrderingModule.ts
+import SystemMetaBuilder from 'runlify'
+
+export const addOrderingModule = (system: SystemMetaBuilder) => {
+  const orderStatuses = system.addCatalog('orderStatuses', { singular: 'Order status', plural: 'Order statuses' })
+  orderStatuses.getKey().setType('string')
+  orderStatuses.addField('title', undefined, { isTitleField: true }).setType('string').setRequired()
+  orderStatuses.addPredefinedElements([
+    { id: 'new', title: 'New' },
+    { id: 'processing', title: 'Processing' },
+    { id: 'completed', title: 'Completed' },
+  ])
+
+  const orders = system.addDocument('orders', { singular: 'Order', plural: 'Orders' })
+  orders.addField('amount').setType('float').setRequired()
+  orders.addLinkField(orderStatuses, 'statusId').setRequired()
+}
+```
+
+Then in `metadata.ts`:
+
+```ts
+import { addOrderingModule } from './modules/addOrderingModule'
+
+const system = new SystemMetaBuilder('myapp')
+addCommonEntities(system)
+addOrderingModule(system)
+```
+
+---
+
+## Module composition rules
+
+1. **Order matters.** Modules that reference entities from other modules must be called
+   after those modules.
+2. **No circular references.** Module A cannot reference entities that Module B adds, if
+   Module B also references entities from Module A.
+3. **Call `addCommonEntities` first** — it seeds `users`, `tenants`, `roles`, and other
+   system entities that domain modules typically reference.
+
+---
+
+## Anti-patterns
+
+### Defining a module that conditionally adds entities
+
+**Wrong:**
+```ts
+export const addOrderingModule = (system: SystemMetaBuilder, withReturns: boolean) => {
+  system.addDocument('orders')
+  if (withReturns) {
+    system.addDocument('returns')  // conditional entity
+  }
+}
+```
+
+**Why:** generates inconsistent meta across environments or team members. The system
+description must be deterministic and environment-independent.
+
+**Correct:** always include or always exclude. Use separate modules for separate
+feature sets: `addOrderingModule` and `addOrderingWithReturnsModule`.
+
+---
+
+### Putting module logic inside `metadata.ts` directly
+
+**Wrong:** writing 500 lines of entity definitions directly in `metadata.ts`.
+
+**Why:** hard to maintain, hard to reuse across projects, impossible to test in isolation.
+
+**Correct:** extract domain areas into module functions in `src/meta/modules/`.

package/docs/11-permissions.md

@@ -0,0 +1,231 @@
+# Permissions
+
+> **Load this file when:** you need to understand how access control works — which
+> permission gates a page/field/action, how permission strings are named, or how new
+> permissions get seeded into the database.
+>
+> Related: [07-backend-file-graph.md](./07-backend-file-graph.md) ·
+> [08-frontend-file-graph.md](./08-frontend-file-graph.md)
+
+---
+
+## Two permission spaces
+
+Runlify generates checks against **two distinct kinds** of permission string. They look
+similar but are enforced completely differently.
+
+| Space | Format | Enforced by | Meaning |
+|-------|--------|-------------|---------|
+| **Data** | `<entity>.<action>` | **Backend** — every GraphQL resolver checks it | Can the caller read/write this entity's data at all, from anywhere (its own page, a reference field on another page, an autocomplete, …) |
+| **UI** | `ui.<entity>.list` | **Frontend only** — never sent to or checked by the backend | Can the caller open this entity's own list page / see it in the menu |
+
+The split exists because a single `<entity>.all` permission used to do both jobs at
+once: granting it opened the entity's own list page **and** silently made the entity
+visible everywhere it's referenced from another entity (filters, autocompletes,
+reference fields, related-record tabs). Those are different concerns — someone might
+need to see a member's `memberType` label in the members list without ever needing to
+open the `memberTypes` list page themselves.
+
+`ui.<entity>.list` is **only ever checked in the generated frontend code**. It is never
+part of a GraphQL permission check, never appears in
+[`permissionsToGraphql.ts`](./07-backend-file-graph.md), and granting it does **not**
+give access to any data. It exists purely to gate navigation.
+
+---
+
+## Data-space actions
+
+| Action | Meaning |
+|--------|---------|
+| `.get` | Read a single record — gates the Show page and `ReferenceField` links to it |
+| `.all` | Read a list of records — gates list queries, autocompletes, filters, reference display |
+| `.meta` | Read list pagination metadata (total count) |
+| `.create` | Create a record |
+| `.update` | Update a record |
+| `.delete` | Delete a record |
+
+These come from `getRuntimePermissions()` (backend, not generated by Runlify — see
+[Where data-space permissions come from](#where-data-space-permissions-come-from)),
+which reflects over every service's methods. Any method a service exposes becomes a
+checkable permission; `get`/`all`/`meta`/`create`/`update`/`delete` exist simply because
+`BaseService` defines those methods and every entity service extends it.
+
+---
+
+## Where each permission is checked
+
+### Own page — `resources.ts`
+
+Each `<Resource>`'s `show`/`edit`/`create`/`list` prop is wrapped in
+[`withPermission`](#uti-lspermissionsts) so an unauthorized visit always renders a
+fallback component instead of `undefined` (see
+[Fallback components](#fallback-components)):
+
+| Resource prop | Required permissions |
+|---------------|----------------------|
+| `show` | `<entity>.get` |
+| `list` | `<entity>.all` **and** `<entity>.meta` **and** `ui.<entity>.list` |
+| `edit` | `<entity>.update` **and** `<ref>.all` for every **required** link field shown in the edit form |
+| `create` | `<entity>.create` **and** `<ref>.all` for every **required** link field shown in the create form |
+
+`list` needs all three because opening the list page requires reading records
+(`.all`), reading pagination metadata (`.meta`), and having UI access to the page
+itself (`ui.<entity>.list`) — the data permissions alone are not enough to open the
+page, and the UI permission alone is not enough to load any data.
+
+`edit`/`create` add the referenced entity's `.all` permission for every **required**
+link field, because a required autocomplete that the user cannot see would make the
+form impossible to submit. Optional link fields don't gate the whole page — see
+[Optional link fields](#optional-link-fields) below.
+
+### Referenced entity — everywhere else
+
+When an entity's data is shown or picked *from inside another entity's page* (not its
+own page), only the data-space `<ref>.all` / `<ref>.get` permissions are checked —
+never `ui.<ref>.list`. Seeing a reference's title, filtering by it, or autocompleting
+it does not require access to that entity's own list page.
+
+| Location | Permission checked |
+|----------|---------------------|
+| `ReferenceField` (List, Show `MainTab`, dependency tabs) | `<ref>.all` gates whether the field renders at all; `<ref>.get` gates whether it renders as a clickable link to the Show page |
+| `ReferenceInput` in a Filter | `<ref>.all` gates whether the whole input renders |
+| `rowClick` on a list Datagrid | `<entity>.get` — can the user open the Show page for the clicked row |
+| `BulkDeleteButton` / `DeleteButton` | `<entity>.delete` |
+| Menu item for an entity | `<entity>.all`, `<entity>.meta`, `ui.<entity>.list` — same trio as the list page, so a menu entry never links to a page the user can't open |
+
+### System pages — `ui.dashboard` / `ui.functions` / `ui.resources` / `ui.meta` {#system-pages}
+
+A handful of non-entity pages (Dashboard, Functions, Resources debug page, Meta debug
+page) use the same `ui.*` namespace, via `<Guard shouldHave='ui.<page>'>` in `routes.ts`
+and `permissions: ['ui.<page>']` on the corresponding menu item in `getDefaultMenu.ts`.
+They aren't tied to an entity, so they aren't generated by `uiPermissions.ts`'s
+per-entity loop — instead they're added conditionally based on the `BootstrapEntityOptions`
+flag that controls whether the page is generated at all (`genUiDashboard`,
+`showFunctionsInMenu`, `showResourcesInMenu`, `showMetaInMenu`). If a page is disabled
+in options, its `ui.*` permission isn't generated either.
+
+### Optional link fields — Create/Edit forms {#optional-link-fields}
+
+A link field that is **not required on input** doesn't gate the whole page. Instead,
+the individual autocomplete is hidden if the user lacks `<ref>.all` — the rest of the
+form still renders normally:
+
+```
+{debug && hasPermission(permissions, '<ref>.all') && <Grid item>...</Grid>}
+```
+
+(`debug &&` is a pre-existing, unrelated dev-only field toggle — it wraps every
+optional field, not just link fields.)
+
+A **required** link field is never hidden this way, because the form couldn't be
+submitted without it. Instead its permission is added to the page-level check in
+`resources.ts` (see the table above) — if the user can't see it, they can't open the
+page at all.
+
+---
+
+## `utils/permissions.ts` {#utils-permissionsts}
+
+Generated (`[gen]`) — see [08-frontend-file-graph.md](./08-frontend-file-graph.md).
+Exports four functions, all operating on the raw `permissions: string[]` array from
+`usePermissions()`:
+
+| Function | Behaviour |
+|----------|-----------|
+| `hasPermission(permissions, key)` | `true` if `key` matches (see below) |
+| `hasAnyPermission(permissions, keys)` | `true` if at least one of `keys` matches (empty `keys` → `true`) |
+| `hasAllPermissions(permissions, keys)` | `true` only if every key in `keys` matches (empty `keys` → `true`) |
+| `withPermission(permissions, keys, Component)` | Returns `Component` if `hasAllPermissions` passes, otherwise `PermissionPage` |
+
+**Matching:** a required key ending in `.*` (e.g. `'ui.memberTypes.*'`) matches by
+prefix — satisfied if at least one current permission starts with `'ui.memberTypes.'`.
+A plain key without `.*` is matched by exact equality.
+
+`withPermission` is what makes every `<Resource>` prop in `resources.ts` always resolve
+to a real component — never `undefined`. Passing `undefined` to a react-admin
+`<Resource>` prop causes react-router to silently fall through to a nearby catch-all
+route (usually `list`) instead of showing a permission error, which is confusing and
+was the original motivation for this file.
+
+---
+
+## Fallback components {#fallback-components}
+
+Two once (`[once]`) components, generated only if missing:
+
+| File | Content | Used when |
+|------|---------|-----------|
+| `src/adm/PermissionPage.tsx` | Re-exports react-admin's `AccessDenied` | `withPermission` denies access (missing permission) |
+| `src/adm/NotFoundPage.tsx` | Re-exports react-admin's `NotFound` | The action doesn't exist for this entity at all — e.g. `edit` when `entity.setUpdatableByUser(false)` |
+
+Both are safe to replace with a custom component — Runlify never touches them again
+once created. Anything importing `withPermission`'s fallback keeps working as long as
+the file still default-exports a component.
+
+---
+
+## Where data-space permissions come from {#where-data-space-permissions-come-from}
+
+`getRuntimePermissions.ts` is **not generated by Runlify** — it's a hand-written
+backend file (`src/adm/services/getRuntimePermissions.ts`) that reflects over every
+registered service's prototype chain at runtime and turns every method name into
+`<service>.<methodName>`. Because `BaseService` defines `get`/`all`/`meta`/`create`/
+`update`/`delete`, and every entity service extends it, those six actions exist for
+every entity automatically — no per-entity registration needed, in Runlify or
+anywhere else. Adding a new entity and running `regen` is enough; the next time
+`getRuntimePermissions()` runs, the new service's methods are picked up.
+
+This is separate from `initPermissions.ts` actually **inserting** rows into the
+`permissions` table — see the next section.
+
+---
+
+## Seeding permissions into the database {#seeding}
+
+```
+src/init/roles/
+  generated/
+    initPermissions.ts       [gen]   Collects all four sources, writes them to the DB
+    uiPermissions.ts         [gen]   One 'ui.<entity>.list' per entity + enabled system pages (see #system-pages)
+  customPermissions.ts       [once]  Hand-written data-space permissions (empty array to start)
+  customUiPermissions.ts     [once]  Hand-written UI-space permissions (empty array to start)
+```
+
+The two `[gen]` files are grouped in `generated/` so it's visually unambiguous which
+files in this directory are regenerated and which are yours — the two `custom*.ts`
+files sit one level up, outside `generated/`.
+
+`initPermissions.ts` merges four sources and calls
+`ctx.service('permissions').createMany(...)`:
+
+```
+getRuntimePermissions(ctx)   ← reflected data-space permissions (see above)
+uiPermissions                ← generated 'ui.<entity>.list' list, one per entity
+customPermissions            ← your hand-written extras (data-space)
+customUiPermissions          ← your hand-written extras (UI-space)
+```
+
+Running `initPermissions` (via `yarn init:permissions` or equivalent) is a **manual
+step** — it is not triggered automatically by `regen`. A new entity's permissions exist
+in code as soon as `regen` finishes (the service exists, `uiPermissions.ts` lists it),
+but they only land in the `permissions` table the next time someone runs the seed
+script.
+
+**Anti-pattern — adding a custom permission string directly to `initPermissions.ts` or
+`uiPermissions.ts`:**
+
+Both are `[gen]` — overwritten on every `regen`. Add hand-written permissions to
+`customPermissions.ts` (data-space) or `customUiPermissions.ts` (UI-space) instead.
+
+---
+
+## Naming a new permission
+
+- Data-space, tied to an existing service method → nothing to name; it already exists
+  via reflection.
+- Data-space, not backed by a service method (a custom action) → add it to
+  `customPermissions.ts`, as `<entity-or-domain>.<action>`, matching the existing
+  `<entity>.<action>` convention.
+- UI-only, not covered by the generated `ui.<entity>.list` set → add it to
+  `customUiPermissions.ts`, prefixed `ui.` so it's unambiguous that it is never
+  enforced by the backend.

package/docs/INDEX.md

@@ -0,0 +1,70 @@
+# Runlify Documentation
+
+> Written for **consumers** of Runlify — projects that already use it.
+> Primary audience: AI agents. Secondary: human developers.
+>
+> Each file in this documentation is **self-contained** for its topic.
+> Load only the file relevant to your current task.
+
+---
+
+## Table of Contents
+
+| # | File | Topic |
+|---|------|-------|
+| 1 | [01-overview.md](./01-overview.md) | Mental model, data flow, two classes of files (generated vs yours) |
+| 2 | [02-system-meta-builder.md](./02-system-meta-builder.md) | All top-level methods on `SystemMetaBuilder` |
+| 3 | [03-entity-types.md](./03-entity-types.md) | `Catalog`, `Document`, `InfoRegistry`, `SumRegistry`, `Report` — when to use each |
+| 4 | [04-fields.md](./04-fields.md) | All field builders, scalar types, filters, indexes, constraints |
+| 5 | [05-custom-methods.md](./05-custom-methods.md) | `MethodBuilder`, Input/Output models, workers, cron schedules |
+| 6 | [06-storage.md](./06-storage.md) | `StorageType` options: Postgres, ClickHouse, Elasticsearch |
+| 7 | [07-backend-file-graph.md](./07-backend-file-graph.md) | Annotated file tree for `<prefix>-back` |
+| 8 | [08-frontend-file-graph.md](./08-frontend-file-graph.md) | Annotated file tree for `<prefix>-ui` |
+| 9 | [09-options.md](./09-options.md) | All `BootstrapEntityOptions` flags with defaults |
+| 10 | [10-modules.md](./10-modules.md) | Built-in modules, how to write your own |
+| 11 | [11-permissions.md](./11-permissions.md) | Data-space vs UI-space permissions, where each is checked, how they're seeded |
+
+---
+
+## Quick orientation
+
+```
+meta-project/
+  src/meta/metadata.ts     ← you write this (SystemMetaBuilder DSL)
+  src/meta/options.json    ← generation options (BootstrapEntityOptions)
+
+runlify regen              ← regenerates everything from the meta
+
+<prefix>-back/             ← generated NestJS/Prisma/GraphQL backend
+<prefix>-ui/               ← generated react-admin frontend
+```
+
+The meta project **describes** the system. Runlify **generates** the implementation.
+Business logic lives only in files Runlify creates once and never overwrites.
+
+---
+
+## Two classes of files
+
+| Class | Owner | Overwritten on `regen`? | Marker |
+|-------|-------|------------------------|--------|
+| **Generated** (`[gen]`) | Runlify | **Yes — every run** | `DO NOT EDIT! THIS IS GENERATED FILE` at top |
+| **Yours** (`[yours]` / `[once]`) | Developer | No — created only if missing | Most have no marker; some (e.g. `PermissionPage.tsx`, `i18n/<lang>/index.ts`) have a short `Generated once, not overwritten on next generation. Edit freely.` note instead |
+
+Yours files: `Additional<Entity>Service.ts`, `hooks/*`, `additionalRoutes.tsx`,
+`Dashboard.tsx`, `getAdditionalMenu.ts`, `restRouter.ts`, `PermissionPage.tsx`,
+`NotFoundPage.tsx`, `customPermissions.ts`, `customUiPermissions.ts`, and others.
+See [07-backend-file-graph.md](./07-backend-file-graph.md) and [08-frontend-file-graph.md](./08-frontend-file-graph.md) for the full list.
+
+---
+
+## Features not covered in this documentation
+
+The following exist in Runlify but are intentionally omitted here — they are used
+selectively and vary significantly per project. Refer to the Runlify source at
+`src/projectsGeneration/builders/` and `src/commands/` for details.
+
+- **Workers** — `addWorker()` on `SystemMetaBuilder`
+- **Telegram Bots** — `addTelegramBot()` on `SystemMetaBuilder`
+- **Integration Clients** — `addIntegrationClient()` on `SystemMetaBuilder`
+- **Cloud CLI** — `login`, `pullEnvs`, `runlify start` commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runlify",
-  "version": "0.0.794",
+  "version": "0.0.797",
   "description": "runlify CLI",
   "private": false,
   "repository": {