sirius-framework-mcp 0.1.0

package/dist/prompts/workflows.js

@@ -0,0 +1,317 @@
+/**
+ * MCP prompt definitions for common Sirius development workflows.
+ *
+ * Each prompt generates an initial conversation that guides an AI assistant
+ * through a specific Sirius framework task.
+ */
+function userMessage(text) {
+    return { role: "user", content: { type: "text", text } };
+}
+function assistantMessage(text) {
+    return {
+        role: "assistant",
+        content: { type: "text", text },
+    };
+}
+// ---------------------------------------------------------------------------
+// 1. add-entity
+// ---------------------------------------------------------------------------
+export const addEntityPrompt = {
+    name: "add-entity",
+    description: "I want to add a new Sirius entity",
+    arguments: [
+        {
+            name: "name",
+            description: "The entity name (e.g. 'Product'). Used as the base for interface, SQL, and Mongo class names.",
+            required: true,
+        },
+        {
+            name: "package",
+            description: "The target Java package (e.g. 'sirius.biz.products'). If omitted, a sensible default under sirius.biz will be suggested.",
+            required: false,
+        },
+    ],
+    generateMessages(args) {
+        const name = args.name;
+        const pkg = args.package ?? `sirius.biz.${name.toLowerCase()}s`;
+        return [
+            userMessage(`I want to add a new Sirius entity called "${name}" in the package "${pkg}". ` +
+                `Please guide me through the full entity-triple pattern.`),
+            assistantMessage(`Great -- adding a new entity in Sirius follows the **entity-triple** pattern ` +
+                `(see resource \`sirius://biz/entity-triple\`). Here is the step-by-step plan:\n` +
+                `\n` +
+                `## 1. Database-independent interface\n` +
+                `Create \`${pkg}.${name}\` as an interface that extends \`Entity\` (and typically \`Traced\`, \`Journaled\`).\n` +
+                `Define a \`${name}Data\` composite if the entity carries reusable field groups.\n` +
+                `Use \`Mapping.named()\` constants for every persistent field.\n` +
+                `\n` +
+                `## 2. JDBC implementation\n` +
+                `Create \`${pkg}.jdbc.SQL${name}\` extending \`SQLTenantAware\` and implementing \`${name}\`.\n` +
+                `Add appropriate \`@Index\` annotations for unique constraints and lookup fields.\n` +
+                `Add \`@Framework("${pkg.replace(/^sirius\.biz\./, "biz.")}-jdbc")\` so the entity is only loaded when the flag is enabled.\n` +
+                `\n` +
+                `## 3. MongoDB implementation\n` +
+                `Create \`${pkg}.mongo.Mongo${name}\` extending \`MongoTenantAware\` and implementing \`${name}\`.\n` +
+                `Add \`@Framework("${pkg.replace(/^sirius\.biz\./, "biz.")}-mongo")\`.\n` +
+                `\n` +
+                `## 4. Framework flags\n` +
+                `Register framework flags in your \`.conf\` file:\n` +
+                `\`\`\`hocon\n` +
+                `sirius.frameworks {\n` +
+                `    "${pkg.replace(/^sirius\.biz\./, "biz.")}" = true\n` +
+                `    "${pkg.replace(/^sirius\.biz\./, "biz.")}-jdbc" = true\n` +
+                `    "${pkg.replace(/^sirius\.biz\./, "biz.")}-mongo" = false\n` +
+                `}\n` +
+                `\`\`\`\n` +
+                `\n` +
+                `## 5. Translation source\n` +
+                `Add \`@TranslationSource\` to provide i18n keys for the entity and its fields.\n` +
+                `Create corresponding \`.properties\` files under \`resources/\`.\n` +
+                `\n` +
+                `Shall I generate the skeleton code for each of these files?`),
+        ];
+    },
+};
+// ---------------------------------------------------------------------------
+// 2. add-job
+// ---------------------------------------------------------------------------
+export const addJobPrompt = {
+    name: "add-job",
+    description: "I want to add a new background job",
+    arguments: [
+        {
+            name: "name",
+            description: "The job name (e.g. 'ProductImportJob'). Used as the class name for the JobFactory implementation.",
+            required: true,
+        },
+        {
+            name: "type",
+            description: "The kind of job: 'batch' (long-running data processing), 'report' (generates output), or 'interactive' (user-triggered, short-lived). Determines the base class.",
+            required: false,
+        },
+    ],
+    generateMessages(args) {
+        const name = args.name;
+        const type = args.type ?? "batch";
+        const baseClassMap = {
+            batch: "BatchProcessJobFactory",
+            report: "ReportJobFactory",
+            interactive: "InteractiveJobFactory",
+        };
+        const baseClass = baseClassMap[type] ?? baseClassMap.batch;
+        return [
+            userMessage(`I want to add a new ${type} background job called "${name}". ` +
+                `Please guide me through the Sirius jobs framework.`),
+            assistantMessage(`The Sirius jobs framework (see resource \`sirius://biz/jobs\`) uses a ` +
+                `\`JobFactory\` hierarchy to define background jobs. For a **${type}** job, ` +
+                `the right base class is \`${baseClass}\`.\n` +
+                `\n` +
+                `## Step-by-step plan\n` +
+                `\n` +
+                `### 1. Choose and extend the base class\n` +
+                `Create \`${name}\` extending \`${baseClass}\`.\n` +
+                `Register it with \`@Register\` so the DI framework picks it up.\n` +
+                `\n` +
+                `### 2. Define parameters\n` +
+                `Override the \`collectParameters()\` method to declare job parameters.\n` +
+                `Use parameter types like \`StringParameter\`, \`BooleanParameter\`, \`EntityParameter\`, etc.\n` +
+                `Parameters appear in the job's UI form automatically.\n` +
+                `\n` +
+                `### 3. Implement execution logic\n` +
+                (type === "batch"
+                    ? `Override \`execute(ProcessContext process)\` to implement the batch processing logic.\n` +
+                        `Use \`process.log()\` for progress reporting and \`process.addTiming()\` for performance tracking.\n` +
+                        `Handle cancellation via \`process.isActive()\`.\n`
+                    : type === "report"
+                        ? `Override \`execute(ProcessContext process)\` and use the report output helpers.\n` +
+                            `The report framework handles file generation and storage automatically.\n`
+                        : `Override \`execute(ProcessContext process)\` for the interactive job logic.\n` +
+                            `Interactive jobs are typically short-lived and may provide immediate feedback.\n`) +
+                `\n` +
+                `### 4. Permissions and labels\n` +
+                `Override \`getRequiredPermission()\` to restrict who can run the job.\n` +
+                `Provide a label and description via NLS keys.\n` +
+                `\n` +
+                `### 5. Optional: scheduling\n` +
+                `If the job should run on a schedule, implement the \`ScheduledJobFactory\` interface ` +
+                `or configure it via the admin UI.\n` +
+                `\n` +
+                `Shall I generate the skeleton code for \`${name}\`?`),
+        ];
+    },
+};
+// ---------------------------------------------------------------------------
+// 3. add-feature
+// ---------------------------------------------------------------------------
+export const addFeaturePrompt = {
+    name: "add-feature",
+    description: "I want to add a complete feature module",
+    arguments: [
+        {
+            name: "name",
+            description: "The feature name (e.g. 'products'). This determines the package, entity names, controller, and templates.",
+            required: true,
+        },
+    ],
+    generateMessages(args) {
+        const name = args.name;
+        const singular = name.endsWith("s") && name.length > 1 ? name.slice(0, -1) : name;
+        const entityName = singular.charAt(0).toUpperCase() + singular.slice(1);
+        const pkg = `sirius.biz.${name.toLowerCase()}`;
+        return [
+            userMessage(`I want to add a complete feature module called "${name}" to a Sirius application. ` +
+                `This should be a full vertical slice: entity, controller, template, and test.`),
+            assistantMessage(`A full feature module in Sirius is a vertical slice that touches multiple layers. ` +
+                `Here is the plan for the "${name}" feature. Relevant resources:\n` +
+                `- \`sirius://biz/entity-triple\` (entity pattern)\n` +
+                `- \`sirius://biz/jobs\` (if the feature needs background processing)\n` +
+                `- \`sirius://biz/importer\` (if the feature needs data import)\n` +
+                `- \`sirius://kernel/di\` (dependency injection and registration)\n` +
+                `\n` +
+                `## 1. Entity layer\n` +
+                `Follow the entity-triple pattern to create:\n` +
+                `- \`${pkg}.${entityName}\` -- database-independent interface\n` +
+                `- \`${pkg}.jdbc.SQL${entityName}\` -- JDBC implementation (extends \`SQLTenantAware\`)\n` +
+                `- \`${pkg}.mongo.Mongo${entityName}\` -- MongoDB implementation (extends \`MongoTenantAware\`)\n` +
+                `- \`${pkg}.${entityName}Data\` -- composite for reusable field groups (if needed)\n` +
+                `\n` +
+                `## 2. Controller layer\n` +
+                `Create \`${pkg}.${entityName}Controller\` extending \`BizController\`:\n` +
+                `- Use \`@Routed\` annotations for URL mappings (e.g. \`/${name}\`, \`/${singular}/{id}\`)\n` +
+                `- Add \`@LoginRequired\` and \`@Permission\` for access control\n` +
+                `- Implement list, detail/edit, and delete endpoints\n` +
+                `- Make the controller generic over the entity interface so it works with both SQL and Mongo\n` +
+                `\n` +
+                `## 3. Template layer\n` +
+                `Create Pasta/Tagliatelle templates under \`resources/default/templates/biz/${name}/\`:\n` +
+                `- \`${singular}.html.pasta\` -- detail/edit view\n` +
+                `- \`${name}.html.pasta\` -- list view\n` +
+                `Use the Tycho UI component library (\`<t:...>\` tags) for consistent look-and-feel.\n` +
+                `\n` +
+                `## 4. Framework flags\n` +
+                `Register in your \`.conf\`:\n` +
+                `\`\`\`hocon\n` +
+                `sirius.frameworks {\n` +
+                `    "biz.${name}" = true\n` +
+                `    "biz.${name}-jdbc" = true\n` +
+                `    "biz.${name}-mongo" = false\n` +
+                `}\n` +
+                `\`\`\`\n` +
+                `\n` +
+                `## 5. Test\n` +
+                `Create \`${entityName}Test.kt\` in \`src/test/kotlin/${pkg.replace(/\./g, "/")}/\`:\n` +
+                `- Use \`@ExtendWith(SiriusExtension::class)\`\n` +
+                `- Wait for database readiness in \`@BeforeAll\`\n` +
+                `- Test CRUD operations and any business logic\n` +
+                `\n` +
+                `## 6. i18n\n` +
+                `Add \`@TranslationSource\` to the entity and create \`.properties\` files ` +
+                `for labels and validation messages.\n` +
+                `\n` +
+                `Shall I start generating the code for each layer?`),
+        ];
+    },
+};
+// ---------------------------------------------------------------------------
+// 4. add-import-handler
+// ---------------------------------------------------------------------------
+export const addImportHandlerPrompt = {
+    name: "add-import-handler",
+    description: "I want to add a data import handler",
+    arguments: [
+        {
+            name: "entity",
+            description: "The entity name this import handler targets (e.g. 'Product'). Must correspond to an existing Sirius entity.",
+            required: true,
+        },
+    ],
+    generateMessages(args) {
+        const entity = args.entity;
+        return [
+            userMessage(`I want to add a data import handler for the "${entity}" entity. ` +
+                `Please guide me through the Sirius importer framework.`),
+            assistantMessage(`The Sirius importer framework (see resource \`sirius://biz/importer\`) provides ` +
+                `\`EntityImportHandler\` classes that define how external data maps to entities. ` +
+                `Here is the plan:\n` +
+                `\n` +
+                `## 1. Choose the base class\n` +
+                `- For JDBC entities: extend \`SQLEntityImportHandler<SQL${entity}>\`\n` +
+                `- For MongoDB entities: extend \`MongoEntityImportHandler<Mongo${entity}>\`\n` +
+                `Register with \`@Register\` and annotate with the appropriate \`@Framework\`.\n` +
+                `\n` +
+                `## 2. Define find queries\n` +
+                `Override \`determineFindQuery()\` to specify how existing records are located ` +
+                `during import (usually by a unique business key like an external ID or code).\n` +
+                `This is critical for upsert behavior -- without it, imports always create new records.\n` +
+                `\n` +
+                `## 3. Map fields\n` +
+                `Override \`collectFieldMappings()\` or use the auto-mapping from \`@AutoImport\` annotations.\n` +
+                `Fields annotated with \`@AutoImport\` on the entity are automatically mapped.\n` +
+                `For custom/computed fields, add explicit mappings in the handler.\n` +
+                `\n` +
+                `## 4. Handle events\n` +
+                `Override lifecycle callbacks to add custom logic:\n` +
+                `- \`beforeImport()\` -- validate or transform data before persisting\n` +
+                `- \`afterImport()\` -- trigger side effects after a record is imported\n` +
+                `- \`collectDefaultExportableMappings()\` -- define which fields appear in exports\n` +
+                `\n` +
+                `## 5. Register and test\n` +
+                `The handler is automatically discovered by the import framework via DI.\n` +
+                `Test by creating a small CSV or XML import and running it through the import UI or jobs.\n` +
+                `\n` +
+                `Shall I generate the handler skeleton for \`${entity}\`?`),
+        ];
+    },
+};
+// ---------------------------------------------------------------------------
+// 5. debug-framework-flags
+// ---------------------------------------------------------------------------
+export const debugFrameworkFlagsPrompt = {
+    name: "debug-framework-flags",
+    description: "My entity/service isn't being picked up",
+    arguments: [],
+    generateMessages() {
+        return [
+            userMessage(`My entity or service is not being picked up by the Sirius framework. ` +
+                `I have the class annotated with @Register but it does not seem to be active. ` +
+                `Help me debug this.`),
+            assistantMessage(`This is a common issue and almost always comes down to **framework flags**. ` +
+                `Let me walk you through the diagnostic steps (see resource \`sirius://kernel/di\`).\n` +
+                `\n` +
+                `## Step 1: Check the framework flag on your class\n` +
+                `Look at the \`@Register\` annotation on your class. If it specifies a \`framework\` attribute:\n` +
+                `\`\`\`java\n` +
+                `@Register(framework = "biz.myfeature")\n` +
+                `\`\`\`\n` +
+                `...then the flag \`biz.myfeature\` must be **enabled** in the config.\n` +
+                `\n` +
+                `Also check for a \`@Framework\` annotation on the class, which serves the same purpose.\n` +
+                `\n` +
+                `## Step 2: Verify the flag is enabled in config\n` +
+                `Check your \`develop.conf\` (or \`instance.conf\`) and the component config files:\n` +
+                `\`\`\`hocon\n` +
+                `sirius.frameworks {\n` +
+                `    "biz.myfeature" = true      # Must be true!\n` +
+                `    "biz.myfeature-jdbc" = true  # If using JDBC entities\n` +
+                `}\n` +
+                `\`\`\`\n` +
+                `A missing or \`false\` flag means the class is **completely invisible** to the DI system.\n` +
+                `\n` +
+                `## Step 3: Check for typos in framework names\n` +
+                `The framework name in \`@Register(framework = "...")\` must **exactly match** ` +
+                `the key in \`sirius.frameworks\`. A typo in either place silently disables the class.\n` +
+                `\n` +
+                `## Step 4: Check the class hierarchy\n` +
+                `- Entities must extend the correct base class (\`SQLTenantAware\`, \`MongoTenantAware\`, etc.)\n` +
+                `- Services must implement an interface or extend a known base class\n` +
+                `- The class must be in a package that is scanned (under the configured base packages)\n` +
+                `\n` +
+                `## Step 5: Use the system console\n` +
+                `In dev mode, go to \`/system/console\` and use the \`frameworks\` command to see ` +
+                `which flags are active. You can also check \`/system/cluster\` for registered components.\n` +
+                `\n` +
+                `What is the exact class and its annotations? I can help pinpoint the issue.`),
+        ];
+    },
+};
+//# sourceMappingURL=workflows.js.map

