spiderly 19.8.4 → 19.8.5

package/agent/docs/backend-localization/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: backend-localization
+description: How Spiderly localizes backend (.NET) strings — error messages, Excel export names, any server-side text. Spiderly uses a JSON file localizer (flat {culture}.json files), NOT .resx. Use whenever you add or translate a backend string, hit a raw translation key leaking to the user, wonder where backend translations live or why there are no .resx files, localize a BusinessException message, register a custom (e.g. DB-backed) IStringLocalizer, or set up UseTranslations / UseCulture. For Angular admin UI strings (Transloco, assets/i18n/*.json), use the frontend-localization skill instead.
+---
+
+# Backend Localization
+
+Spiderly localizes server-side strings through the standard .NET `IStringLocalizer` abstraction, but the **implementation is JSON-file based — there is no `.resx` anywhere in the framework**. Do not create `.resx`/`.resources` files or a `ResourceManager`; they will not be read. The choice is deliberate: flat JSON files are diff-friendly, trivial to edit by hand or by an agent, and need no designer/codegen step.
+
+Because everything goes through `IStringLocalizer`, call sites look identical to a resx-backed app — the JSON nature only matters when you *define* or *find* a translation.
+
+## The three localizer modes
+
+`IStringLocalizer` is registered as a **singleton** in `AddSpiderly` based on the builder config (`StartupExtensions.cs`):
+
+| Builder call | Registered implementation | Behavior |
+|---|---|---|
+| `spiderly.UseTranslations()` | `JsonStringLocalizer` | Loads every `Translations/{culture}.json` file. |
+| `spiderly.UseTranslations<TLocalizer>()` | your `TLocalizer` | Custom source (e.g. database-backed). DI resolves its constructor. |
+| *(neither called)* | `PassthroughStringLocalizer` | No-op: returns the key as its own value, so the app runs untranslated. |
+
+`PassthroughStringLocalizer` being the default is why a brand-new app shows raw keys until you opt in with `UseTranslations()`.
+
+## Enabling JSON translations
+
+```csharp
+// Startup.cs — inside AddSpiderly(spiderly => { ... })
+spiderly.UsePostgreSQL();
+spiderly.UseCulture("sr-Latn-RS");   // default + supported cultures
+spiderly.UseTranslations();          // register the JSON localizer
+```
+
+Translation files live in a `Translations/` directory and **must be copied to the build output** — `JsonStringLocalizer` reads from `AppContext.BaseDirectory/Translations`, not the source tree. Add this to the `.csproj` that holds them:
+
+```xml
+<ItemGroup>
+  <None Update="Translations\*.json" CopyToOutputDirectory="PreserveNewest" />
+</ItemGroup>
+```
+
+## File format and naming
+
+Each file is a **flat** key→value JSON object (no nesting) named exactly after the culture:
+
+```jsonc
+// Translations/sr-Latn-RS.json
+{
+  "ConcurrencyException": "Podaci su u međuvremenu izmenjeni. Osvežite stranicu.",
+  "EntityDoesNotExistInDatabase": "Traženi podatak ne postoji.",
+  "WelcomeUser": "Dobrodošli, {0}!"
+}
+```
+
+Two hard naming rules — both fail silently if broken:
+
+1. **The filename must equal `CultureInfo.CurrentCulture.Name`** that the request runs under (e.g. `sr-Latn-RS.json`, `en.json`, `bs-Latn-BA.json`). The localizer keys off the running culture's exact name; a mismatch (`sr.json` when requests run as `sr-Latn-RS`) means *no file matches* and every key falls through to its raw self.
+2. **The culture must be registered via `UseCulture(default, ...additional)`.** `RequestLocalization` only switches `CurrentCulture` to cultures in that supported list; anything else falls back to the default culture, so its JSON file is never consulted.
+
+Format placeholders use `string.Format`: `_localizer["WelcomeUser", user.Name]` → `"Dobrodošli, Filip!"`.
+
+## Using the localizer in code
+
+### Inside an entity service (`{Entity}Service : {Entity}ServiceGenerated`)
+
+The base `ServiceBase` exposes a `protected readonly IStringLocalizer _localizer`, so use it directly. This is the canonical way to produce a **localized error message**:
+
+```csharp
+public class ProductService : ProductServiceGenerated
+{
+    public ProductService(EntityServiceDependencies deps) : base(deps) { }
+
+    protected override async Task OnBeforeSaveProductAndReturnSaveBodyDTO(ProductSaveBodyDTO dto)
+    {
+        if (dto.Price < 0)
+            throw new BusinessException(_localizer["PriceCannotBeNegative"]);
+    }
+}
+```
+
+`_deps.Localizer` is the same instance (the dependency bundle) — prefer `_localizer` for brevity inside a service; pass `_deps.Localizer` when a helper needs it (e.g. `Helper.ValidateFileSize(file.Length, max, _deps.Localizer)`).
+
+### Inside a custom (non-entity) service or controller
+
+Inject `IStringLocalizer` through the constructor like any other dependency:
+
+```csharp
+public class WarrantyRegistrationService
+{
+    private readonly IStringLocalizer _localizer;
+
+    public WarrantyRegistrationService(IStringLocalizer localizer)
+    {
+        _localizer = localizer;
+    }
+
+    public void Validate(IFormFile file)
+    {
+        Helper.ValidateFileSize(file.Length, MaxReceiptFileSize, _localizer);
+    }
+}
+```
+
+Custom controllers that extend a generated base already receive `IStringLocalizer localizer` and pass it to `base(...)` — see the custom-endpoints skill.
+
+### Indexer vs. the `Translate` extension
+
+```csharp
+_localizer["Key"]                  // LocalizedString; implicitly converts to string. Renders "Key" if missing.
+_localizer["Key", arg0, arg1]      // string.Format with the translation value as the format string.
+_localizer.Translate("Key")        // plain string, explicitly returns the key itself on a miss.
+_localizer.GetExcelTranslation("ProductExcelExportName", "ProductList")
+                                   // Excel-specific key first, then the plural/list key, then the raw key.
+```
+
+`Translate` and `GetExcelTranslation` are in `Spiderly.Shared.Localization.StringLocalizerExtensions` (`using Spiderly.Shared.Localization;`).
+
+## Gotchas
+
+- **Translations are loaded once, at app start.** The JSON localizer is a singleton that reads all files in its constructor. **Editing a `*.json` file has no effect until you restart the backend** — there is no file watcher. (A custom `UseTranslations<T>()` localizer can reload per request if you build it that way.)
+- **A missing key fails open, not loud.** Both the JSON localizer (unknown key) and the passthrough default return the *key string itself* with `ResourceNotFound = true`. So a typo'd or untranslated key silently leaks the raw identifier (e.g. `PriceCannotBeNegative`) to the end user instead of throwing. Keep keys in sync across every `{culture}.json`, and treat a raw-key-in-the-UI sighting as a missing-translation bug, not a code bug.
+- **Don't reach for `.resx`.** Adding a resource file or `ResourceManager` won't integrate — the abstraction only resolves through the registered `IStringLocalizer`.
+
+## Custom localizer (e.g. database-backed)
+
+When translations must be editable at runtime (admin-managed) rather than shipped as files, implement `IStringLocalizer` and register it. DI resolves its constructor, so it can depend on your `DbContext` or a cache:
+
+```csharp
+public class DbStringLocalizer : IStringLocalizer
+{
+    private readonly IApplicationDbContext _context;
+    public DbStringLocalizer(IApplicationDbContext context) => _context = context;
+
+    public LocalizedString this[string name]
+    {
+        get
+        {
+            string culture = CultureInfo.CurrentCulture.Name;
+            string value = _context.DbSet<Translation>()
+                .Where(t => t.Culture == culture && t.Key == name)
+                .Select(t => t.Value)
+                .FirstOrDefault();
+            return value != null
+                ? new LocalizedString(name, value)
+                : new LocalizedString(name, name, resourceNotFound: true);
+        }
+    }
+
+    public LocalizedString this[string name, params object[] arguments]
+    {
+        get
+        {
+            LocalizedString s = this[name];
+            return new LocalizedString(name, string.Format(s.Value, arguments), s.ResourceNotFound);
+        }
+    }
+
+    public IEnumerable<LocalizedString> GetAllStrings(bool includeParentCultures) =>
+        Enumerable.Empty<LocalizedString>();
+}
+```
+
+```csharp
+spiderly.UseTranslations<DbStringLocalizer>();   // takes precedence over the built-in JSON localizer
+```
+
+Mirror the built-in's key-on-miss contract (`resourceNotFound: true`, return the key) so callers behave consistently.
+
+## Frontend strings are a separate system
+
+This skill is backend only. The Angular admin panel localizes through **Transloco** (`src/assets/i18n/{lang}.json` + `translocoService.translate(...)`), which is unrelated to the .NET `IStringLocalizer` here. For UI labels, menu items, validation messages, and auto-translated form labels, use the **frontend-localization** skill.

package/agent/docs/backend-testing/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: backend-testing
+description: Unit-test a Spiderly backend service against an EF Core InMemory database — covers the two InMemory pitfalls that silently corrupt assertions (the change tracker masking a missing SaveChanges, and WithTransactionAsync throwing TransactionIgnoredWarning). Use when writing xUnit/NUnit tests for entity services, business logic, or save/delete hooks against an InMemory DbContext, or when an InMemory-backed test passes/throws for reasons that don't match production.
+---
+
+# Backend Testing (EF Core InMemory)
+
+Spiderly entity services run against a relational DbContext in production but are usually unit-tested against `Microsoft.EntityFrameworkCore.InMemory`. InMemory is *not* a relational database — two of its behavioral gaps will silently make a test lie unless you guard against them.
+
+## Pitfall 1: the change tracker masks a missing `SaveChanges`
+
+EF's change tracker serves **tracked-but-unsaved** entities back through later LINQ queries on the same context. So a method that adds/mutates an entity but forgets to call `SaveChangesAsync()` still appears to work — a follow-up `await _context.Set<T>().FirstOrDefaultAsync(...)` in the test returns the in-memory tracked instance, and the assertion passes. In production (separate request/context) the row was never persisted.
+
+**If the method's contract is "I persist before returning," assert the flush happened — not just that the value is readable:**
+
+```csharp
+[Fact]
+public async Task Activate_PersistsTheChange()
+{
+    using var context = NewContext();
+    context.Product.Add(new Product { Id = 1, IsActive = false });
+    await context.SaveChangesAsync();
+
+    var service = new ProductService(context);
+    await service.ActivateAsync(productId: 1);
+
+    // ❌ This passes even if ActivateAsync never called SaveChangesAsync —
+    //    the tracker hands back the mutated, unsaved instance.
+    // var p = await context.Product.FirstAsync(x => x.Id == 1);
+    // Assert.True(p.IsActive);
+
+    // ✅ Assert the unit of work actually flushed.
+    Assert.False(context.ChangeTracker.HasChanges());
+
+    // For extra confidence, read through a FRESH context so nothing is served
+    // from the tracker — this is the closest InMemory gets to a real round-trip:
+    using var verify = NewContext();
+    Assert.True((await verify.Product.FirstAsync(x => x.Id == 1)).IsActive);
+}
+```
+
+`NewContext()` must reuse the **same** InMemory database name across both instances so the second context sees the first's saved data (see the shared options helper below).
+
+## Pitfall 2: `WithTransactionAsync` throws `TransactionIgnoredWarning`
+
+Spiderly service methods wrap their unit of work in `_context.WithTransactionAsync(...)`. The InMemory provider has no transaction support, so EF raises `InMemoryEventId.TransactionIgnoredWarning` — and by default warnings of this severity are promoted to **exceptions**, so the test throws before it reaches any assertion. Suppress that one warning when building the options:
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Diagnostics;
+
+private static MyAppDbContext NewContext(string dbName) =>
+    new(new DbContextOptionsBuilder<MyAppDbContext>()
+        .UseInMemoryDatabase(dbName)
+        // Without this, any code path that calls WithTransactionAsync throws:
+        //   "An 'IServiceProvider' ... transaction ... was ignored ..."
+        .ConfigureWarnings(w => w.Ignore(InMemoryEventId.TransactionIgnoredWarning))
+        .Options);
+```
+
+Pass a stable `dbName` (e.g. one per test, `Guid.NewGuid().ToString()`) so each test is isolated but a test's own multiple contexts share state.
+
+## When InMemory isn't enough
+
+InMemory ignores relational constraints (unique indexes, FK cascade, check constraints, `[Required]` at the DB level), provider-specific SQL, and real transaction semantics. If the behavior under test depends on any of those, prefer the **SQLite in-memory** provider (`UseSqlite("DataSource=:memory:")`, keep the connection open) or a disposable real database — don't assert relational guarantees against `UseInMemoryDatabase`.

package/agent/docs/custom-endpoints/SKILL.md

@@ -0,0 +1,409 @@
+---
+name: custom-endpoints
+description: Add custom (non-CRUD) API endpoints to a Spiderly project. Use when creating custom controllers, adding new service methods beyond generated CRUD, building storefront or webhook endpoints, calling generated services from custom code, or choosing between return types.
+---
+
+# Custom Endpoints
+
+## Controller Patterns
+
+### Pattern 1: Extend Generated Base Controller
+
+Add custom methods alongside generated CRUD endpoints:
+
+```csharp
+[ApiController]
+[Route("/api/[controller]/[action]")]
+public class OrderController : OrderBaseController
+{
+    private readonly IServiceProvider _serviceProvider;
+
+    public OrderController(
+        IApplicationDbContext context,
+        IServiceProvider serviceProvider,
+        IStringLocalizer localizer
+    )
+        : base(context, serviceProvider, localizer)
+    {
+        _serviceProvider = serviceProvider;
+    }
+
+    [HttpGet]
+    [AuthGuard]
+    public async Task UpdateOrderStatus(long orderId, byte newStatusId)
+    {
+        OrderServiceGenerated orderService =
+            _serviceProvider.GetRequiredService<OrderServiceGenerated>();
+        await orderService.UpdateOrderStatus(orderId, newStatusId);
+    }
+}
+```
+
+The generated `OrderBaseController` already provides `GetPaginatedOrderList`, `SaveOrder`, `DeleteOrder`, etc. Your custom methods are added alongside them.
+
+### Pattern 2: Fully Custom Controller
+
+For endpoints with no generated entity CRUD (storefronts, webhooks), inject domain services directly:
+
+```csharp
+[ApiController]
+[Route("/api/[controller]/[action]")]
+public class StorefrontController : ControllerBase
+{
+    private readonly StorefrontCatalogService _catalogService;
+
+    public StorefrontController(
+        StorefrontCatalogService catalogService
+    )
+    {
+        _catalogService = catalogService;
+    }
+
+    [HttpGet]
+    public async Task<List<StorefrontCategoryDTO>> Categories()
+    {
+        return await _catalogService.GetCategoriesForDisplay();
+    }
+
+    [HttpGet]
+    public async Task<ActionResult<StorefrontBrandDTO>> BrandBySlug(string slug)
+    {
+        StorefrontBrandDTO result = await _catalogService.GetBrandBySlug(slug);
+        if (result == null) return NotFound();
+        return result;
+    }
+}
+```
+
+### Decide spinner behavior for every new endpoint
+
+The global blocking spinner is inferred automatically — POSTs and full-DTO GETs keep it; read-shaped returns (`Namebook`/`Codebook`/`PaginatedResult`) and bare-scalar GETs skip it. When adding an endpoint, ask whether the inference matches the UX: a full-DTO GET that is polled on a timer, runs in the background, or feeds a lightweight popover/inline panel (e.g. a row-level "show order items" popover on a list page) should be marked `[SkipSpinner]` — blacking out the whole screen there is disproportionate. See [Key Attributes](#key-attributes) for `[SkipSpinner]`/`[ShowSpinner]` details.
+
+### `[Controller("Name")]` — Grouping Entities
+
+Multiple entities under one controller:
+
+```csharp
+[Controller("SecurityController")]
+public class User : BusinessObject<long> { ... }
+
+[Controller("SecurityController")]
+public class Role : BusinessObject<int> { ... }
+```
+
+Generates a single `SecurityBaseController` with CRUD for both entities.
+
+## Custom Service Methods
+
+Create standalone service classes for custom logic. Inject `IApplicationDbContext` or `EntityServiceDependencies` as needed:
+
+```csharp
+public class StorefrontCatalogService
+{
+    private readonly IApplicationDbContext _context;
+
+    public StorefrontCatalogService(IApplicationDbContext context)
+    {
+        _context = context;
+    }
+
+    public async Task<List<StorefrontCategoryDTO>> GetCategoriesForDisplay()
+    {
+        return await _context.DbSet<Category>()
+            .AsNoTracking()
+            .Select(x => new StorefrontCategoryDTO
+            {
+                Id = x.Id,
+                Name = x.Name,
+                Slug = x.Slug,
+            })
+            .ToListAsync();
+    }
+}
+```
+
+To add custom methods to a generated entity service, create an `{Entity}Service` class:
+
+```csharp
+public class OrderService : OrderServiceGenerated
+{
+    public OrderService(EntityServiceDependencies deps) : base(deps) { }
+
+    public async Task UpdateOrderStatus(long orderId, byte newStatusId)
+    {
+        await _deps.Context.DbSet<Order>()
+            .Where(x => x.Id == orderId)
+            .ExecuteUpdateAsync(x => x.SetProperty(o => o.OrderStatusId, newStatusId));
+    }
+}
+```
+
+### Database Access Patterns
+
+```csharp
+// Simple query
+List<Product> products = await _context.DbSet<Product>()
+    .Where(x => x.IsActive)
+    .ToListAsync();
+
+// Eager load navigations
+List<ProductVariant> variants = await _context.DbSet<ProductVariant>()
+    .Include(x => x.Product)
+    .Where(x => ids.Contains(x.Id))
+    .ToListAsync();
+
+// Fetch with version check (optimistic concurrency)
+Notification notification = await GetInstanceAsync<Notification, long>(id, version);
+
+// Fetch without version check
+OrderStatus status = await GetInstanceAsync<OrderStatus, byte>(statusId);
+
+// Add + save
+_context.DbSet<Order>().Add(order);
+await _context.SaveChangesAsync();
+
+// Batch delete
+await _context.DbSet<OrderItem>()
+    .Where(x => x.Order.Id == orderId)
+    .ExecuteDeleteAsync();
+```
+
+### Transactions
+
+```csharp
+StorefrontPlaceOrderResultDTO result = await _context.WithTransactionAsync(async () =>
+{
+    // All operations here are atomic
+    _context.DbSet<Order>().Add(order);
+    await _context.SaveChangesAsync();
+
+    foreach (var item in dto.Items)
+    {
+        _context.DbSet<OrderItem>().Add(new OrderItem { Order = order, ... });
+        variant.Stock -= item.Quantity;
+    }
+    await _context.SaveChangesAsync();
+
+    return new StorefrontPlaceOrderResultDTO { OrderNumber = order.OrderNumber };
+});
+```
+
+### Current User Context
+
+```csharp
+long currentUserId = _authenticationService.GetCurrentUserId();
+
+UserWishlist wishlist = await _context.DbSet<UserWishlist>()
+    .FirstOrDefaultAsync(x => x.User.Id == currentUserId);
+```
+
+### Calling Generated Service Methods
+
+Within an entity service, call inherited methods directly. From other services, resolve the entity service via DI:
+
+```csharp
+// Within ProductService — call inherited generated methods directly
+PaginatedResultDTO<ProductDTO> products = await GetPaginatedProductList(
+    filterDTO, _deps.Context.DbSet<Product>(), authorize: false);
+
+// From a different service — resolve the entity service via DI
+ProductServiceGenerated productService =
+    _deps.ServiceProvider.GetRequiredService<ProductServiceGenerated>();
+PaginatedResultDTO<ProductDTO> products = await productService.GetPaginatedProductList(
+    filterDTO, _deps.Context.DbSet<Product>(), authorize: false);
+
+// Use the internal overload for custom projection
+PaginatedResult<Product> result = await GetPaginatedProductList(filterDTO, query);
+List<CustomDTO> dtos = await result.Query
+    .Skip(filterDTO.First).Take(filterDTO.Rows)
+    .Select(x => new CustomDTO { ... })
+    .ToListAsync();
+```
+
+## Return Types
+
+| Return Type | When to Use | HTTP Status |
+|---|---|---|
+| `Task<TDto>` | Single entity | 200 with JSON |
+| `Task<List<TDto>>` | Entity list | 200 with JSON array |
+| `Task<PaginatedResultDTO<T>>` | Paginated data | 200 with `{ data, totalRecords }` |
+| `Task` (void) | Fire-and-forget actions | 200 empty |
+| `Task<int>` / `Task<string>` | Scalar values | 200 with value |
+| `Task<IActionResult>` | File downloads, conditional status | Varies |
+| `Task<ActionResult<TDto>>` | Entity or 404 | 200 or 404 |
+
+```csharp
+// File download (inject IOptions<Spiderly.Shared.ExcelOptions> excelOptions via the constructor)
+return File(bytes, excelOptions.Value.ExcelContentType, "export.xlsx");
+
+// Conditional 404
+StorefrontBrandDTO result = await _catalogService.GetBrandBySlug(slug);
+if (result == null) return NotFound();
+return result;
+
+// Webhook acknowledgement
+return Ok();
+```
+
+### Return and parameter types must be discoverable (SPIDERLY001)
+
+Any custom class used as a controller return type or `[FromBody]` parameter must be discoverable by the source generator, otherwise the generated Angular TS client will reference an undefined type. A type is discoverable when it carries one of:
+
+- `[SpiderlyDTO]` — hand-written DTO, **or**
+- `[SpiderlyEntity]` — Spiderly entity.
+
+If the generator can't resolve the type, it emits build error **SPIDERLY001** at `dotnet build` time — no more broken TypeScript references surfacing later at `ng build`.
+
+**Canonical pattern for custom response shapes:**
+
+```csharp
+using Spiderly.Shared.Attributes;
+
+namespace MyProject.Business.DTO
+{
+    [SpiderlyDTO]
+    public partial class CheckoutSummaryDTO
+    {
+        public decimal Total { get; set; }
+        public int ItemCount { get; set; }
+    }
+}
+
+// In controller
+[HttpGet]
+public async Task<CheckoutSummaryDTO> GetCheckoutSummary() => await _service.BuildSummary();
+```
+
+**Anti-pattern** — plain C# class with no marker attribute:
+
+```csharp
+// WILL TRIGGER SPIDERLY001
+public class CheckoutSummary { public decimal Total { get; set; } }
+
+[HttpGet]
+public async Task<CheckoutSummary> GetCheckoutSummary() => ...;  // ❌ broken TS ref
+```
+
+**Fix:** add `[SpiderlyDTO]` (conventionally suffix the class name with `DTO`).
+
+### Prefer generated TS over hand-written `api.service.ts`
+
+The Spiderly CLI generates a typed method in `api.service.generated.ts` for every action on a `[SpiderlyController]` whose DTOs are `[SpiderlyDTO]`, plus the matching TS classes in `entities.generated.ts`. **Default to this** — one source of truth (C# DTOs), automatic regeneration on changes, no drift between backend and frontend types.
+
+Requirements to enable auto-generation:
+
+1. Put `[SpiderlyDTO]` DTOs in the flat `{App}.Business.DTO` namespace — **not** a sub-namespace like `{App}.Business.DTO.Foo`. The `ExcelPropertiesToExclude` and `ValidationRules` source generators only emit `using {App}.Business.DTO;` and will fail with `CS0246` for types in sub-namespaces.
+2. Mark the controller with `[SpiderlyController]` and **do not** add `[UIDoNotGenerate]`.
+3. Use explicit action names that disambiguate across controllers (e.g. `GetSupplierReplenishmentDrafts`, not bare `GetDrafts`) — the generated TS method is camelCase of the action name, unscoped by controller.
+
+Naming convention the generator applies:
+- DTO `FooBarDTO` → TS class `FooBar` in `entities.generated.ts`
+- Action `GetFooBar` → TS method `getFooBar` in `api.service.generated.ts`
+
+Consume in Angular by importing from the generated files directly — do **not** re-declare local interfaces or add a hand-written method to `api.service.ts`.
+
+### When to opt out (manual `api.service.ts`)
+
+Add `[UIDoNotGenerate]` to the controller + leave DTOs plain (no `[SpiderlyDTO]`) + write the method by hand in `api.service.ts` **only** when the shape cannot be auto-generated:
+- `IFormFile` uploads (bulk Excel import, image upload)
+- `Blob` responses (PDF download via `responseType: 'blob'`)
+- Custom content-type / header negotiation
+
+### Validation traps
+
+- `[StringLength]` on a `List<string>` (or any collection-of-scalar) breaks the FluentValidation generator with `CS1929` — it emits `.MaximumLength(...)` which only exists for scalar strings. Apply `[StringLength]` only to scalar `string` properties; leave collection elements unconstrained at the DTO level.
+
+## Exception Handling
+
+| Type | HTTP | When |
+|---|---|---|
+| `BusinessException(message)` | 400 | User-facing validation errors |
+| `SecurityViolationException()` | 403 | Tampering, impossible conditions |
+
+```csharp
+if (dto.Items.Count == 0)
+    throw new BusinessException("Cart is empty.");
+
+if (paymentMethod == null)
+    throw new SecurityViolationException($"Invalid PaymentMethodId: {dto.PaymentMethodId}");
+```
+
+## Key Attributes
+
+| Attribute | Purpose |
+|---|---|
+| `[AuthGuard]` | Require valid JWT |
+| `[UIDoNotGenerate]` | Hide from Swagger / skip Angular UI generation |
+| `[SkipSpinner]` | Skip the global full-screen blocking spinner. **Usually unnecessary** — auto-applied to `Namebook`/`Codebook`/`PaginatedResult`/`LazyLoadSelectedIds` returns and to any `HttpGet` returning a bare scalar (`int`/`bool`/`decimal`/`DateTime`/…). Add it manually only when the inference can't see your intent: a GET that returns a **full DTO but is polled/refreshed on a timer**, a background submit, or a fetch feeding a **lightweight popover/inline panel** where a full-screen block is disproportionate. |
+| `[ShowSpinner]` | Force the spinner back ON, overriding the auto-skip. **Rarely needed** — a slow user-triggered operation is usually a `POST` (which keeps the spinner without any attribute). Use only for a deliberately slow `HttpGet` returning a bare scalar where you still want the blocking overlay. |
+| `[ApiExplorerSettings(GroupName = "...")]` | Swagger grouping |
+| `[FromForm]` | Bind file uploads |
+| `[FromBody]` | Bind JSON body |
+
+## DI Registration
+
+Entity services are auto-registered by the generated `EntityServiceRegistration` class. Register custom services in `Extensions/AppServiceExtensions.cs`:
+
+```csharp
+public static class AppServiceExtensions
+{
+    public static IServiceCollection AddAppServices(this IServiceCollection services)
+    {
+        // Entity services (auto-generated — registers all {Entity}ServiceGenerated + user overrides)
+        services.AddEntityServices();
+
+        // Custom services
+        services.AddTransient<StorefrontCatalogService>();
+        services.AddTransient<MeilisearchService>();
+        services.AddTransient<IPaymentGateway, RaiAcceptPaymentGateway>();
+
+        return services;
+    }
+}
+```
+
+Then call `services.AddAppServices()` in `Startup.ConfigureServices()`. Inject into controllers via constructor — the DI container resolves all dependencies automatically.
+
+If you create an `{Entity}Service` that extends `{Entity}ServiceGenerated`, the auto-generated registration detects it and registers both the concrete type and the generated base type to resolve to your override.
+
+## Custom DTOs
+
+Define in `Business/DTOs/` or a similar folder:
+
+```csharp
+public class StorefrontProductDTO
+{
+    [Required]
+    public long Id { get; set; }
+
+    [Required]
+    public string Title { get; set; }
+
+    public decimal? SalePrice { get; set; }
+
+    [Required]
+    public string ImageUrl { get; set; }
+}
+```
+
+Use `[Required]` on non-nullable fields for correct Swagger/TypeScript generation.
+
+**Validation attributes belong on input DTOs only.** On a DTO that accepts data (a request body you `ValidateAndThrow` and persist), `[StringLength]`, `[GreaterThanOrEqualTo]`, etc. produce FluentValidation + Angular rules that actually run. On a readonly/output-only DTO — something you only return, like the example above — skip them: nothing ever validates data the server itself produced, so the rules are dead weight. The one attribute to keep on output DTOs is `[Required]`, because it also drives Swagger nullability and therefore the generated TypeScript types. (A render-only `[SpiderlyDTO]` currently still emits unused Angular form-validators — harmless noise; tracked as filiptrivan/spiderly#242.)
+
+## Extending PermissionCodes
+
+Add custom permission codes via partial class:
+
+```csharp
+public static partial class PermissionCodes
+{
+    public static string ExportReports { get; } = "ExportReports";
+    public static string ManageSettings { get; } = "ManageSettings";
+}
+```
+
+Then check in custom code:
+
+```csharp
+await _authorizationService.AuthorizeAndThrowAsync<User>(PermissionCodes.ExportReports);
+```