@adula/kit 0.2.0-alpha.4 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @adula/kit
 
-Experimental 0.2.0-alpha.4 resource framework for AdonisJS 7 and PostgreSQL 17. Node 24 or later is required. MIT licensed. The target is the complete approved 1.0 scope; it has not passed acceptance.
+Resource framework for AdonisJS 7 and PostgreSQL 17, version 1.0.0 (accepted by the owner, ADR 028). Node 24 or later is required. MIT licensed. The public API in `api/kit-api.json` follows semantic versioning.
 
 ## Install into a consumer
 
@@ -28,4 +28,14 @@ Doctor measures the deployment's `storage/uploads` directory and warns above 5 d
 
 ## Current limitations
 
-Attachment ownership, upload/download, storage migration, authentication lifecycle/rate limiting, generic resource UI and core administration have local integration consumers and tests. Real OAuth/SMTP, full Tuyau field contracts, human/performance acceptance, XState workflows, later business features, staging/offsite restoration and a genuine minor-version consumer upgrade remain open. Submission envelopes are durable records in pending_definition state, not running workflows. See [implementation status](https://github.com/adulash/adula-kit/blob/main/docs/implementation-status.md), [gaps](https://github.com/adulash/adula-kit/blob/main/KIT_GAPS.md) and [1.0 acceptance](https://github.com/adulash/adula-kit/blob/main/docs/acceptance-1.0.md). Version 0.2.0-alpha.4 targets alpha; the owner-authorized latest alias remains on 0.2.0-alpha.1.
+Phases 3 and 4 (collaboration, assignments, templates and realtime notifications,
+CSV import, printing, webhooks, API tokens/OpenAPI, amend-by-copy and versioned
+XState workflows) are implemented with PostgreSQL tests; see the
+[business features guide](https://github.com/adulash/adula-kit/blob/main/docs/business-features.md).
+
+- Two-factor authentication is not included; it is planned for 2.0 (ADR 027).
+- Impersonation was reviewed by automated adversarial and black-box tests only; its
+  human security review is deferred to 2.0 (ADR 027).
+- XLSX import is not available (GAP-006); CSV is.
+
+See [implementation status](https://github.com/adulash/adula-kit/blob/main/docs/implementation-status.md), [gaps](https://github.com/adulash/adula-kit/blob/main/KIT_GAPS.md) and [1.0 acceptance](https://github.com/adulash/adula-kit/blob/main/docs/acceptance-1.0.md).

package/build/agent/AGENTS.template.md

@@ -16,11 +16,11 @@ Structure
 8. Deletes are soft. Changeable lists come from lookups. Approvable documents use `submittable: true`.
 9. Notify via notify(), number via sequence, configure via settings. Nothing else.
 
-Security 10. Every route passes the authorize middleware. Every transformer uses `serialize` (explicit pick). 11. Never write crypto, sessions, or auth flows; use kit. 2FA and impersonation changes need a human review. 12. Never delete or weaken a test to make the build pass.
+Security 10. Every route passes the authorize middleware. Every transformer uses `serialize` (explicit pick). `systemSave` and `rehome` skip role rules: use them only in listeners and module services after an explicit authorization, never in a controller or route (enforced by lint). 11. Never write crypto, sessions, or auth flows; use kit. 2FA and impersonation changes need a human review. 12. Never delete or weaken a test to make the build pass.
 
 UI 13. Before designing or changing any interface, read and apply `.agents/skills/adula-frontend-design/SKILL.md` (the kit's bundled frontend-design skill for business applications). At project kickoff, request the company's identity before the first design: name, logo, colors, fonts and brand guidelines when available. Reuse supplied identity, ask only for missing information, and preserve it in project-owned docs/design-identity.md. Fill the resource definition before writing a page. Override only via pages/<resource>/. 14. Compose interfaces from the project-owned shadcn/ui components in inertia/components/ui/. Use Button, Input, Select, Table, Card and the other registry primitives instead of hand-styled native controls or homemade equivalents. Semantic HTML for structure, text and form submission is allowed. Add components only via `node ace adula:ui add`, never `shadcn add`. 15. All forms (including create/edit) and row/record detail views use shadcn Dialog (modal) by default. Use ResourceSurface for resource forms/details; do not choose a standalone page, Sheet or custom overlay unless the user explicitly requests that alternative. View dialogs close on outside click; edit dialogs ask before closing by default. Honor system preferences for Gregorian, Hijri or both calendars and reduced motion. RTL by default; Arabic labels; English identifiers. Installation terminal instructions are English. Preserve explicit user exceptions and project-owned customizations.
 
-Boundaries 16. Never modify node_modules/@adula and never use patch-package (enforced by lint). Do not re-implement a kit service under another name (checked in review). 17. A limitation is recorded in KIT_GAPS.md (template inside) and reported to the developer — never worked around. 18. Only packages already in package.json. Ask before adding one. 19. New module or workflow → run the idea-review skill first. Field changes do not need it. 20. Before finishing: `npm run typecheck && npm test && node ace adula:doctor`.
+Boundaries 16. Never modify node_modules/@adula and never use patch-package (enforced by lint). Do not re-implement a kit service under another name (checked in review). 17. A limitation is recorded in KIT_GAPS.md (template inside) and reported to the developer — never worked around. Describe the kit capability, not this project, and reproduce it on a new application from create-app. The developer submits it through the prefilled form link printed by `node ace adula:gaps report`, then records `Issue: #<number>`; never open kit issues through the API. 18. Only packages already in package.json. Ask before adding one. 19. New module or workflow → run the idea-review skill first. Field changes do not need it. 20. Before finishing: `npm run typecheck && npm test && node ace adula:doctor`.
 <!-- adula-kit:end -->
 
 ## Project rules

package/build/agent/capabilities.md

@@ -1,13 +1,60 @@
-# Current capabilities
+# adula-kit capabilities (1.2.0)
 
-Version 0.2.0-alpha.4, experimental alpha. Resource definitions and registry; six flat condition operators (typed limits documented in KIT_GAPS.md); CASL evaluation with structural ltree scope; JSON/Inertia resource CRUD; field contracts; keyset pagination; sequences/lookups/settings; soft deletion; optimistic concurrency; atomic inline writes/activity/outbox; deduplicated database listeners; org moves; attachment ownership/storage migration; saved views (queries limited to fields the author may query); attachment fields with per-field `accept`/`maxSize` limits and daily pruning of unbound uploads; case-insensitive e-mail identity with ownership proof before OAuth linking; `adula:gaps report`; core administration services; resource/module commands; copied shadcn UI and installation diagnostics.
+Generated by `node ace adula:capabilities`. Read this before proposing a module; anything not listed here is not provided by the kit.
 
-The reference consumer wires authentication/session lifecycle, admin screens, authorized attachments, optional MCP, Redis actor caching, a queue worker, one scheduler and backup/restore drills. Educational modules are isolated test fixtures, not installed application features. The agent ships business frontend-design and idea-review skills, company identity intake and modal defaults. Real SMTP receipt/recovery and isolated offsite local/source-S3 attachment recovery are documented in the source repository's confirmed-achievements ledger. OAuth is optional and externally unverified. Source-S3 recovery is integrated into the operational backup commands and verified directly; local Docker backup/recovery also passed; natural scheduled operation and staging remain pending; each consumer must verify its own configuration.
+## Resource definition
 
-This is not the 1.0 capability catalog. Planned features are listed in docs/implementation-status.md of the adula-kit source repository; do not assume them.
+| Field type | Storage |
+|---|---|
+| string | varchar |
+| text | text |
+| integer | integer |
+| money | bigint minor units, decimal string in JSON |
+| boolean | boolean |
+| date | date (YYYY-MM-DD) |
+| datetime | timestamptz |
+| json | jsonb |
+| attachment | attachments row id; per-field accept/maxSize |
+| belongsTo | foreign key, preloaded, restrict on delete |
+| user | users foreign key, restrict on delete; choices are active members of the record unit or its ancestors; related as { id, fullName } |
+| hasMany | child resource; inline rows saved with the parent |
+| lookup | lookups group key |
 
-Core user invitations are available through `UserInvitations` and the `core.users/invite` permission. New standalone projects include an Arabic invitation Dialog, SMTP mail and single-use 24-hour acceptance links; recipients set their own passwords and receive no automatic roles. Configure SMTP and APP_URL, then assign business roles after acceptance. Existing consumers must merge project-owned routes/pages deliberately.
+Field options: required, unique (partial, active rows), sortable, searchable (generated tsvector), filterable, permissionLevel, sequence, column.
 
-Administrative mutations protect the last active administrator and the acting administrator's own access. Repeated installation repairs missing bootstrap grants. The reference settings screen controls Gregorian, Umm al-Qura Hijri or dual-calendar presentation, edit-dialog dismissal confirmation and restrained transitions. Storage and API dates stay canonical. Permission actions require confirmation and report server outcomes.
+Resource options: scoped (required), scope.from (the unit follows a required belongsTo parent), title (fields that name the record in relations, pickers, tasks and approvals), submittable (docStatus, submit/cancel/amend-by-copy), version (optimistic locking, default with submittable), customFields, list / form / show / serialize / hidden, actions, hooks.beforeSave / hooks.afterSave.
 
-The separate @adula/create-app package creates a complete application from an empty directory, including local service provisioning, fresh migrations, an administrator and company identity intake. Node/npm and Docker for the default service mode are prerequisites; existing PostgreSQL/Redis can be used instead. The packages are published on npm under the experimental `alpha` tag: `npm create @adula/app@alpha my-app`.
+Role rule conditions: $eq, $ne, $in, $lt, $gt, $like on scalar fields; unsupported conditions are refused. Organization scope is always added with AND. `$actor.id` names the signed-in user on user fields, createdBy and updatedBy ($eq, $ne, $in), bound per request.
+
+Workflow steps: condition, update, notify, approval, decision, delay, http, end. Workflow and step names: use lower-case letters, digits and underscores, starting with a letter (for example release_approval, notify_approved).
+
+## Services
+
+- **Resources and authorization:** `defineResource`, `ResourceRegistry`, `ResourceService`, `createResourceController`, `buildAbility`, `accessibleBy`, `ActorStore`, `packedResourceRules`
+- **Records and collaboration:** `RecordCollaboration`, `followerListeners`, `Assignments`, `SavedViews`, `logActivity`
+- **Documents and workflows:** `defineWorkflow`, `WorkflowEngine`, `workflowListeners`
+- **Notifications and messages:** `notify`, `notifyWithTemplate`, `MessageTemplates`, `deliverNotificationMail`, `listenForNotifications`, `NotificationsAdmin`
+- **Integration:** `Webhooks`, `signWebhook`, `InboundWebhooks`, `openApiDocument`, `ImportBatches`, `renderPrintHtml`, `htmlToPdf`
+- **Security:** `UserInvitations`, `UsersAdmin`, `RolesAdmin`
+- **Data and operations:** `sequence`, `Settings`, `SettingsAdmin`, `publishOutbox`, `consumeEvent`, `recordMutation`, `moveOrgUnit`, `migrateStorage`, `verifyBackup`, `runtimeHealth`
+
+## Extension points
+
+- Resource hooks (beforeSave, afterSave) inside the save transaction
+- ResourceService.systemSave for module-decided writes (validator, hooks and audit, no role rules); ResourceService.rehome after a parent moves
+- Assignment closing notes (Assignments closeNote: optional or required); managed assignments (managed: true) closed by module code with Assignments.close
+- Page override: inertia/pages/<resource>/{index,form,show}.tsx replaces the generated page
+- Create links with defaults: /resources/<resource>/create?defaults[field]=value
+- Domain events <module>.<resource>.{created,updated,deleted,submitted,cancelled,amended} with idempotent listeners
+- Module workflows (Module.workflows) with versioned definitions
+- Message templates edited per deployment
+- Outgoing webhooks and the bearer-token /api/v1 API
+- Signed inbound webhooks raising inbound.<source>.<event> through the outbox
+
+## Outside the kit
+
+- Dynamic fields or a field editor screen
+- Runtime plugins
+- A visual workflow editor
+- Multi-tenant SaaS in one database (one deployment per organization)
+- XLSX import until a maintained parser passes the dependency rule (GAP-006)

package/build/agent/skills/adula-frontend-design/SKILL.md

@@ -46,7 +46,7 @@ Install missing registry components with `node ace adula:ui add <component>`. Ne
 
 Every form and every row/record detail view opens in a shadcn Dialog unless the user explicitly requests another presentation. This includes create/edit forms and custom page overrides. Do not infer a page or Sheet exception from screen size, form length or personal design preference.
 
-For resource routes, use `ResourcePage`, which selects the modal surface by default. For a custom form/detail override, wrap its content in `ResourceSurface` with a title, description and the list's `backHref`. It keeps direct URLs usable and returns to the list when dismissed. Use `presentation="page"` only for a user-requested page exception. Keep embedded line-item fields within their parent's form, not separate nested forms. Search and filter controls may stay in the list toolbar; their form element is submission structure, not a separate record form.
+For resource routes, use `ResourcePage`, which selects the modal surface by default. For a custom form/detail override, wrap its content in `ResourceSurface` with a title, description and the list's `backHref`. It keeps direct URLs usable and returns to the list when dismissed. From a list, open records with `openRecord(resource, id, 'show' | 'edit')` (exported by `resource-surface`): the dialog opens over the mounted list, and closing keeps its query, loaded rows and scroll. Use `presentation="page"` only for a user-requested page exception. Keep embedded line-item fields within their parent's form, not separate nested forms. Search and filter controls may stay in the list toolbar; their form element is submission structure, not a separate record form.
 
 Give every Dialog a visible DialogTitle and a useful DialogDescription. Keep long content scrollable within the viewport, Arabic RTL alignment, an accessible close control, focus containment and Escape dismissal. Use shadcn components inside the modal too. Keep validation and conflict messages inside it, preserve typed values on errors, and keep unauthorized actions absent. Do not replace server authorization with UI checks.
 

package/build/agent/skills/idea-review/SKILL.md

@@ -3,4 +3,29 @@ name: idea-review
 description: Translate a new module or workflow into existing kit resources and declared extension points before writing code.
 ---
 
-Read docs/decisions, the resource registry, capabilities and KIT_GAPS.md. Identify existing entities before proposing new ones. Produce a compact module blueprint with owned tables, explicit scope, dependencies, relationships, events, field visibility and acceptance tests. Classify each requirement as implemented now, a declared extension, or outside the kit. Do not design a dynamic field editor, runtime plugin loader or visual workflow editor. A user's already-approved plan authorizes its specified reference modules; do not ask to approve them again.
+Use for a new module or workflow only; field changes do not need it.
+
+1. Run `node ace adula:capabilities` and read the output: kit field types, services,
+   workflow steps, extension points, what is outside the kit, and this project's
+   registered modules, resources and workflows. Read docs/decisions and KIT_GAPS.md.
+2. Find existing entities with the same meaning; reference them with belongsTo.
+   Never duplicate a table owned by another module.
+3. Produce a compact blueprint:
+   - module name, `dependsOn`, owned resources with `scoped` stated explicitly;
+   - fields with kit types, required/unique/searchable/filterable, permission levels,
+     hidden fields, lookups (groups and keys) and sequences;
+   - submittable documents and their workflow as steps (condition, update, notify,
+     approval, delay, http, end) with approvers by role;
+   - events consumed and emitted, listeners (idempotent) and any webhooks;
+   - role rules per action, including conditions from the six operators;
+   - acceptance tests: 403/404/uniqueness/scope from the generator plus the
+     business rules.
+4. Classify each requirement: **now** (kit capability), **extension** (hooks, page
+   override, listener, workflow), or **outside the kit** (record it in KIT_GAPS.md
+   with Needed by, Tried, Blocked because, Proposed kit change, Workaround).
+5. Never design a dynamic field editor, runtime plugin loader, visual workflow editor
+   or a second tenant model. An already-approved plan authorizes its modules; do not
+   ask to approve them again.
+
+After implementation, run the reviewers: module-review, security-review,
+schema-review, ui-review and perf-review.

package/build/agent/skills/module-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: module-review
+description: Review a module's boundaries, dependencies, events and scope before merging.
+---
+
+Check, citing file and line for every finding:
+
+- The module lives in `app/modules/<name>` and is registered in `start/modules.ts`
+  after every module it depends on; `dependsOn` lists each module whose resources
+  it references. `ResourceRegistry.register` must accept the order.
+- It writes only its own tables. Cross-module effects happen in idempotent
+  listeners (`consumeEvent` + processed_events), never by importing another
+  module's controllers or services. Heavy listeners dispatch jobs.
+- Every resource declares `scoped`. Central (`scoped: false`) resources are
+  justified; scoped ones rely on the kit's organization scope, not custom filters.
+- Documents that need approval use `submittable: true` and a module workflow; the
+  operational status is a lookup separate from `docStatus`.
+- No kit service is re-implemented under another name (notify, sequence, settings,
+  assignments, comments, imports, webhooks, workflows).
+- Educational fixtures are not imported by the application.
+
+Verdict: accept, or a numbered list of blocking findings.

package/build/agent/skills/perf-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: perf-review
+description: Review queries, pagination and background work against the performance budget.
+---
+
+Budget (plan section 13): list with two relations p95 < 300 ms, form save < 200 ms,
+cached Ability build < 5 ms, on 100,000 seeded rows and 50 concurrent users.
+
+Check, citing file and line:
+
+- Lists go through `ResourceService.list`: keyset pagination, limit ≤ 100, selected
+  columns only, belongsTo preloaded in one query per relation; no query in a loop.
+- Custom queries have supporting indexes (foreign keys, `(org_unit_id, deleted_at)`,
+  sort columns used by saved views); `EXPLAIN` shows no sequential scan on large
+  tables for the common filters.
+- Save paths keep one transaction: record, lines, activity, field changes and outbox.
+  Anything slow (mail, HTTP, PDF, imports) runs in the worker, never inline.
+- Listeners are idempotent and cheap or dispatch jobs; workflows do not poll.
+- Caches (Ability, lookups, settings) are invalidated by the kit's revision rules,
+  not by time alone.
+- Run `pnpm test:medical` with `K6_BINARY` on staging-like hardware before release
+  and record the measured p95 values; never relax the thresholds.
+
+Verdict: accept, or findings with the measurement or query plan.

package/build/agent/skills/schema-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: schema-review
+description: Review migrations and resource definitions for integrity and evolution.
+---
+
+Check, citing file and line:
+
+- Migrations are additive (expand/contract): no drop or rename of a column still
+  read by the previous release; kit migrations are never edited after release.
+- Standard columns come from the generator (`id`, `org_unit_id` when scoped,
+  `created_by`, `updated_by`, timestamps, `deleted_at`, `version`, `doc_status`,
+  `amended_from_id`); they are not hand-edited.
+- Every foreign key is indexed and `restrict` on delete (cascade only inside the
+  same module); `(org_unit_id, deleted_at)` exists for scoped tables.
+- Unique rules are partial (`WHERE deleted_at IS NULL`); searchable fields produce
+  the generated tsvector with a GIN index.
+- Money is bigint minor units; dates use `date`, instants `timestamptz`; changeable
+  lists are lookups, numbering uses sequences.
+- The definition's `form`, `list`, `show` and `serialize` match the columns, and
+  generated contract tests cover 403/404/uniqueness/scope.
+
+Verdict: accept, or blocking findings with the corrected migration.

package/build/agent/skills/security-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: security-review
+description: Review authorization, serialization and sensitive flows of a change.
+---
+
+Check, citing file and line:
+
+- Every route passes authentication and the resource goes through ResourceService
+  (or `resources.access` for record features). Custom queries use `accessibleBy`;
+  nothing reads records by id without the scope and Ability checks.
+- Responses use the kit serializers; hidden and `permissionLevel` fields never leave
+  the server, including through search, sort, filters, exports, prints, history,
+  notifications, webhooks and OpenAPI.
+- Role rules use only the six operators; nothing widens scope with an allow rule.
+- No hand-written crypto, sessions, password or token handling. Secrets are sealed
+  with the application encryption; tokens and recovery codes are stored hashed.
+- Outgoing HTTP (webhooks, workflow steps) targets HTTPS and cannot reach private
+  addresses in production; payloads carry identifiers, not record fields.
+- Uploads and imports are size-limited and parsed by the kit; errors never echo
+  secrets. Rate limits cover authentication, second factor and token creation.
+- 2FA, impersonation and authentication changes are flagged for human review
+  (AGENTS rule 11); map the change to ASVS 4.0.3 V2/V3/V4 items.
+
+Verdict: accept, or blocking findings with the exploit scenario for each.

package/build/agent/skills/ui-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: ui-review
+description: Review pages and components for RTL, the component system and data access.
+---
+
+Check, citing file and line:
+
+- Components come from `inertia/components/ui` (installed by `node ace adula:ui add`);
+  no `shadcn add` in modules, no hand-styled native controls or homemade dialogs.
+- Forms and record details use the shadcn Dialog (ResourceSurface) unless the user
+  asked otherwise; destructive actions confirm; edits guard against closing.
+- RTL: `dir="rtl"`, logical properties (`ms-`, `ps-`, `text-start`), arrows follow
+  the reading direction, Latin digits in amounts per the UI preference, Arabic
+  labels and English identifiers. Dates honor the calendar preference.
+- Generated pages are overridden only through `pages/<resource>/<mode>.tsx`.
+- Heavy sections are deferred props or fetched after render; lists paginate with
+  the scroll prop; no page renders data the server did not serialize for the user.
+- Accessible names exist for icon buttons, dialogs and regions; errors use
+  `role="alert"`; focus stays inside dialogs.
+- Company identity from docs/design-identity.md is applied, not invented.
+
+Verdict: accept, or findings with screenshots or selectors.

package/build/commands/capabilities.d.ts

@@ -2,5 +2,9 @@ import { BaseCommand } from '@adonisjs/core/ace';
 export default class Capabilities extends BaseCommand {
     static commandName: string;
     static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    write: boolean;
     run(): Promise<void>;
 }

package/build/commands/capabilities.js

@@ -1,9 +1,40 @@
-import { BaseCommand } from '@adonisjs/core/ace';
-import { readFile } from 'node:fs/promises';
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, flags } from '@adonisjs/core/ace';
+import { writeFile } from 'node:fs/promises';
+import { capabilityCatalog } from '../src/commands/capabilities.js';
 export default class Capabilities extends BaseCommand {
     static commandName = 'adula:capabilities';
-    static description = 'Print implemented capabilities and current acceptance boundary';
+    static description = 'Generate the capability catalog (kit features plus this project registry)';
+    static options = { startApp: true };
     async run() {
-        this.logger.log(await readFile(new URL('../agent/capabilities.md', import.meta.url), 'utf8'));
+        let registry;
+        try {
+            ;
+            ({ registry } = await this.app.import('#start/modules'));
+        }
+        catch {
+            this.logger.warning('start/modules could not be loaded; printing kit capabilities only');
+        }
+        // Imported lazily: main.ts lists this command itself.
+        const { getMetaData } = await import('./main.js');
+        const metadata = await getMetaData();
+        const catalog = capabilityCatalog({
+            registry,
+            commands: metadata.map((command) => `${command.commandName} — ${command.description}`),
+        });
+        if (this.write) {
+            await writeFile(this.app.makePath('capabilities.md'), catalog);
+            this.logger.success('capabilities.md');
+        }
+        else
+            this.logger.log(catalog);
     }
 }
+__decorate([
+    flags.boolean({ description: 'Write capabilities.md at the project root' })
+], Capabilities.prototype, "write", void 0);

package/build/commands/doctor.js

@@ -1,9 +1,11 @@
 import { BaseCommand } from '@adonisjs/core/ace';
 import { fileURLToPath } from 'node:url';
-import { diagnose } from '../src/commands/doctor.js';
+import { diagnose, diagnoseResourceSnapshots, diagnoseOutbox, diagnoseWorkflowRoles, } from '../src/commands/doctor.js';
+import { runtimeHealth } from '../src/core/health.js';
 import { diagnoseAttachments } from '../src/attachments/doctor.js';
 import { Settings } from '../src/services/settings.js';
 import { MigrationRunner } from '@adonisjs/lucid/migration';
+import { readFile } from 'node:fs/promises';
 export default class Doctor extends BaseCommand {
     static commandName = 'adula:doctor';
     static description = 'Check kit ownership, installation and backup readiness';
@@ -12,6 +14,7 @@ export default class Doctor extends BaseCommand {
         const { default: db } = await import('@adonisjs/lucid/services/db');
         const findings = await diagnose(fileURLToPath(this.app.appRoot), new Settings(db.connection().getWriteClient()), this.app.inProduction, process.env);
         findings.push(await diagnoseAttachments(db.connection().getWriteClient()));
+        findings.push(diagnoseOutbox(await runtimeHealth(db.connection().getWriteClient())));
         const migrations = await new MigrationRunner(db, this.app, { direction: 'up' }).getList();
         const missing = migrations.filter((entry) => entry.status === 'corrupt');
         const pending = migrations.filter((entry) => entry.status === 'pending');
@@ -24,6 +27,39 @@ export default class Doctor extends BaseCommand {
                     ? `${pending.length} pending migrations; run migration:run after the deployment backup`
                     : 'Migration files and database history agree',
         });
+        const sources = [];
+        for (const entry of pending)
+            for (const extension of ['.ts', '.js'])
+                try {
+                    const file = `${entry.name}${extension}`;
+                    sources.push({ file, source: await readFile(this.app.makePath(file), 'utf8') });
+                    break;
+                }
+                catch { }
+        let registry;
+        try {
+            ;
+            ({ registry } = await this.app.import('#start/modules'));
+        }
+        catch { }
+        if (registry) {
+            // Before the 1.1 migrations run, roles have no key column yet (an unfinished upgrade).
+            const keyed = await db.connection().getWriteClient().schema.hasColumn('roles', 'key');
+            const roles = await db.from('roles').select(keyed ? ['key', 'name'] : ['name']);
+            findings.push(diagnoseWorkflowRoles(registry.workflows(), roles.map((role) => ({
+                key: role.key ? String(role.key) : null,
+                name: String(role.name),
+            }))));
+        }
+        if (registry)
+            findings.push(diagnoseResourceSnapshots(sources, (name) => {
+                try {
+                    return registry.get(name);
+                }
+                catch {
+                    return undefined;
+                }
+            }));
         for (const finding of findings)
             this.logger.log(`${finding.status.toUpperCase()} ${finding.check}: ${finding.message}`);
         if (findings.some((finding) => finding.status === 'fail'))

package/build/commands/gaps.js

@@ -10,7 +10,7 @@ import { gapReport } from '../src/commands/gap_report.js';
 /** Collects KIT_GAPS.md for reporting; nothing leaves the machine without explicit confirmation. */
 export default class Gaps extends BaseCommand {
     static commandName = 'adula:gaps';
-    static description = 'Show the project gap report with private names masked before it is sent';
+    static description = 'Show the project gap report with private names masked, and links that open the kit gap form prefilled';
     static options = { startApp: false };
     async run() {
         if (this.action !== 'report')
@@ -23,16 +23,26 @@ export default class Gaps extends BaseCommand {
         catch {
             throw new Error('KIT_GAPS.md does not exist; adula:install creates it');
         }
-        const { masked, titles } = gapReport(content);
-        this.logger.info(`${titles.length} gap(s) recorded in KIT_GAPS.md`);
-        for (const title of titles)
-            this.logger.log(`  ${title}`);
+        const { masked, gaps } = gapReport(content);
+        this.logger.info(`${gaps.length} gap(s) recorded in KIT_GAPS.md`);
+        for (const gap of gaps)
+            this.logger.log(`  ${gap.title}${gap.issue ? ` (reported: ${gap.issue})` : ''}`);
         if (!this.yes) {
-            const confirmed = await this.prompt.confirm('Show the full masked report? Nothing is sent anywhere by this command.');
+            const confirmed = await this.prompt.confirm('Show the full masked report and the issue links? Nothing is sent anywhere by this command.');
             if (!confirmed)
                 return;
         }
         this.logger.log(masked);
+        const pending = gaps.filter((gap) => gap.url);
+        if (!pending.length)
+            return;
+        this.logger.info('Review each link in a browser, submit the form, then write the issue number in the entry as "Issue: #<number>".');
+        for (const gap of pending) {
+            this.logger.log(`\n${gap.title}`);
+            if (gap.missing.length)
+                this.logger.warning(`Complete before submitting: ${gap.missing.join(', ')}`);
+            this.logger.log(gap.url);
+        }
     }
 }
 __decorate([

package/build/commands/install.js

@@ -1,7 +1,9 @@
 import { BaseCommand } from '@adonisjs/core/ace';
 import { readFile, writeFile, access } from 'node:fs/promises';
 import { Settings } from '../src/services/settings.js';
+import { seedModules } from '../src/core/module_seed.js';
 import { syncAgentAssets } from '../src/commands/agent_assets.js';
+import { GAPS_TEMPLATE } from '../src/commands/gap_report.js';
 import { KIT_VERSION } from '../src/version.js';
 import { fileURLToPath } from 'node:url';
 export default class Install extends BaseCommand {
@@ -32,10 +34,12 @@ export default class Install extends BaseCommand {
             let role = await trx('roles').where('name', 'administrator').first();
             if (!role) {
                 const [created] = await trx('roles')
-                    .insert({ name: 'administrator', permission_level: 1 })
+                    .insert({ name: 'administrator', key: 'administrator', permission_level: 1 })
                     .returning('*');
                 role = created;
             }
+            else if (!role.key && !(await trx('roles').where('key', 'administrator').first()))
+                await trx('roles').where('id', role.id).update({ key: 'administrator' });
             // Repair a missing bootstrap grant even when the role already exists.
             // The transaction lock makes repeated/concurrent installation idempotent.
             if (!(await trx('role_rules')
@@ -55,12 +59,22 @@ export default class Install extends BaseCommand {
                 .ignore();
             await new Settings(trx).set('kit.version', KIT_VERSION);
         });
+        // Module lookups and default roles: added when missing, never overwritten.
+        let registry;
+        try {
+            ;
+            ({ registry } = await this.app.import('#start/modules'));
+        }
+        catch (error) {
+            this.logger.warning(`Module defaults skipped: ${error.message}`);
+        }
+        if (registry) {
+            const seeded = await seedModules(knex, registry, user.id);
+            this.logger.info(`Module defaults: ${seeded.lookups} lookup rows added; roles created: ${seeded.created.join(', ') || 'none'}; adopted by name: ${seeded.adopted.join(', ') || 'none'}`);
+        }
         for (const [name, content] of [
             ['CLAUDE.md', 'Read and follow AGENTS.md.\nThe project rules are maintained there.\n'],
-            [
-                'KIT_GAPS.md',
-                '# Kit gaps\n\nRecord Needed by, Tried, Blocked because, Proposed kit change, Workaround.\n',
-            ],
+            ['KIT_GAPS.md', GAPS_TEMPLATE],
         ]) {
             const path = this.app.makePath(name);
             try {

package/build/commands/main.d.ts

@@ -1,6 +1,8 @@
+import Resource from './resource.js';
 import Doctor from './doctor.js';
-import Capabilities from './capabilities.js';
+import ModuleAdd from './module_add.js';
+import Ui from './ui.js';
 export declare function getMetaData(): Promise<import("@adonisjs/core/types/ace").CommandMetaData[]>;
 export declare function getCommand(meta: {
     commandName: string;
-}): Promise<typeof Capabilities | typeof Doctor | null>;
+}): Promise<typeof Resource | typeof Doctor | typeof ModuleAdd | typeof Ui | null>;

package/build/commands/main.js

@@ -1,4 +1,5 @@
 import Resource from './resource.js';
+import ResourceSnapshot from './resource_snapshot.js';
 import Doctor from './doctor.js';
 import Install from './install.js';
 import Capabilities from './capabilities.js';
@@ -9,6 +10,7 @@ import StorageMigrate from './storage_migrate.js';
 import Gaps from './gaps.js';
 const commands = [
     Resource,
+    ResourceSnapshot,
     Doctor,
     Install,
     Capabilities,

package/build/commands/module_add.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { BaseCommand, args, flags } from '@adonisjs/core/ace';
 import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
 import { identifier } from '../src/resource/define_resource.js';
-import { appendMarkedItem } from '../src/commands/source_markers.js';
+import { appendMarkedItem, moduleSource } from '../src/commands/source_markers.js';
 export default class ModuleAdd extends BaseCommand {
     static commandName = 'adula:module:add';
     static description = 'Create and register an application-owned module';
@@ -44,7 +44,7 @@ export default class ModuleAdd extends BaseCommand {
             'tests',
         ])
             await mkdir(this.app.makePath('app/modules', this.name, directory), { recursive: true });
-        await writeFile(this.app.makePath('app/modules', this.name, 'module.ts'), `import type { Module } from '@adula/kit'\n// adula:imports\nexport default { name: '${this.name}', label: { ar: '${this.name}', en: '${this.name}' }, reference: ${Boolean(this.reference)}, dependsOn: [], resources: [/* adula:resources */] } satisfies Module\n`, { flag: 'wx' });
+        await writeFile(this.app.makePath('app/modules', this.name, 'module.ts'), moduleSource(this.name, { reference: Boolean(this.reference), typed: true }), { flag: 'wx' });
         await writeFile(indexPath, next);
         this.logger.success(`Created ${this.name}. Fill bilingual labels and declare dependencies before adding resources.`);
     }

package/build/commands/resource.js

@@ -18,7 +18,7 @@ export default class Resource extends BaseCommand {
         }
         const files = await generateResource(fileURLToPath(this.app.appRoot), this.name, this.module);
         files.forEach((file) => this.logger.success(file));
-        this.logger.info('Set bilingual labels, fill the resource definition, migrate, and run the generated security contract.');
+        this.logger.info('Set bilingual labels (label: the plural list heading; recordLabel: the singular record noun) and fill the resource definition. The generated migration embeds the definition as scaffolded: after filling the definition, run `node ace adula:resource:snapshot <name>` to refresh the pending migration, and update the model, factory and contract fixture, before migration:run. adula:doctor reports a pending migration that differs. Then run the generated security contract.');
     }
 }
 __decorate([

package/build/commands/resource_snapshot.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+/**
+ * Rewrites the definition embedded in a resource's generated create-migration from the
+ * current resource, while that migration has not run yet (#20). A migration that already
+ * ran is never edited: change the table with a new expand migration instead.
+ */
+export default class ResourceSnapshot extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    name: string;
+    run(): Promise<void>;
+}