package/dist/prompts/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../src/prompts/workflows.ts"],"names":[],"mappings":"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"}

package/dist/resources/biz/analytics.md

@@ -0,0 +1,157 @@
+# Analytics
+
+The analytics module provides scheduled metric computation, performance flags,
+event recording, and chart visualization. Metrics are computed per entity on
+daily or monthly schedules.
+
+## Metric Computers
+
+### DailyMetricComputer
+
+Computes a metric for each entity on a daily basis. Annotated with `@AutoRegister`
+for automatic discovery:
+
+```java
+@AutoRegister
+public abstract class DailyMetricComputer<E extends BaseEntity<?>>
+        implements AnalyticalTask<E> {
+
+    @Part @Nullable
+    protected Metrics metrics;
+
+    public abstract void compute(MetricComputerContext context, E entity) throws Exception;
+}
+```
+
+Implementation example:
+
+```java
+public class OrderCountComputer extends DailyMetricComputer<SQLTenant> {
+
+    @Override
+    public Class<SQLTenant> getType() {
+        return SQLTenant.class;
+    }
+
+    @Override
+    public void compute(MetricComputerContext context, SQLTenant tenant) throws Exception {
+        int count = oma.select(SQLOrder.class)
+                       .eq(SQLOrder.TENANT, tenant)
+                       .where(OMA.FILTERS.gte(SQLOrder.CREATED_AT, context.periodStart()))
+                       .where(OMA.FILTERS.lte(SQLOrder.CREATED_AT, context.periodEnd()))
+                       .count();
+        metrics.updateDailyMetric("orders", tenant, context.date(), count);
+    }
+}
+```
+
+### MonthlyMetricComputer
+
+Same pattern, but invoked monthly. Also runs daily for the current month via
+best-effort scheduling to keep preliminary values up to date:
+
+```java
+public class MonthlyRevenueComputer extends MonthlyMetricComputer<SQLTenant> {
+
+    @Override
+    public void compute(MetricComputerContext context, SQLTenant tenant) throws Exception {
+        // context.periodStart() and context.periodEnd() span the full month
+        Amount revenue = computeRevenue(tenant, context.periodStart(), context.periodEnd());
+        metrics.updateMonthlyMetric("revenue", tenant, context.date(), revenue.getAmount());
+    }
+
+    @Override
+    public boolean suppressBestEffortScheduling() {
+        return false;  // default: allow daily re-computation of current month
+    }
+}
+```
+
+### MonthlyLargeMetricComputer
+
+For expensive computations that should only run once per month (not re-computed
+daily via best effort).
+
+## MetricComputerContext
+
+Passed to every `compute()` call with pre-calculated time boundaries:
+
+| Method                          | Description                                  |
+|---------------------------------|----------------------------------------------|
+| `date()`                        | The reference date for the metric            |
+| `periodStart()`                 | Start of the period (LocalDateTime)          |
+| `periodEnd()`                   | End of the period (LocalDateTime)            |
+| `periodOutsideOfCurrentInterest()` | True if computing a historical period     |
+| `bestEffort()`                  | True if this is a best-effort re-computation |
+
+## Scheduling
+
+The analytics scheduler iterates over entities and invokes registered computers.
+There are separate schedulers for JDBC and MongoDB entities:
+
+- `SQLAnalyticalTaskScheduler` — schedules tasks for `SQLEntity` types
+- `MongoAnalyticalTaskScheduler` — schedules tasks for `MongoEntity` types
+
+Enable the appropriate framework flags:
+
+```hocon
+sirius.frameworks {
+    biz.analytics-metrics-jdbc = true    # Enable JDBC metric computation
+    biz.analytics-metrics-mongo = false  # Enable MongoDB metric computation
+    biz.scheduler-jdbc = true            # Enable JDBC scheduler
+    biz.scheduler-mongo = false          # Enable MongoDB scheduler
+}
+```
+
+Schedulers use batch emitters (`SQLEntityBatchEmitter`, `MongoEntityBatchEmitter`)
+to process entities in configurable batch sizes via `DistributedTasks`.
+
+## Execution Flags (Performance Flags)
+
+Performance flags track boolean states per entity (e.g., "has overdue invoices",
+"needs review"). They are stored as composites on entities:
+
+- **`SQLPerformanceData`** — for JDBC entities
+- **`MongoPerformanceData`** — for MongoDB entities
+
+```java
+@Framework("biz.tenants-jdbc")
+public class SQLTenant extends BizEntity implements Tenant<Long>, PerformanceFlagged {
+    private final SQLPerformanceData performanceData = new SQLPerformanceData(this);
+
+    @Override
+    public SQLPerformanceData getPerformanceData() {
+        return performanceData;
+    }
+}
+```
+
+Enable with:
+
+```hocon
+sirius.frameworks {
+    biz.analytics-execution-flags-jdbc = true
+    biz.analytics-execution-flags-mongo = false
+}
+```
+
+## AnalyticalTask Interface
+
+Both `DailyMetricComputer` and `MonthlyMetricComputer` implement `AnalyticalTask<E>`.
+Override `getLevel()` to control execution order (lower = earlier) when one computer
+depends on another's results. Override `isEnabled()` to conditionally disable.
+
+## Common Mistakes
+
+1. **Missing scheduler framework flag** — Registering metric computers without
+   enabling `biz.scheduler-jdbc` or `biz.scheduler-mongo` means they never execute.
+
+2. **Wrong entity type** — A `DailyMetricComputer<SQLTenant>` only runs for
+   `SQLTenant` entities. If your app uses MongoDB, you need a Mongo variant.
+
+3. **Ignoring `periodOutsideOfCurrentInterest()`** — Use this flag to skip
+   expensive external API calls when backfilling historical data.
+
+4. **Not using `bestEffort()` correctly** — Best-effort runs provide preliminary
+   values for the current period. Do not perform destructive operations during
+   best-effort runs.

