@chill-sharp/ui-core 1.1.12

package/doc/UiCore/CRUD.md

@@ -0,0 +1,170 @@
+# CRUD Menu Configuration
+
+Versione italiana: [Italiano](../it/UiCore/CRUD.md)
+
+Create a menu item with `ComponentName` set to `CRUD`. Its `ComponentConfigurationJson` must be a JSON object; keys are case-insensitive. `chillType` is required. Normally it is the entity Chill type and `chillQuery` is the query Chill type that returns that entity.
+
+```json
+{
+  "chillType": "Model.Post",
+  "chillQuery": "Query.PostQuery",
+  "viewCode": "default",
+  "disableAdd": false,
+  "disableCreate": false,
+  "disableEdit": false,
+  "disableInlineEdit": false,
+  "disableDelete": false,
+  "defaultValues": {},
+  "fixedValues": {},
+  "fixedQueryValues": {},
+  "defaultQueryValues": {},
+  "relations": []
+}
+```
+
+## Options
+
+| Key | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `chillType` | string | required | Entity Chill type displayed and edited by the task. |
+| `chillQuery` | string or `null` | `null` | Query Chill type. Configure it when the entity needs a dedicated query. |
+| `viewCode` | string | `default` | Schema view code used for the task. |
+| `disableAdd` | boolean | `false` | Hides the Add command. |
+| `disableCreate` | boolean | `false` | Prevents creating new records. |
+| `disableEdit` | boolean | `false` | Prevents dialog editing. |
+| `disableInlineEdit` | boolean | `false` | Prevents inline table editing. |
+| `disableDelete` | boolean | `false` | Prevents deletion. |
+| `defaultValues` | object | `{}` | Initial values for the create form; users may change them. |
+| `fixedValues` | object | `{}` | Create values made read-only in the form and inline editor. |
+| `fixedQueryValues` | object | `{}` | Mandatory query filters that the user cannot change. |
+| `defaultQueryValues` | object | `{}` | Initial query values the user may change. |
+| `relationLabel` | string or object | omitted | Label for this CRUD when it is opened as a relation. The object form is `{ "labelGuid", "primaryDefaultText", "secondaryDefaultText" }`. |
+| `relations` | array | `[]` | Child CRUD definitions available from each row's action menu. |
+
+Unknown JSON properties are retained by the menu editor but are not standard CRUD options.
+
+## Values and relation placeholders
+
+Values in the four value objects are JSON values. In a nested relation, a string `@{FieldName}` reads that property from the selected parent row, and `@{mock}` supplies a lightweight entity object for that parent row.
+
+### Which bag is applied, and when
+
+There are two independent flows:
+
+| Flow | Editable starting values | Values that take precedence |
+| --- | --- | --- |
+| Search/query | `defaultQueryValues` | `fixedQueryValues` |
+| Create entity | `defaultValues` | `fixedValues` |
+
+UI Core merges each flow in that order. Therefore, when the same property occurs in both bags, the value in the `fixed...` bag wins. Use only the fixed bag when a value must never be changed; use only the default bag when it is merely a useful starting value.
+
+`fixedQueryValues` constrains the records returned by the child CRUD. `fixedValues` constrains the entity sent by the create flow and marks those entity properties read-only in the form and inline editor. The fixed bags are configuration, not a replacement for server-side authorization or validation: the API must still enforce tenant, ownership, and authorization rules.
+
+### Static CLR-compatible values
+
+The JSON literal is passed as the property value; UI Core does not evaluate or convert it before normal entity/query serialization. Use the JSON representation that the ChillSharp API expects for the CLR property.
+
+```json
+{
+  "defaultQueryValues": {
+    "IsPublished": true,
+    "MinimumScore": 50,
+    "Category": "News",
+    "From": "2026-01-01T00:00:00+01:00"
+  },
+  "fixedValues": {
+    "TenantCode": "acme",
+    "Priority": 10,
+    "IsInternal": false,
+    "ArchivedAt": null
+  }
+}
+```
+
+Use JSON strings for CLR `string`, `Guid`, `DateTime`, `DateTimeOffset`, `DateOnly`, and enum values when the server exposes those enums as strings. Use JSON numbers for numeric CLR values and JSON booleans for `bool`. Dates and GUIDs must be JSON strings, not JavaScript expressions: `"2026-01-01"` and `"8d0946dc-fc2b-4d95-b5ca-6f12d9618a5b"`, not `new Date(...)` or `Guid.NewGuid()`.
+
+### Static entity-reference values
+
+Yes—an entity reference can be static because a JSON object is a permitted value. Supply the same reference shape accepted by the target property, normally at least the referenced entity identifier and type:
+
+```json
+{
+  "fixedQueryValues": {
+    "Customer": {
+      "guid": "8d0946dc-fc2b-4d95-b5ca-6f12d9618a5b",
+      "chillType": "Model.Customer"
+    }
+  },
+  "fixedValues": {
+    "Status": {
+      "guid": "7d8af0dd-d20d-4bb7-9a4d-f3b9d2f9c2b4",
+      "chillType": "Model.OrderStatus",
+      "label": "Approved"
+    }
+  }
+}
+```
+
+`label` is optional UI metadata. Do not rely on it for identity: `guid` identifies the entity. Include `chillType` when the reference can be polymorphic or when the server/client needs explicit type information. The exact property name and object shape must match the target query or entity schema; a scalar foreign-key property instead needs the scalar GUID string, for example `"CustomerGuid": "8d0946dc-fc2b-4d95-b5ca-6f12d9618a5b"`.
+
+### Dynamic values: `@{FieldName}` and `@{mock}`
+
+Placeholders are resolved only while opening a relation from a selected parent row. They are not expressions and are not evaluated in a root menu CRUD, because no parent entity exists there. In that case the original placeholder string remains unchanged.
+
+- `@{Guid}` copies the selected row's `Guid`/`guid` value.
+- `@{CustomerCode}` copies a field from the selected row's `properties` object or direct object properties. A camel-case token also falls back to the Pascal-case property name.
+- A missing field resolves to `null`.
+- `@{mock}` creates a lightweight copy of the selected parent entity. It carries its `guid`, `chillType`, `label`, and a copy of its `properties`; it does not fetch the entity again.
+
+Use `@{mock}` for a child reference property such as `Order`, and use `@{Guid}` for a scalar foreign key such as `OrderGuid`:
+
+```json
+{
+  "relations": [
+    {
+      "chillType": "Model.OrderRow",
+      "chillQuery": "Query.OrderRowQuery",
+      "fixedQueryValues": { "Order": "@{mock}" },
+      "defaultQueryValues": { "Order": "@{mock}" },
+      "fixedValues": { "Order": "@{mock}" },
+      "defaultValues": { "Order": "@{mock}" }
+    },
+    {
+      "chillType": "Model.OrderRow",
+      "chillQuery": "Query.OrderRowQuery",
+      "fixedQueryValues": { "OrderGuid": "@{Guid}" },
+      "fixedValues": { "OrderGuid": "@{Guid}" }
+    }
+  ]
+}
+```
+
+Use the first form only when the query/entity schema exposes an `Order` entity-reference property. Use the second form only when it exposes an `OrderGuid` scalar property. Do not send `@{mock}` to a scalar GUID property.
+
+```json
+{
+  "chillType": "Model.Order",
+  "chillQuery": "Query.OrderQuery",
+  "relations": [
+    {
+      "chillType": "Model.OrderRow",
+      "chillQuery": "Query.OrderRowQuery",
+      "relationLabel": {
+        "labelGuid": "ORDER-ROWS-LABEL",
+        "primaryDefaultText": "Rows",
+        "secondaryDefaultText": "Righe"
+      },
+      "fixedQueryValues": { "Order": "@{mock}" },
+      "defaultQueryValues": { "Order": "@{mock}" },
+      "defaultValues": { "Order": "@{mock}" },
+      "fixedValues": { "Order": "@{mock}" }
+    }
+  ]
+}
+```
+
+Use `fixedQueryValues` for an unchangeable parent filter and `defaultQueryValues` for an initial editable filter. Use `fixedValues` for a read-only create value and `defaultValues` for an editable create default. Relations can contain further `relations` arrays.
+
+## Persisting the menu entry
+
+The menu API stores the JSON as a string. For example, use `ComponentName: "CRUD"` and serialize the object into `ComponentConfigurationJson` when calling `set-menu`. Invalid JSON, or a JSON array instead of an object, cannot configure the task.

