spiderly 19.8.4 → 19.8.6

package/agent/docs/file-storage/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: file-storage
+description: Configure file storage providers and blob upload behavior in Spiderly. Use when setting up storage for entity blob properties, choosing a built-in adapter, writing a custom adapter, or troubleshooting file upload issues.
+---
+
+# File Storage
+
+## How storage is selected
+
+Per blob property. Decorate a string property with a `StorageAttribute` subclass; the source generator emits upload/delete code that resolves the matching `IFileManager` adapter from DI for that property only. There is no global storage registration — every blob property declares which adapter it goes through.
+
+## Built-in adapters
+
+Spiderly ships three built-in adapters and matching attributes:
+
+| Adapter | Attribute | Best for | Returns |
+| --- | --- | --- | --- |
+| `DiskStorageService` | `[DiskStorage]` | Local development | File key |
+| `S3PublicStorageService` | `[S3PublicStorage]` | CDN-served images, public assets | Full public URL |
+| `S3PrivateStorageService` | `[S3PrivateStorage]` | Private documents, signed-URL access | S3 key |
+
+All three implement `Spiderly.Shared.Interfaces.IFileManager`.
+
+## Entity property declaration
+
+```csharp
+public class Brand : BusinessObject<int>
+{
+    [S3PublicStorage]
+    [AcceptedFileTypes("image/*")]
+    [MaxFileSize(2_000_000)]
+    [StringLength(1000, MinimumLength = 1)]
+    public string LogoUrl { get; set; }
+}
+
+public class WarrantyRegistration : BusinessObject<long>
+{
+    [S3PrivateStorage]
+    [AcceptedFileTypes("image/jpeg", "image/png", "application/pdf")]
+    [MaxFileSize(10_000_000)]
+    [StringLength(1000, MinimumLength = 1)]
+    public string ReceiptImageUrl { get; set; }
+}
+```
+
+`[StorageAttribute]` subclasses replace the legacy `[BlobName]` marker — presence of any subclass is what marks a string property as a blob.
+
+| Attribute | Level | Purpose |
+| --- | --- | --- |
+| `[DiskStorage]` / `[S3PublicStorage]` / `[S3PrivateStorage]` | Property | Routes uploads through the matching adapter |
+| `[AcceptedFileTypes("mime/type", ...)]` | Property | **Required on every blob property** — MIME-type whitelist. Build error `SPIDERLY014` if missing. No default. |
+| `[MaxFileSize(N)]` | Property | Max bytes (default: 20MB) |
+| `[ImageWidth(N)]` / `[ImageHeight(N)]` | Property | Validate exact image dimensions |
+
+## DI registration
+
+Spiderly's source generator emits `_deps.ServiceProvider.GetRequiredService<TConcrete>()` per blob property, so each adapter you use must be discoverable by its concrete type.
+
+`DiskStorageService` is pre-registered by the `spiderly init` template in `AppServiceExtensions.AddAppServices` (it's the dev default and has no external dependencies). When you opt in to S3, register the adapters you reference there:
+
+```csharp
+// In your AppServiceExtensions.cs
+services.AddSingleton<S3PublicStorageService>();
+services.AddSingleton<S3PrivateStorageService>();
+```
+
+The storage services are stateless wrappers around external clients (the `IAmazonS3` instance for S3, the local filesystem for Disk) — `Singleton` avoids per-resolve constructor work like the `Directory.CreateDirectory` call in `DiskStorageService`.
+
+The S3 client itself is registered separately (one `IAmazonS3` shared by both S3 adapters):
+
+```csharp
+services.AddSingleton<IAmazonS3>(sp =>
+{
+    IConfiguration configuration = sp.GetRequiredService<IConfiguration>();
+    AmazonS3Config s3Config = new AmazonS3Config
+    {
+        ServiceURL = configuration.GetValue<string>($"{Spiderly.Shared.Settings.ConfigurationSection}:S3ServiceUrl"),
+        ForcePathStyle = true,
+        AuthenticationRegion = "auto",
+    };
+
+    return new AmazonS3Client(
+        new BasicAWSCredentials(
+            configuration.GetValue<string>($"{Spiderly.Shared.Settings.ConfigurationSection}:S3AccessKey"),
+            configuration.GetValue<string>($"{Spiderly.Shared.Settings.ConfigurationSection}:S3SecretKey")
+        ),
+        s3Config
+    );
+});
+```
+
+## Configuration (`appsettings.json`)
+
+```json
+{
+  "AppSettings": {
+    "Spiderly.Shared": {
+      "S3BucketName": "my-bucket",
+      "S3PublicEndpoint": "https://cdn.example.com"
+    }
+  }
+}
+```
+
+S3 credentials (`S3AccessKey`, `S3SecretKey`, `S3ServiceUrl`) are app-specific settings, not in `Spiderly.Shared`.
+
+## Writing a custom storage adapter
+
+Spiderly ships only the three adapters above. Other backends (Cloudinary, Azure Blob, Backblaze, on-prem MinIO, …) are written by the consumer:
+
+1. Implement `IFileManager`:
+
+   ```csharp
+   public class MyCustomStorageService : IFileManager
+   {
+       public Task<string> UploadFileAsync(...) { /* impl */ }
+       public Task DeleteNonActiveBlobs(...)    { /* impl */ }
+       public Task<string> GetFileDataAsync(string key) { /* impl */ }
+       public Task<string> MoveBlobToEntityPathAsync(...) { /* impl */ }
+       public Task DeleteNonActiveEditorImages(...) { /* impl */ }
+   }
+   ```
+
+2. Subclass `StorageAttribute`, passing your service type to the base constructor:
+
+   ```csharp
+   public sealed class MyCustomStorageAttribute : StorageAttribute
+   {
+       public MyCustomStorageAttribute() : base(typeof(MyCustomStorageService)) { }
+   }
+   ```
+
+3. Register the service in DI:
+
+   ```csharp
+   services.AddTransient<MyCustomStorageService>();
+   ```
+
+4. Use the attribute on entity properties:
+
+   ```csharp
+   [MyCustomStorage]
+   [AcceptedFileTypes("image/*")]
+   [StringLength(1000, MinimumLength = 1)]
+   public string Photo { get; set; }
+   ```
+
+The source generator detects custom storage attributes by the convention "attribute name ends with `Storage`" — so `MyCustomStorageAttribute` is treated as a blob marker automatically. The generator's auto-resolution of the field name is currently hard-coded for the three built-ins; for custom adapters, the generated code emits a marker comment indicating it can't dispatch — you'll need to inject your custom service directly into hand-written upload paths instead of relying on Spiderly's auto-CRUD endpoints. (Open issue: extend the source generator to read `StorageAttribute.ServiceType` from the subclass's base initializer to support fully-automatic custom-adapter routing.)
+
+## Upload flow
+
+Generated methods per blob property:
+
+```
+1. Upload{Property}For{Entity}(IFormFile file)         ← Controller endpoint
+2.   → OnBefore{Property}BlobFor{Entity}UploadIsAuthorized(file, id)
+3.   → OnBefore{Property}BlobFor{Entity}IsUploaded(stream, file, id)
+4.       → For image/* content types:
+5.           → ValidateImageFor{Property}Of{Entity}(stream, file, id)
+6.           → OptimizeImageFor{Property}Of{Entity}(stream, file, id)
+7.   → storageService.UploadFileAsync(...)            ← resolved per [*Storage] attribute
+8.   → Returns file key/URL (semantics depend on the adapter)
+```
+
+On entity save (Update/Insert):
+
+```
+→ storageService.DeleteNonActiveBlobs(activeKey, entityName, propertyName, entityId)
+```
+
+## Upload hooks
+
+Override in your entity service class:
+
+```csharp
+// Authorization hook — run before upload
+public override async Task OnBeforeMainImageBlobForProductUploadIsAuthorized(
+    IFormFile file, long id)
+{
+    // Custom authorization logic
+}
+
+// Full preprocessing hook — runs for ALL file types
+public override async Task<byte[]> OnBeforeMainImageBlobForProductIsUploaded(
+    Stream stream, IFormFile file, long id)
+{
+    // For images: validate then optimize
+    if (file.ContentType.StartsWith("image/"))
+    {
+        await ValidateImageForMainImageOfProduct(stream, file, id);
+        stream.Position = 0;
+        return await OptimizeImageForMainImageOfProduct(stream, file, id);
+    }
+    return await Helper.ReadAllBytesAsync(stream);
+}
+
+// Image validation — check dimensions, format, etc.
+public override async Task ValidateImageForMainImageOfProduct(
+    Stream stream, IFormFile file, long id)
+{
+    await Helper.ValidateImageDimensions(stream, width: 800, height: 600);
+}
+
+// Image optimization — resize, compress, convert format
+public override async Task<byte[]> OptimizeImageForMainImageOfProduct(
+    Stream stream, IFormFile file, long id)
+{
+    return await Helper.OptimizeImage(stream, new Size(800, 600), quality: 80);
+}
+```
+
+### Helper.OptimizeImage
+
+```csharp
+public static async Task<byte[]> OptimizeImage(
+    Stream originalImageStream,
+    Size? newImageSize = null,  // null = keep original size
+    int quality = 85            // WebP quality
+)
+```
+
+- Converts to **WebP lossy** format (via SixLabors.ImageSharp)
+- Resizes with `ResizeMode.Max` (fit within bounds, not crop)
+- Default quality: 85
+
+### Helper.ValidateImageDimensions
+
+```csharp
+public static async Task ValidateImageDimensions(
+    Stream imageStream,
+    int width = 0,   // 0 = skip width check
+    int height = 0   // 0 = skip height check
+)
+```
+
+Throws `SecurityViolationException` if dimensions don't match exactly.
+
+## Cleanup methods
+
+### `DeleteNonActiveBlobs`
+
+Called automatically during entity save. Deletes all previously uploaded files for a property except the current active one. Uses file naming prefix to find old files.
+
+### `DeleteNonActiveEditorImages`
+
+For rich text `[Editor]` properties paired with `[S3PublicStorage]`. Extracts `<img>` URLs from HTML, deletes uploaded images that are no longer referenced.
+
+```csharp
+List<string> activeUrls = Helper.ExtractImageUrlsFromHtml(dto.HtmlDescription);
+await _s3PublicStorageService.DeleteNonActiveEditorImages(
+    activeUrls, nameof(Brand), nameof(Brand.HtmlDescription) + "Image", id.ToString());
+```
+
+Only implemented for `S3PublicStorageService`. Other built-in providers throw `NotImplementedException`.
+
+## File naming convention
+
+All providers generate: `{objectId}-{objectType}-{objectProperty}-{GUID}.{extension}`
+
+S3 providers add folder structure: `{objectType}/{objectProperty}/{objectId}/{filename}`
+
+This prefix-based naming enables `DeleteNonActiveBlobs` to find and clean up old files without database tracking.

package/agent/docs/filtering-patterns/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: filtering-patterns
+description: Customize server-side filtering, pagination, and paginated list overrides. Use when doing custom server-side filtering, overriding paginated lists, working with FilterDTO, using AdditionalFilterId for parent-child filtering, or building programmatic filters.
+---
+
+# Filtering Patterns
+
+## FilterDTO Structure
+
+```csharp
+public class FilterDTO
+{
+    public Dictionary<string, List<FilterRuleDTO>> Filters { get; set; } = new();
+    public int First { get; set; }          // zero-based offset
+    public int Rows { get; set; }           // page size
+    public List<FilterSortMetaDTO> MultiSortMeta { get; set; } = new();
+    public int? AdditionalFilterIdInt { get; set; }
+    public long? AdditionalFilterIdLong { get; set; }
+    public byte? AdditionalFilterIdByte { get; set; }
+}
+
+public class FilterRuleDTO
+{
+    public object Value { get; set; }
+    public string MatchMode { get; set; }
+    public string Operator { get; set; }    // "and" / "or"
+}
+```
+
+**Match modes** — the `MatchMode` values a filter rule can use, generated from the `MatchModeCodes` contract: see [references/match-mode-codes.generated.md](references/match-mode-codes.generated.md).
+
+Filter dictionary keys are **camelCase DTO property names**. The generated `PaginatedResultGenerator` auto-resolves them to entity paths (e.g., `categoryDisplayName` → `x.Category.Name`).
+
+## Override `GetPaginated{Entity}List` (Most Common)
+
+The most common customization — pre-filter the query before pagination:
+
+```csharp
+public override async Task<PaginatedResultDTO<CommentDTO>> GetPaginatedCommentList(
+    FilterDTO filterDTO,
+    IQueryable<Comment> query,
+    bool authorize)
+{
+    // Add custom WHERE clauses
+    query = query.Where(x => x.IsApproved == true);
+
+    // Parent-child filtering via AdditionalFilterId
+    if (filterDTO.AdditionalFilterIdLong.HasValue)
+        query = query.Where(x => x.BlogPost.Id == filterDTO.AdditionalFilterIdLong.Value);
+
+    return await base.GetPaginatedCommentList(filterDTO, query, authorize);
+}
+```
+
+Always call `base.GetPaginated{Entity}List(...)` to keep generated filtering, sorting, pagination, and authorization intact.
+
+## Programmatic `FilterDTO<T>` API
+
+Build filters in backend code with type-safe fluent API:
+
+```csharp
+FilterDTO<Product> filter = new FilterDTO<Product>()
+    .AddFilter(x => x.Name, "widget", MatchModeCodes.Contains)
+    .AddFilter(x => x.Price, 100m, MatchModeCodes.GreaterThan)
+    .AddSort(x => x.CreatedAt, -1)   // -1 = descending
+    .SetPagination(0, 25);
+
+PaginatedResultDTO<ProductDTO> result = await GetPaginatedProductList(
+    filter, _context.DbSet<Product>(), authorize: false);
+```
+
+Property names are auto-converted from PascalCase to camelCase.
+
+## AdditionalFilterId Pattern
+
+Pass a parent ID from the frontend to filter child records server-side.
+
+**Frontend (Angular):**
+
+```html
+<spiderly-data-table
+  [cols]="cols"
+  [getPaginatedListObservableMethod]="getCommentListObservableMethod"
+  [additionalFilterIdLong]="blogPostId">
+</spiderly-data-table>
+```
+
+**Backend override:**
+
+```csharp
+public override async Task<PaginatedResultDTO<CommentDTO>> GetPaginatedCommentList(
+    FilterDTO filterDTO,
+    IQueryable<Comment> query,
+    bool authorize)
+{
+    if (filterDTO.AdditionalFilterIdLong.HasValue)
+        query = query.Where(x => x.BlogPost.Id == filterDTO.AdditionalFilterIdLong.Value);
+
+    return await base.GetPaginatedCommentList(filterDTO, query, authorize);
+}
+```
+
+Use `AdditionalFilterIdInt`, `AdditionalFilterIdLong`, or `AdditionalFilterIdByte` based on the parent entity's ID type.
+
+## Custom Projection (Advanced)
+
+For fully custom DTOs (e.g., storefront-specific), call the internal overload that returns `PaginatedResult<T>` (with query + total count), then project yourself:
+
+```csharp
+public async Task<PaginatedResultDTO<CustomDTO>> GetPaginatedProductsCustom(
+    FilterDTO filterDTO, IQueryable<Product> query)
+{
+    PaginatedResult<Product> result = await GetPaginatedProductList(filterDTO, query);
+
+    List<CustomDTO> dtos = await result.Query
+        .Skip(filterDTO.First)
+        .Take(filterDTO.Rows)
+        .Select(x => new CustomDTO { Id = x.Id, Title = x.Title })
+        .ToListAsync();
+
+    return new PaginatedResultDTO<CustomDTO>
+    {
+        Data = dtos,
+        TotalRecords = result.TotalRecords
+    };
+}
+```

package/agent/docs/filtering-patterns/references/match-mode-codes.generated.md

@@ -0,0 +1,15 @@
+<!-- GENERATED FROM framework-metadata.json — DO NOT EDIT.
+     Regenerate: `dotnet run --project Spiderly.MetadataExporter -- --out framework-metadata.json && node tools/extract-ts-metadata.mjs && node tools/gen-skill-docs.mjs` -->
+
+# Filter match modes
+
+String constants for the comparison operators a filter rule can use (carried on FilterRuleDTO.MatchMode). The values mirror PrimeNG's table filter match modes, so the same code drives both the Angular UI and the server-side query translation in the generated paginated-list logic.
+
+| Name | Value | Description |
+| --- | --- | --- |
+| `Contains` | `contains` | String substring match, case-insensitive (value.Contains(...)). |
+| `Equals` | `equals` | Equality match. For strings it is case-insensitive; for bool, number, and date/time properties it is an exact == comparison. |
+| `GreaterThan` | `greaterThan` | Greater-than comparison (>), for number and date/time properties. |
+| `In` | `in` | Membership match against a JSON array of values (value IN [...]), for number and id properties. |
+| `LessThan` | `lessThan` | Less-than comparison (<), for number and date/time properties. |
+| `StartsWith` | `startsWith` | String prefix match, case-insensitive (value.StartsWith(...)). |

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

@@ -0,0 +1,120 @@
+---
+name: frontend-localization
+description: How Spiderly localizes Angular admin-panel UI strings — labels, buttons, menu items, validation messages, any user-facing text. Spiderly uses Transloco with flat assets/i18n/{lang}.json files loaded by SpiderlyTranslocoLoader. Use whenever you add or translate a UI string, hit a raw translation key rendering on screen, set up or change languages (provideTransloco / availableLangs), use translocoService.translate or the *transloco template directive, run i18n:extract, or wonder how form labels get auto-translated. For .NET backend strings (error messages, Excel names, IStringLocalizer), use the backend-localization skill instead.
+---
+
+# Frontend Localization
+
+The Spiderly Angular admin panel localizes every user-facing string through **Transloco**. Translation files are flat key→value JSON, one per language, served as static assets and loaded over HTTP at runtime — there is no compile-time embedding. Never hardcode user-facing English in a template; route it through a translation key so it localizes with the rest of the panel (e.g. a PACMS app runs entirely in Serbian).
+
+This is a **separate system from the backend**: a string shown by the API (a `BusinessException` message) is translated on the .NET side via `IStringLocalizer` (see the **backend-localization** skill); a string rendered by the admin UI is translated here.
+
+## Setup (`app.config.ts`)
+
+Transloco is registered in the app's `ApplicationConfig` with Spiderly's loader:
+
+```typescript
+provideTransloco({
+  config: {
+    availableLangs: ['sr-Latn-RS'],   // every language you ship a JSON file for
+    defaultLang: 'sr-Latn-RS',
+    reRenderOnLangChange: false,       // true only if you let users switch language at runtime
+  },
+  loader: SpiderlyTranslocoLoader,     // from the `spiderly` package
+}),
+```
+
+`SpiderlyTranslocoLoader` fetches `${ConfigService.frontendUrl}/assets/i18n/{lang}.json`. So:
+
+- Files live in **`src/assets/i18n/{lang}.json`**, named **exactly** after a `lang` in `availableLangs` (e.g. `sr-Latn-RS.json`, `en.json`).
+- They must be deployed as static assets (they're requested over HTTP, not bundled). They already are under `src/assets`, but a build that drops the `assets/` glob will 404 the translations and every key renders raw.
+
+## File format
+
+A flat JSON object — no nesting:
+
+```jsonc
+// src/assets/i18n/sr-Latn-RS.json
+{
+  "Save": "Sačuvaj",
+  "Products": "Proizvodi",
+  "Product": "Proizvod",
+  "InvalidSKU": "SKU mora biti 6–12 velikih slova/brojeva.",
+  "WelcomeUser": "Dobrodošli, {{name}}!"
+}
+```
+
+Parameters use Transloco's `{{param}}` syntax: `translocoService.translate('WelcomeUser', { name: user.name })`.
+
+## Using translations
+
+**In TypeScript** — inject `TranslocoService`:
+
+```typescript
+this.translocoService.translate('Products');
+this.translocoService.translate('WelcomeUser', { name: user.name });
+```
+
+**In templates** — open a Transloco context once, then call `t(...)`:
+
+```html
+<ng-container *transloco="let t">
+  <spiderly-button [label]="t('Save')"></spiderly-button>
+  <h2>{{ t('Products') }}</h2>
+</ng-container>
+```
+
+Add `TranslocoDirective` to the component's `imports` to use `*transloco`.
+
+### Adding a new key
+
+1. Add it to **every** `assets/i18n/{lang}.json` (one entry per language).
+2. Reference it via `translate('Key')` / `t('Key')`.
+
+Run **`npm run i18n:extract`** (transloco-keys-manager) to scan `src/` and add any missing keys to the JSON files automatically — use it instead of hand-syncing. Note it scans only your own `src/`, **not** `node_modules/spiderly`; keys used inside Spiderly's own library components are pre-seeded by `spiderly init`, so they resolve out of the box.
+
+## Form label auto-translation
+
+You rarely translate field labels by hand. When `BaseFormService` builds a form, it sets each control's `labelForDisplay` from `getTranslatedLabel(controlName)`, which normalizes the camelCase property name to a key and translates it:
+
+- strips a trailing `Id` (`productId` → `Product`)
+- strips a trailing `DisplayName` (`categoryDisplayName` → `Category`)
+- upper-cases the first char, then `translate(...)`
+
+So `name` → key `Name`, `productId` → key `Product`, `categoryDisplayName` → key `Category`. Provide those PascalCase keys in your i18n files and labels localize automatically. (The form/control mechanics themselves are documented in the **angular-customization** skill.)
+
+## Translating menu items and validation messages
+
+These are ordinary `translate(...)` calls — the surrounding mechanics live in **angular-customization**; only the translation call is shown here.
+
+```typescript
+// Menu (layout.component.ts)
+menu: SpiderlyMenuItem[] = [
+  { label: this.translocoService.translate('Dashboard'), icon: 'pi pi-fw pi-home', routerLink: ['/dashboard'] },
+];
+
+// Custom validator message (ValidatorAbstractService subclass)
+if (value && !value.match(/^[A-Z0-9]{6,12}$/))
+  return { _: this.translocoService.translate('InvalidSKU') };
+```
+
+## Static text in custom library-style components
+
+If you build a reusable control/component with text baked into its template, route it through Transloco rather than hardcoding — same rule the Spiderly library follows for its own controls:
+
+```html
+<ng-container *transloco="let t">
+  <p-tab>{{ t('Preview') }}</p-tab>
+</ng-container>
+```
+
+## Gotchas
+
+- **A missing key renders the raw key.** Transloco's default `missingHandler` returns the key string, so a typo'd or unseeded key leaks the identifier (e.g. `InvalidSKU`) onto the screen instead of erroring. Treat a raw-key sighting as a missing-translation bug. Keep keys in sync across all `{lang}.json` files and lean on `i18n:extract`.
+- **Filename must match `availableLangs`.** `SpiderlyTranslocoLoader` requests `{lang}.json` for the active lang; a mismatch (`sr.json` while `availableLangs` is `['sr-Latn-RS']`) 404s and the whole file falls through to raw keys.
+- **Translations are fetched, not bundled.** They load over HTTP from `frontendUrl/assets/i18n/`. A misconfigured `frontendUrl` (in `ConfigService`) or a build that strips the `assets` glob breaks all translations at once — a useful first thing to check when *everything* shows raw keys.
+- **`reRenderOnLangChange: false`** means a runtime language switch won't re-render already-rendered text. Set it to `true` only if you actually offer in-session language switching.
+
+## Backend strings are a separate system
+
+This skill is the Angular admin panel only. Server-side strings (API error messages, Excel export names, anything from a `BusinessException`) are localized on the .NET side through `IStringLocalizer` and `Translations/{culture}.json` — a completely separate mechanism. Use the **backend-localization** skill for those.

package/agent/docs/mapper-customization/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: mapper-customization
+description: Customize Spiderly-generated Mapster mappers. Use when overriding DTO-to-entity or entity-to-DTO mapping, adding computed fields to DTOs, customizing query projections, or using the ProjectToDTO attribute.
+---
+
+# Mapper Customization
+
+## Generated Methods
+
+Spiderly generates **4 Mapster configuration methods per entity** (3 for abstract entities) in a `partial class Mapper`:
+
+| Method | Direction | Used By |
+|---|---|---|
+| `{Entity}DTOToEntityConfig()` | DTO → Entity | Save flow (mapping DTO to entity before insert/update) |
+| `{Entity}ToDTOConfig()` | Entity → DTO | Main UI form, general DTO mapping |
+| `{Entity}ProjectToConfig()` | Entity → DTO | Paginated list queries (projection) |
+| `{Entity}ExcelProjectToConfig()` | Entity → DTO | Excel export projection |
+
+Each method returns a `TypeAdapterConfig` with Mapster mappings. For M2O relationships, the generator automatically maps `{Nav}Id` and `{Nav}DisplayName`:
+
+```csharp
+public static TypeAdapterConfig CartToDTOConfig()
+{
+    TypeAdapterConfig config = new();
+
+    config
+        .NewConfig<Cart, CartDTO>()
+        .Map(dest => dest.UserId, src => src.User.Id)
+        .Map(dest => dest.UserDisplayName, src => src.User.Email)
+        .Map(dest => dest.CartStatusId, src => src.CartStatus.Id)
+        .Map(dest => dest.CartStatusDisplayName, src => src.CartStatus.Name)
+        ;
+
+    return config;
+}
+```
+
+## `[ProjectToDTO]` — Inline Custom Mappings
+
+Add custom mappings to the projection method without overriding it. Applied to the **entity class** (not properties). `AllowMultiple = true`.
+
+```csharp
+[ProjectToDTO(".Map(dest => dest.TransactionPrice, src => src.Transaction.Price)")]
+public class Achievement : BusinessObject<long>
+{
+    // ...
+}
+```
+
+The string is appended directly to the generated `.NewConfig<Entity, EntityDTO>()` chain. Use this for simple field mappings that the generator doesn't produce automatically.
+
+## Partial Method Override — Full Control
+
+For complex mapping logic, override the entire generated method. The generator **skips generation** for any method that already exists in the user's partial `Mapper` class (detected by method name match).
+
+**Setup** — the user's mapper file (one per project, marked with `[SpiderlyDataMapper]`):
+
+```csharp
+using Spiderly.Shared.Attributes;
+
+namespace MyProject.Business.DataMappers
+{
+    [SpiderlyDataMapper]
+    public static partial class Mapper
+    {
+        // Override any generated method by declaring it here
+    }
+}
+```
+
+**Override example:**
+
+```csharp
+[SpiderlyDataMapper]
+public static partial class Mapper
+{
+    public static TypeAdapterConfig ProductToDTOConfig()
+    {
+        TypeAdapterConfig config = new();
+
+        config
+            .NewConfig<Product, ProductDTO>()
+            .Map(dest => dest.BrandId, src => src.Brand.Id)
+            .Map(dest => dest.BrandDisplayName, src => src.Brand.Name)
+            .Map(dest => dest.PriceWithTax, src => src.Price * 1.2m)
+            ;
+
+        return config;
+    }
+}
+```
+
+**Important:** When overriding, you take full responsibility — the generated M2O mappings won't be included automatically. Copy the generated method from `obj/.../Mapper.generated.cs` as a starting point, then add your custom mappings.
+
+## When to Use Each Approach
+
+| Scenario | Approach |
+|---|---|
+| Add a simple computed field to projection | `[ProjectToDTO(".Map(...)")]` on entity class |
+| Add multiple computed fields to projection | Stack multiple `[ProjectToDTO]` attributes |
+| Complex mapping with conditionals or method calls | Override the full method in `Mapper.cs` |
+| Change DTO → Entity mapping (e.g., ignore a field) | Override `{Entity}DTOToEntityConfig()` |
+| Change Excel export projection | Override `{Entity}ExcelProjectToConfig()` |
+
+Most projects never need custom mappers — the generated mappings handle M2O, M2M display names, and standard field-to-field mapping automatically.

package/agent/manifest.json

@@ -0,0 +1,34 @@
+{
+  "skills": [
+    {
+      "name": "add-entity",
+      "surface": "skill",
+      "description": "Scaffold a new Spiderly entity end-to-end (entity class, Angular pages, routes, menu, migration)"
+    },
+    {
+      "name": "deployment",
+      "surface": "skill",
+      "description": "Deploy a Spiderly project to your own infrastructure with Docker, Caddy, and Terraform. Use when deploying, redeploying, shipping, releasing, or rolling out the .NET backend or Angular admin to production — first-time setup or an ongoing deploy — and when diagnosing a down or erroring production origin (502/521, container crash-loop, failed deploy workflow). Also covers CI/CD pipelines, TLS with Cloudflare origin certificates, database backups and restores, and infrastructure-as-code layout for a Spiderly app."
+    },
+    {
+      "name": "ef-migrations",
+      "surface": "skill",
+      "description": "Create and apply EF Core migrations in Spiderly projects. Use when adding, modifying, or removing entity properties, changing column types, renaming columns, or any database schema change that requires a migration."
+    },
+    {
+      "name": "report-gap",
+      "surface": "skill",
+      "description": "Use the moment you're forced into a workaround because the clean Spiderly-native path didn't exist — you looked for a lifecycle hook, an override, an entity attribute, or a generator option and it was structurally missing, so you had to bypass or copy generated code, or reach into framework internals. Also use when the gap is in Spiderly's own skills, plugins, or docs — a skill that should have fired but didn't, or skill/doc content that was missing, stale, or wrong for the case you hit. Turns that gap into a pre-filled GitHub issue URL against filiptrivan/spiderly that the user copies and submits. Also invoke manually to report a Spiderly limitation. NOT for hacks in the consumer's own business logic, NOT for ordinary bugs in your own code."
+    },
+    {
+      "name": "spiderly-upgrade",
+      "surface": "skill",
+      "description": "Upgrade a Spiderly consumer app's package version (NuGet + npm) to a newer Spiderly release. Use when the user asks to upgrade Spiderly, bump the Spiderly version, jump to a newer Spiderly release, or migrate to a newer Spiderly package version. Do NOT use for EF Core schema migrations (see ef-migrations skill)."
+    },
+    {
+      "name": "verify-ui",
+      "surface": "skill",
+      "description": "Log past Spiderly's email-code auth wall to visually verify the running Angular admin panel — screenshot a page, click through a flow, or dogfood a UI change without writing a test. Use when asked to \"verify the admin UI\", \"check this page renders\", \"screenshot the admin panel\", \"does this screen look right\", or to eyeball a change in the live app. For authoring Playwright test suites or debugging CI traces, use the e2e-testing skill instead."
+    }
+  ]
+}