package/dist/resources/biz/biz-controller.md

@@ -0,0 +1,151 @@
+# BizController
+
+`BizController` extends `BasicController` from sirius-web and serves as the base
+class for all controllers that operate on entities in the biz layer. It provides
+tenant-aware helpers, entity loading from web requests, and pre-injected database
+access parts.
+
+## Injected Parts
+
+`BizController` comes with these fields already injected:
+
+```java
+@Part protected Mixing mixing;       // Schema/descriptor access
+@Part protected OMA oma;             // JDBC entity operations
+@Part protected Mango mango;         // MongoDB entity operations
+@Part protected Elastic elastic;     // Elasticsearch operations
+@Part @Nullable protected Tenants<?, ?, ?> tenants;  // Tenant management
+```
+
+You can use `oma`, `mango`, and `elastic` directly in subclasses without declaring
+your own `@Part` fields.
+
+## Loading Entities from Requests — load()
+
+The `load()` method reads HTTP parameters into an entity, populating all fields
+marked with `@Autoloaded`:
+
+```java
+@Routed(value = "/product/:1/save", methods = HttpMethod.POST)
+@LoginRequired
+public void saveProduct(WebContext webContext, String productId) {
+    Product product = find(Product.class, productId);
+
+    load(webContext, product);  // fills all @Autoloaded fields from the request
+    oma.update(product);
+    showSavedMessage();
+    webContext.respondWith().redirectToGet("/products");
+}
+```
+
+Overloads:
+- `load(webContext, entity)` — loads all `@Autoloaded` properties.
+- `load(webContext, entity, Mapping... properties)` — loads only the listed properties.
+- `load(webContext, entity, List<Mapping> properties)` — same, with a list.
+
+## Resolving Entities — find()
+
+The `find()` method resolves an entity by its ID string. It also handles the special
+value `"new"`, which creates a fresh instance instead of querying the database:
+
+```java
+Product product = find(Product.class, productId);
+// If productId is "new", returns a new Product()
+// Otherwise, looks up the entity — throws 404 if not found
+```
+
+For tenant-scoped entities, use `findForTenant()` which additionally verifies that
+the entity belongs to the current user's tenant.
+
+## CRUD Flow Pattern
+
+The standard pattern for list/edit/delete:
+
+```java
+@Register
+public class ProductController extends BizController {
+
+    @Routed("/products")
+    @DefaultRoute
+    @LoginRequired
+    @Permission("permission-manage-products")
+    public void products(WebContext webContext) {
+        SQLPageHelper<Product> pageHelper =
+                SQLPageHelper.withQuery(tenants.forCurrentTenant(oma.select(Product.class)));
+        pageHelper.withBasePath("/products");
+        pageHelper.withSearchFields(QueryField.contains(Product.NAME));
+        webContext.respondWith()
+                  .template("/templates/products/list.html.pasta", pageHelper.asPage());
+    }
+
+    @Routed("/product/:1")
+    @LoginRequired
+    @Permission("permission-manage-products")
+    public void editProduct(WebContext webContext, String productId) {
+        Product product = findForTenant(Product.class, productId);
+
+        if (webContext.ensureSafePOST()) {
+            load(webContext, product);
+            oma.update(product);
+            showSavedMessage();
+            webContext.respondWith().redirectToGet("/products");
+            return;
+        }
+
+        webContext.respondWith()
+                  .template("/templates/products/edit.html.pasta", product);
+    }
+
+    @Routed("/product/:1/delete")
+    @LoginRequired
+    @Permission("permission-manage-products")
+    public void deleteProduct(WebContext webContext, String productId) {
+        Product product = findForTenant(Product.class, productId);
+        oma.delete(product);
+        showDeletedMessage();
+        webContext.respondWith().redirectToGet("/products");
+    }
+}
+```
+
+## Page Helpers
+
+For list views with pagination, search, and filtering:
+
+- **`SQLPageHelper`** — wraps a `SmartQuery<SQLEntity>` for JDBC entities.
+- **`MongoPageHelper`** — wraps a `MongoQuery<MongoEntity>` for MongoDB entities.
+- **`ElasticPageHelper`** — wraps an `ElasticQuery<ElasticEntity>` for Elasticsearch.
+
+```java
+SQLPageHelper<Product> pageHelper =
+        SQLPageHelper.withQuery(oma.select(Product.class).orderAsc(Product.NAME));
+pageHelper.withBasePath("/products");
+pageHelper.withSearchFields(QueryField.contains(Product.NAME));
+pageHelper.addBooleanFacet(Product.ACTIVE, NLS.get("Product.active"));
+```
+
+## @Autoloaded
+
+Mark entity properties with `@Autoloaded` to have `load()` pick them up automatically
+from HTTP request parameters. The parameter name matches the property name:
+
+```java
+@Autoloaded
+@Length(150)
+@Trim
+private String name;  // loaded from request param "name"
+```
+
+## Common Mistakes
+
+1. **Forgetting `ensureSafePOST()`** — Always check for safe POST before mutating
+   data. Without this, you are vulnerable to CSRF attacks.
+
+2. **Not returning after redirect** — After `redirectToGet()`, always `return`.
+   Otherwise the method continues and may try to render a template too.
+
+3. **Using `find()` for tenant-scoped entities** — Use `findForTenant()` instead.
+   Plain `find()` does not verify the tenant, which allows cross-tenant data access.
+
+4. **Forgetting `@DefaultRoute`** — Without a default route, exceptions in other
+   routes render a generic error page instead of staying in context.