package/doc/UiCore/README.md

@@ -0,0 +1,13 @@
+# ChillSharp UI Core
+
+Versione italiana: [Italiano](../it/UiCore/README.md)
+
+`@chill-sharp/ui-core` is the shared Angular workspace UI for ChillSharp applications. It supplies the workspace shell, authenticated navigation, schema-driven forms and tables, CRUD tasks, permissions screens, and the menu-task registry. Application repositories keep their tenant branding, routes, runtime configuration, and client-owned extensions outside this package.
+
+The package reads schema and menu metadata from the ChillSharp API. The server controls entity metadata and persisted menu entries; the UI Core renders the standard experience from that metadata. Use configuration JSON to tailor an individual menu task without copying shared UI code.
+
+## Guides
+
+- [CRUD menu configuration](./CRUD.md): configure a `CRUD` menu item and its JSON options.
+- [Menu guide](../MenuGuide/README.md): persisted menu items and `MenuHierarchy` visibility.
+- [Relation configuration](../MenuGuide/Relations.md): schema relations that UI Core can turn into nested CRUD tasks.

package/doc/ValidationModel/README.md

@@ -0,0 +1,117 @@
+# Validation Model
+
+Versione italiana: [Italiano](../it/ValidationModel/README.md)
+
+
+ChillSharp supports the standard ASP.NET Core / .NET validation attributes on entity and query properties, as long as those properties are also marked with `[ChillProperty]`.
+
+## Standard validation on Chill properties
+
+Decorate your `ChillEntity` or `ChillQuery` properties with both `[ChillProperty]` and the usual DataAnnotations attributes such as `[Required]`, `[StringLength]`, `[Range]`, `[EmailAddress]`, and so on.
+
+```csharp
+using ChillSharp.Annotations;
+using ChillSharp.EF;
+using System.ComponentModel.DataAnnotations;
+
+public class Customer : ChillEntity
+{
+    [Key]
+    public override Guid Guid { get; set; }
+
+    [ChillProperty(
+        UniquePropertyKeyString: "2F262D7E-F676-4857-B41D-D31C766AA38F",
+        PrimaryLanguageLabel: "Name",
+        SecondaryLanguageLabel: "Nome")]
+    [Required(ErrorMessage = "Customer name is required.")]
+    [StringLength(80, ErrorMessage = "Customer name must be 80 characters or less.")]
+    public string Name { get; set; } = string.Empty;
+}
+```
+
+At runtime ChillSharp validates only the properties decorated with `[ChillProperty]`.
+
+If a property has DataAnnotations attributes but is not a Chill property, ChillSharp ignores it in the Chill validation pipeline.
+
+## Combining DataAnnotations with `OnValidation()`
+
+You can still add custom ChillSharp validation by overriding `OnValidation()`.
+
+```csharp
+public override IEnumerable<ChillValidationError> OnValidation(IChillContext context)
+{
+    if (Name == "admin")
+    {
+        return
+        [
+            new ChillValidationError
+            {
+                FieldName = nameof(Name),
+                Message = "The name 'admin' is reserved."
+            }
+        ];
+    }
+
+    return [];
+}
+```
+
+Runtime behavior is:
+
+1. ChillSharp runs standard DataAnnotations validation on `[ChillProperty]` members.
+2. ChillSharp then runs your custom `OnValidation()` logic.
+3. The returned errors are exposed as `ChillValidationError` using the human-readable DataAnnotations `ErrorMessage`.
+
+## Update behavior
+
+The same validation pipeline also runs automatically at the beginning of the internal post-update runtime hook used by ChillSharp.
+
+This means:
+
+- If the client calls validation explicitly, it receives `ChillValidationError` entries for annotation-based and custom validation errors.
+- If the client skips explicit validation and goes directly to create or update, ChillSharp still validates the entity during the update lifecycle and throws a `ChillValidationException` with the same human-readable messages.
+
+## Notes
+
+- Use standard DataAnnotations for simple field rules.
+- Use `OnValidation()` for rules that depend on multiple fields, business logic, or database lookups.
+- To make a property part of ChillSharp validation, always add `[ChillProperty]`.
+
+## Appendix: GUID-based validation messages
+
+As an optional flexibility hack, a DataAnnotations `ErrorMessage` can contain a GUID string instead of final user text.
+
+Then you can provide the actual primary and secondary texts by overriding `GetValidationMessageDefinitions()`.
+
+```csharp
+public class Customer : ChillEntity
+{
+    [ChillProperty(
+        UniquePropertyKeyString: "B2AB35A8-6A89-4D39-8F1D-183F686811A9",
+        PrimaryLanguageLabel: "Code",
+        SecondaryLanguageLabel: "Codice")]
+    [Required(ErrorMessage = "4F880CC1-5C7A-4E23-982A-5F0C490B44DE")]
+    public string Code { get; set; } = string.Empty;
+
+    public override IEnumerable<ChillValidationMessageDefinition> GetValidationMessageDefinitions(IChillContext context)
+    {
+        return
+        [
+            new ChillValidationMessageDefinition
+            {
+                MessageGuid = Guid.Parse("4F880CC1-5C7A-4E23-982A-5F0C490B44DE"),
+                PrimaryLanguageMessage = "Code is required.",
+                SecondaryLanguageMessage = "Il codice e obbligatorio."
+            }
+        ];
+    }
+}
+```
+
+When ChillSharp sees that GUID in `ErrorMessage`, it resolves the final message through the same primary/secondary language convention used elsewhere in ChillSharp metadata.
+
+Notes:
+
+- This is optional. Plain human-readable `ErrorMessage` values still work normally.
+- Use this only when you want a stable identifier for a validation text.
+- If the GUID is not found in `GetValidationMessageDefinitions()`, ChillSharp falls back to the raw `ErrorMessage` string.

package/doc/it/AIAssistedDevelopment/README.md

@@ -0,0 +1,185 @@
+# Guida allo sviluppo assistito dall'intelligenza artificiale
+
+Versione originale in inglese: [English](../../AIAssistedDevelopment/README.md)
+
+
+Questo documento spiega come ChillSharp può aiutarti quando crei software con l'assistenza dell'intelligenza artificiale e desideri comunque che la base di codice rimanga strutturata, stabile e rivedibile.
+
+L’idea chiave è semplice: gli strumenti di intelligenza artificiale sono molto più affidabili quando funzionano all’interno di un’architettura vincolata, ripetitiva e ben definita rispetto a quando viene chiesto loro di mantenere manualmente sincronizzati molti controller, DTO, endpoint e percorsi di convalida.
+
+ChillSharp non corregge automaticamente il codice generato dall'intelligenza artificiale. Ciò che fa è ridurre la quantità di superficie che l’intelligenza artificiale deve generare e mantenere.
+
+## Perché è importante
+
+Una modalità di errore comune nello sviluppo backend assistito dall'intelligenza artificiale è che il modello tocca troppe parti mobili contemporaneamente:
+
+- controllori
+- Mappature DTO
+- contratti di richiesta/risposta
+- logica di validazione
+- controlli autorizzativi
+- comportamenti CRUD duplicati
+
+Maggiore è il numero di file ed endpoint personalizzati di cui disponi, più facile sarà per l'intelligenza artificiale introdurre derive accidentali dell'interfaccia, comportamenti incoerenti o refactoring ampi che non erano mai stati previsti.
+
+ChillSharp riduce tale rischio spostando gran parte della superficie backend in un runtime uniforme basato su modello.
+
+## In che modo ChillSharp aiuta
+
+### 1. La logica aziendale cresce all'interno di un ambiente strutturato
+
+Con ChillSharp, i principali punti di estensione sono espliciti e prevedibili:
+
+- 
+- 
+- 
+- Hook del ciclo di vita come `OnCreate()`, `OnUpdate()`, `OnAfterUpdate()`, `OnDelete()` e `OnSelect()`
+- metadati tramite `[ChillProperty]` e relative annotazioni
+
+Ciò offre all’intelligenza artificiale uno spazio più ristretto e strutturato per apportare modifiche.
+
+Invece di chiedere a un modello di intelligenza artificiale di inventare ancora un altro controller, richiedere DTO, risposta DTO, mappatore, validatore e contratto di instradamento, spesso puoi chiedergli di:
+
+- aggiungi una proprietà
+- aggiungere la convalida
+- aggiungi un filtro di query
+- aggiungere la logica del ciclo di vita
+- modificare le regole di autorizzazione
+
+Questo di solito produce modifiche più piccole e più sicure.
+
+### 2. Riduzione del rischio di refactoring accidentale degli endpoint
+
+ChillSharp espone una superficie API standard tramite `app.MapChillApi()`, con operazioni stabili come:
+
+- 
+- 
+- 
+- 
+- 
+- 
+
+Poiché la superficie di trasporto è centralizzata, l’aggiunta o l’evoluzione delle entità aziendali non richiede che l’intelligenza artificiale continui a riscrivere un insieme crescente di controller per entità e definizioni di percorso.
+
+Ciò riduce un rischio specifico dell’IA:
+
+- modifica accidentale dei nomi degli endpoint
+- modifica delle forme del carico utile in modo incoerente
+- implementare un endpoint in modo diverso dagli altri
+- interrompere i client attraverso refactoring API non necessari
+
+L'interfaccia continua ad evolversi insieme al modello, ma il CRUD e i meccanismi di query non devono essere riprodotti ogni volta.
+
+### 3. Gli endpoint crescono in modo uniforme
+
+In un backend tradizionale scritto a mano, ogni nuova entità tende a creare codice API più duplicato. Nel tempo si accumulano piccole differenze:
+
+- Un controller convalida in modo diverso
+- un altro controller restituisce payload leggermente diversi
+- Un altro endpoint dimentica un controllo di autorizzazione
+- Un altro mappatore DTO omette un campo
+
+Gli strumenti di intelligenza artificiale amplificano questo problema perché continuano il modello locale che vedono, anche quando il modello locale è già incoerente.
+
+ChillSharp spinge il sistema nella direzione opposta: entità e query si collegano allo stesso modello di runtime, quindi la crescita è più uniforme per impostazione predefinita.
+
+Questa uniformità aiuta entrambi:
+
+- manutentori umani che esaminano i cambiamenti prodotti dall'intelligenza artificiale
+- Strumenti di intelligenza artificiale che ragionano sulla base di codice con meno ambiguità
+
+### 4. Carico utile del programma ridotto per gli strumenti di intelligenza artificiale
+
+Quando un progetto si basa su molti controller CRUD personalizzati, classi DTO, livelli di mappatura e definizioni di endpoint ripetitive, l'intelligenza artificiale ha bisogno di più contesto di repository per apportare una modifica sicura.
+
+Ciò aumenta:
+
+- utilizzo dei gettoni
+- latenza
+- costo
+- la possibilità che il modello manchi uno dei livelli duplicati
+
+ChillSharp riduce questo onere poiché gran parte della logica di trasporto ripetitiva è già gestita dal runtime del framework.
+
+In pratica ciò significa che un compito dell’intelligenza artificiale può spesso essere risolto leggendo e modificando:
+
+- un'entità
+- una domanda
+- una regola di convalida
+- una definizione di autorizzazione
+
+invece di una lunga catena di file correlati.
+
+### 5. Abbassare la pressione per il refactoring continuo su larga scala
+
+Senza una struttura basata su modelli, i team spesso chiedono all'IA di continuare a eseguire il refactoring di un elenco crescente di:
+
+- endpoint
+- controllori
+- DTO
+- validatori
+- mappatori
+- controlli dei permessi
+
+Questo è costoso e fragile. Incoraggia inoltre ampie riscritture automatizzate che potrebbero non fornire valore aziendale.
+
+ChillSharp riduce la necessità di questo stile di manutenzione perché la superficie CRUD/query generica è già centralizzata.
+
+Ciò ha vantaggi pratici:
+
+- minor consumo di token AI
+- Meno refactoring ampi su file ripetitivi
+- minore sforzo di revisione per il codice generato
+- minore utilizzo del calcolo per la stessa funzionalità
+
+Se ti interessano sia l'efficienza ingegneristica che l'efficienza energetica, questo è uno degli argomenti più forti per l'utilizzo di un runtime uniforme invece di una grande quantità di standard endpoint ripetuti.
+
+## In cosa è bravo ChillSharp nei flussi di lavoro AI
+
+ChillSharp è una buona soluzione quando vuoi che l'intelligenza artificiale ti aiuti con:
+
+- estensione delle entità di dominio
+- aggiunta di regole di convalida
+- aggiunta di funzionalità di query
+- esposizione delle modifiche al modello attraverso una superficie API generica esistente
+- mantenere autorizzazioni e metadati più vicini al modello
+
+Questo di solito è una soluzione migliore rispetto a chiedere all’IA di generare ripetutamente grandi set di codice dell’infrastruttura CRUD.
+
+## Cosa ChillSharp non risolve
+
+ChillSharp non elimina la necessità di revisione tecnica. In particolare è necessario ancora verificare:
+
+- Le regole aziendali sono corrette
+- le regole di autorizzazione sono corrette
+- le proprietà esposte sono intenzionali
+- I cambiamenti di modello non distruggono i consumatori
+- La logica del ciclo di vita generata dall'intelligenza artificiale è effettivamente sicura
+
+ChillSharp riduce la duplicazione e la deriva. Non elimina la necessità del giudizio.
+
+## Posizionamento consigliato
+
+Se desideri un modo breve e difendibile per descriverlo nella documentazione o nelle note sull'architettura, usa qualcosa come:
+
+"ChillSharp aiuta lo sviluppo assistito dall'intelligenza artificiale centralizzando i meccanismi API ripetitivi in ​​un runtime basato su modello. Ciò riduce la deviazione accidentale dell'interfaccia, mantiene il comportamento degli endpoint più uniforme e riduce la quantità di codice e contesto del repository che gli strumenti di intelligenza artificiale devono generare e mantenere."
+
+## Lista di controllo pratica
+
+Se desideri utilizzare ChillSharp come architettura backend compatibile con l'intelligenza artificiale, la linea di base è:
+
+1. mantenere le entità aziendali e le query come il luogo principale in cui viene definito il comportamento delle funzionalità
+2. utilizzare `[ChillProperty]` in modo coerente in modo che il DTO e la superficie di convalida rimangano intenzionali
+3. preferire `OnValidation()` e gli hook del ciclo di vita rispetto alla logica del controller ad hoc
+4. evitare di reintrodurre endpoint CRUD personalizzati ripetitivi a meno che non ce ne sia una reale necessità
+5. esaminare attentamente le modifiche al modello poiché una superficie basata su modello può influire su più operazioni client contemporaneamente
+6. mantenere le autorizzazioni e l'autenticazione allineate con lo stesso approccio basato sul modello
+
+## Documenti correlati
+
+- [../README.md](../README.md)
+- [../RegisterContext.md](../RegisterContext.md)
+- [../ValidationModel/README.md](../ValidationModel/README.md)
+- [../PermissionModel/README.md](../PermissionModel/README.md)
+- [../AuthenticationModel/README.md](../AuthenticationModel/README.md)
+- [../ClientGeneration/README.md](../ClientGeneration/README.md)

package/doc/it/AttachmentModel/README.md

@@ -0,0 +1,173 @@
+# Modulo allegati
+
+Versione originale in inglese: [English](../../AttachmentModel/README.md)
+
+
+`ChillSharp.Attachment` aggiunge un'entità di allegato incorporata oltre a endpoint di caricamento e download supportati da un archivio di file system.
+
+## Cosa aggiunge
+
+- L'entità `Attachment` è persistita nella tabella `attachment`
+- supporto generico Chill CRUD per i metadati degli allegati
+- 
+- 
+
+Poiché `Attachment` è un vero `ChillEntity`, viene esposto anche tramite il rilevamento dello schema e può essere gestito tramite gli endpoint Chill CRUD standard una volta che l'host `DbContext` implementa `IChillAttachmentDbContext`.
+
+Il modulo espone anche un tipo di query `AttachmentQuery` Chill, che gli helper client possono utilizzare per elencare gli allegati collegati a un'entità di destinazione.
+
+## Registra il modulo
+
+Aggiungi il modello del modulo al tuo contesto ed esponi `DbSet`:
+
+```csharp
+using ChillSharp.Attachment;
+using ChillSharp.Attachment.Model;
+
+public class AppDbContext : DbContext, IChillContext, IChillAttachmentDbContext
+{
+    public DbSet<Attachment> Attachments => Set<Attachment>();
+
+    protected override void OnModelCreating(ModelBuilder modelBuilder)
+    {
+        base.OnModelCreating(modelBuilder);
+        modelBuilder.AddChillAttachmentModel();
+    }
+
+    public string GetChillTypePrefix() => "MyApp.Data";
+}
+```
+
+Quando il contesto implementa `IChillAttachmentDbContext`, `services.AddChillApi<AppDbContext>()` registra automaticamente gli endpoint dell'allegato.
+
+## Configurazione della radice dell'archivio
+
+Il modulo legge la radice dell'archivio da:
+
+- opzioni di avvio tramite `services.Configure<ChillAttachmentOptions>(...)`
+- variabile d'ambiente `CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT`
+
+Esempio:
+
+```csharp
+builder.Services.Configure<ChillAttachmentOptions>(options =>
+{
+    options.ArchiveRoot = "/srv/chill/attachments";
+});
+```
+
+O attraverso l'ambiente:
+
+```env
+CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT=/srv/chill/attachments
+```
+
+## Disposizione dell'archivio
+
+I file vengono archiviati nella root dell'archivio configurata utilizzando:
+
+```csharp
+public static string BuildAttachmentPath(
+    string archiveRoot,
+    string attachToChillType,
+    Guid id,
+    string extension,
+    DateTime createdAtUtc)
+```
+
+La disposizione risultante è:
+
+```text
+{archiveRoot}/{attachToChillType}/{year}/{guid[0..2]}/{guid[2..4]}/{guid}{extension}
+```
+
+Esempio:
+
+```text
+/srv/chill/attachments/Post/2026/ab/cd/abcd1234....pdf
+```
+
+## Carica endpoint
+
+
+
+Campi modulo multiparte:
+
+- 
+- 
+- 
+- 
+- 
+- una o più parti `file`
+
+Per ogni file caricato il modulo:
+
+1. crea un'entità Chill `Attachment` tramite `ChillEngine`
+2. memorizza il file fisico nell'archivio
+3. restituisce il payload DTO dell'allegato creato
+
+## Scarica l'endpoint
+
+
+
+Comportamento:
+
+- carica l'entità `Attachment` dal database
+- risolve il percorso del file archiviato
+- restituisce il file utilizzando il nome file originale memorizzato e il tipo MIME
+- consente il download anonimo quando `Public == true`
+- richiede un utente autenticato quando `Public == false`
+
+## Aiutanti del cliente
+
+### `.NET`
+
+`ChillSharp.Client` ora include gli aiutanti per gli allegati:
+
+```csharp
+var post = new ChillDtoEntity
+{
+    Guid = postGuid,
+    ChillType = "Model.Post"
+};
+
+var uploaded = await client.UploadAttachmentAsync(
+    post,
+    File.ReadAllBytes("contract.pdf"),
+    "contract.pdf",
+    "application/pdf",
+    title: "Signed contract",
+    description: "Customer-facing version",
+    isPublic: false);
+
+var attachments = await client.GetAttachmentsAsync(post);
+var fileBytes = await client.DownloadAttachmentAsync(uploaded[0]);
+```
+
+I sovraccarichi disponibili coprono:
+
+- caricare dal percorso del file
+- caricamento da `byte[]`
+- caricamento da `Stream`
+- scaricabile tramite allegato `Guid`
+- scaricabile tramite allegato `ChillDtoEntity`
+
+### TypeScript / Angular / React / Vue / Python
+
+Le librerie client generiche in `extra-libs/` espongono gli helper corrispondenti:
+
+- TypeScript: `uploadAttachment()`, `uploadAttachments()`, `getAttachments()`, `downloadAttachment()`
+- Angolare: stessi helper tramite `ChillSharpNgClient` dei wrapper `Observable`
+- React e Vue: stessi helper tramite il client raw restituito da `useChillSharpClient()`
+- Python: `upload_attachment()`, `upload_attachments()`, `get_attachments()`, `download_attachment()`
+
+##CRUD generico
+
+I metadati degli allegati rimangono disponibili tramite gli endpoint Chill standard:
+
+- 
+- 
+- 
+- 
+
+L'eliminazione di un allegato tramite ChillSharp rimuove anche il file archiviato dal disco.