@chill-sharp/chill-cli 1.1.16

package/README.md

@@ -0,0 +1,21 @@
+# Chill CLI
+
+Create a ChillSharp workspace that is ready for your preferred coding agent.
+
+```bash
+npm install -g @chill-sharp/chill-cli
+chill new my-data-project
+cd my-data-project
+```
+
+`chill new` creates the project directory and installs the maintained ChillSharp agent skills in `.agents/skills`. It also adds `AGENTS.md` with instructions that agent tools can follow while developing the project.
+
+The command uses only Node.js standard-library APIs, so it works on Linux, macOS, and Windows with Node.js 20 or later.
+
+## Command
+
+```text
+chill new <project-name>
+```
+
+Project names use lowercase letters, digits, and hyphens. The command refuses to overwrite an existing directory.

package/bin/chill.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const packageManifest = JSON.parse(readFileSync(path.join(packageDirectory, 'package.json'), 'utf8'));
+const [command, projectName] = process.argv.slice(2);
+
+if (command === 'new') {
+  createProject(projectName);
+} else if (command === '--help' || command === '-h' || command === 'help' || !command) {
+  printUsage();
+  process.exit(command ? 0 : 1);
+} else if (command === '--version' || command === '-v') {
+  console.log(packageManifest.version);
+} else {
+  console.error(`Unknown command: ${command}`);
+  printUsage();
+  process.exit(1);
+}
+
+function createProject(name) {
+  if (!name) {
+    console.error('A project name is required.');
+    printUsage();
+    process.exit(1);
+  }
+
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+    console.error('Project names must use lowercase letters, digits, and hyphens only.');
+    process.exit(1);
+  }
+
+  const destination = path.resolve(process.cwd(), name);
+  if (existsSync(destination)) {
+    console.error(`Cannot create '${name}': '${destination}' already exists.`);
+    process.exit(1);
+  }
+
+  mkdirSync(destination);
+  cpSync(path.join(packageDirectory, 'skills'), path.join(destination, '.agents', 'skills'), { recursive: true });
+  writeFileSync(path.join(destination, 'AGENTS.md'), projectInstructions(name));
+  writeFileSync(path.join(destination, 'README.md'), projectReadme(name));
+  writeFileSync(path.join(destination, '.gitignore'), '.DS_Store\nThumbs.db\n.env\n');
+
+  console.log(`Created ${name}.`);
+  console.log('Agent skills were added to .agents/skills.');
+  console.log('Next steps:');
+  console.log(`  cd ${name}`);
+  console.log('  Open this folder in your coding agent and describe the first useful outcome.');
+}
+
+function projectInstructions(name) {
+  return `# ${name}\n\nThis project is prepared for ChillSharp development with a coding agent.\n\nBefore changing ChillSharp code, inspect the relevant skill in \`.agents/skills\`. Use the project\'s existing conventions and keep implementation work focused on the requested outcome.\n\nFor a new ChillSharp backend, start by describing the users, data, and first workflow. The agent can then use the included model, registration, permissions, i18n, menu, plugin, and MCP guidance as needed.\n`;
+}
+
+function projectReadme(name) {
+  return `# ${name}\n\nA ChillSharp project workspace prepared for coding agents.\n\n## Start building\n\nOpen this folder with your coding agent and describe the first outcome you want to deliver. The agent guidance lives in [\`.agents/skills\`](.agents/skills).\n\nFor example:\n\n> Build a service directory for our nonprofit. Visitors should be able to find local support services, while staff can securely manage the underlying data.\n\n## Included guidance\n\nThe workspace contains ChillSharp skills for model preparation, registration, permissions, localized text, menus, client plugins, current-user preferences, documentation, and MCP.\n`;
+}
+
+function printUsage() {
+  console.log('Usage: chill new <project-name>');
+  console.log('');
+  console.log('Commands:');
+  console.log('  new <project-name>  Create an agent-ready ChillSharp workspace.');
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@chill-sharp/chill-cli",
+  "version": "1.1.16",
+  "description": "Start a ChillSharp project with agent-ready guidance.",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "bin": {
+    "chill": "./bin/chill.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/sync-skills.mjs && node --check bin/chill.mjs",
+    "check": "node --check bin/chill.mjs",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "chillsharp",
+    "cli",
+    "coding-agent",
+    "starter"
+  ],
+  "author": "Andrea Piovesan",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/e-500/chill-sharp.git",
+    "directory": "extra/chill-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/e-500/chill-sharp/issues"
+  },
+  "homepage": "https://github.com/e-500/chill-sharp#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/chillsharp-current-user-preferences/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: chillsharp-current-user-preferences
+description: Configure, expose, and consume ChillSharp.Auth's cached current-user culture, time zone, date-format, number-format, and theme preferences in server logic and UI clients.
+---
+
+# ChillSharp Current User Preferences
+
+Use this skill when a ChillSharp feature needs the authenticated user's display culture, time zone, date format, number format, or preferred theme. It covers server-side lifecycle hooks and UI/client consumption of the authoritative `AuthUser` preferences. Do not use it for browser-only preferences unrelated to `AuthUser`.
+
+## Model
+
+`ChillUserPreferences` is an immutable snapshot with `DisplayCultureName`, `DisplayTimeZone`, `DisplayDateFormat`, `DisplayNumberFormat`, and `PreferredTheme`. Entity hooks read it synchronously through:
+
+```csharp
+var preferences = context.GetCurrentUserPreferences();
+```
+
+Never load `AuthUser` from an `OnCreate`, `OnUpdate`, or other lifecycle hook merely to obtain these values.
+
+## Auth integration
+
+`AddChillAuthApi` registers `IChillAuthUserPreferencesAccessor` and the singleton `IChillAuthUserPreferencesCache`. Login and token refresh warm the snapshot; `ChillAuthService` refreshes it after an `AuthUser` save and removes it for deleted or renamed external identities.
+
+For a custom host DbContext, inject the scoped accessor and implement the two `IChillContext` methods below. Keep the accessor optional only when the context must also be constructible outside DI, such as for migrations or tests.
+
+```csharp
+private readonly IChillAuthUserPreferencesAccessor? _userPreferencesAccessor;
+
+public ChillUserPreferences GetCurrentUserPreferences() =>
+    _userPreferencesAccessor?.Current ?? ChillUserPreferences.Empty;
+
+public string GetDefaultUserCultureName()
+{
+    var cultureName = GetCurrentUserPreferences().DisplayCultureName;
+    return string.IsNullOrWhiteSpace(cultureName) ? GetPrimaryCultureName() : cultureName;
+}
+```
+
+The accessor is cache-only: when there is no authenticated principal or no warmed snapshot, it returns `ChillUserPreferences.Empty`. Do not add a fallback database query to lifecycle hooks.
+
+## API and client use
+
+The authenticated endpoint `GET /api/chill-auth/current-user-preferences` returns the same `ChillUserPreferences` snapshot as JSON:
+
+```json
+{
+  "displayCultureName": "it-IT",
+  "displayTimeZone": "Europe/Rome",
+  "displayDateFormat": "dd/MM/yyyy",
+  "displayNumberFormat": "N2",
+  "preferredTheme": "cini"
+}
+```
+
+Use this endpoint after authentication and when restoring a session; do not infer the active display culture or time zone from the browser, operating system, token claims, or auth-management user endpoints. The C#, Python, TypeScript, Angular, Vue, and React clients expose it as `GetCurrentUserPreferences`, `get_current_user_preferences`, or `getCurrentUserPreferences`; the Vue and React packages also provide `useCurrentUserPreferences`.
+
+In Angular UI Core, inject `ChillService` and read its `userPreferences` signal (or its `displayCultureName`, `displayTimeZone`, `displayDateFormat`, `displayNumberFormat`, and `preferredTheme` projections). Use these values to select UI language, format and parse dates and numbers, convert UTC timestamps, and select the client theme. The backend treats `PreferredTheme` as an opaque string. UI Core defaults unauthenticated users to browser `prefers-color-scheme` light/dark and clients register extra selectable themes with `provideChillSharpUiCore({ additionalThemes: ['theme-name'] })`.
+
+## Entity use
+
+Use `DisplayTimeZone` as an IANA zone identifier only after validating it with the application's time-zone policy. Treat all fields as optional and provide an explicit fallback where one is required.
+
+```csharp
+public override void OnUpdate(IChillContext context)
+{
+    var timeZone = context.GetCurrentUserPreferences().DisplayTimeZone;
+    // Apply application-specific behavior only when timeZone is available.
+}
+```
+
+For full setup and cache behavior, read [CurrentUserPreferences.md](../../../doc/CurrentUserPreferences.md).

package/skills/chillsharp-documentation/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: chillsharp-documentation
+description: Create or update ChillSharp repository documentation under doc with a mirrored Italian translation and reciprocal language switchers.
+---
+
+# ChillSharp Documentation
+
+Use this skill for every Markdown change below `doc/`, including new guides and translated documentation.
+
+## Localization contract
+
+- The English source lives at `doc/<relative-path>.md`.
+- Create and maintain its Italian translation at `doc/it/<relative-path>.md`; preserve the same relative directory and filename.
+- Each document must start with its title and then a reciprocal language switcher within the opening section:
+  - English: `Versione italiana: [Italiano](<relative link to doc/it/...>)`
+  - Italian: `English version: [English](<relative link to doc/...>)`
+- Translate prose, headings, image alt text, and link text for the Italian version. Keep code, commands, identifiers, file paths, URLs, and literal API payload fields unchanged unless their surrounding explanatory prose requires a translation.
+- When an English document changes, apply the equivalent semantic change to its Italian counterpart in the same task. Do not leave a placeholder, an English duplicate, or a stale translation.
+
+## Workflow
+
+1. For a new document, create the English document and its Italian counterpart together.
+2. Keep internal links valid from both mirrored locations; use relative Markdown links.
+3. Run `python .agents/skills/chillsharp-documentation/scripts/check_localized_docs.py doc` before handing off documentation changes. Resolve every reported issue.
+
+The checker verifies structure and switchers. Review the translation itself for meaning, terminology, and code fidelity.

package/skills/chillsharp-documentation/scripts/check_localized_docs.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Validate the mirrored English/Italian Markdown documentation layout."""
+
+from __future__ import annotations
+
+import sys
+import re
+from pathlib import Path
+
+
+def has_switcher(path: Path, label: str, target: Path) -> bool:
+    lines = path.read_text(encoding="utf-8").splitlines()
+    pattern = re.compile(rf"\[{re.escape(label)}\]\(([^)]+)\)")
+    for line in lines[:12]:
+        match = pattern.search(line)
+        if match and (path.parent / match.group(1)).resolve() == target.resolve():
+            return True
+    return False
+
+
+def main() -> int:
+    if len(sys.argv) != 2:
+        print("Usage: check_localized_docs.py <doc-root>", file=sys.stderr)
+        return 2
+
+    doc_root = Path(sys.argv[1]).resolve()
+    italian_root = doc_root / "it"
+    if not doc_root.is_dir():
+        print(f"Documentation root does not exist: {doc_root}", file=sys.stderr)
+        return 2
+
+    issues: list[str] = []
+    english_documents = sorted(
+        path for path in doc_root.rglob("*.md") if italian_root not in path.parents
+    )
+
+    for english_path in english_documents:
+        relative_path = english_path.relative_to(doc_root)
+        italian_path = italian_root / relative_path
+        if not italian_path.is_file():
+            issues.append(f"Missing Italian translation: it/{relative_path.as_posix()}")
+            continue
+
+        if not has_switcher(english_path, "Italiano", italian_path):
+            issues.append(f"Missing or invalid English switcher: {relative_path.as_posix()}")
+
+        if not has_switcher(italian_path, "English", english_path):
+            issues.append(f"Missing or invalid Italian switcher: it/{relative_path.as_posix()}")
+
+    if italian_root.is_dir():
+        for italian_path in sorted(italian_root.rglob("*.md")):
+            relative_path = italian_path.relative_to(italian_root)
+            if not (doc_root / relative_path).is_file():
+                issues.append(f"Italian document has no English source: it/{relative_path.as_posix()}")
+
+    if issues:
+        print("Documentation localization check failed:")
+        for issue in issues:
+            print(f"- {issue}")
+        return 1
+
+    print(f"Documentation localization check passed for {len(english_documents)} document(s).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/chillsharp-i18n/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: chillsharp-i18n
+description: Configure ChillSharp localized text storage, culture-aware schema labels, and i18n client lookups.
+---
+
+# ChillSharp Internationalization
+
+Use this skill when a host needs persisted localized text or culture-aware schema metadata.
+
+The host `DbContext` must implement `IChillI18nDbContext` and call `modelBuilder.AddChillI18nModel()` from `OnModelCreating`. Register the API with `builder.Services.AddChillI18nApi<TContext>()`; the standard endpoints are `GET /api/chill-i18n/text/{labelGuid}/{cultureName}` and `PUT /api/chill-i18n/text`.
+
+Keep primary and secondary culture names on `IChillContext`. `PrimaryLanguageLabel` and `SecondaryLanguageLabel` are schema fallbacks, not a replacement for persisted localized text. Test primary, secondary, and unsupported cultures after creating the EF migration.

package/skills/chillsharp-menu-json/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: chillsharp-menu-json
+description: Configure or repair ChillSharp workspace menu JSON for CRUD tasks, especially ChillType and ChillQuery values.
+---
+
+# ChillSharp Menu JSON Configuration
+
+Use this skill when creating or correcting a persisted workspace menu item whose `ComponentName` is `crud` and whose `ComponentConfigurationJson` selects a ChillSharp entity and query.
+
+## Resolve logical ChillTypes from C# namespaces
+
+`chillType` and `chillQuery` are logical ChillTypes, not filesystem paths. Derive each value from the declaring C# namespace after removing the application's `IChillContext.GetChillTypePrefix()`.
+
+For example, with a prefix of `MyApp` and these declarations:
+
+```csharp
+namespace MyApp.Model;
+public class Item : ChillEntity { }
+public class ItemQuery : ChillQuery { }
+```
+
+use `Model.Item` and `Model.ItemQuery`—not `Query.ItemQuery`, even if `ItemQuery.cs` resides in a `Model/Query` folder.
+
+## CRUD configuration
+
+Keep the entity and query aligned, retain any intentional relations, and use valid JSON:
+
+```json
+{
+  "chillType": "Model.Item",
+  "viewCode": "default",
+  "chillQuery": "Model.ItemQuery",
+  "relations": []
+}
+```
+
+When repairing an existing menu item, change only the incorrect logical type unless the user requests other configuration changes. Save the menu entry, reopen the task, and confirm that the type-resolution error is gone.

package/skills/chillsharp-plugin-development/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: chillsharp-plugin-development
+description: Develop client-owned ChillSharp UI plugins and overrides while keeping shared UI behavior upgradeable.
+---
+
+# ChillSharp UI Plugin Development
+
+Use this skill for Angular client features that extend a ChillSharp UI client. Keep application-owned code in the client repository and shared behavior in `@chill-sharp/ui-core`.
+
+- Add feature routes/components under `src/app/core/plugins` and register routes from `register-client-plugins.ts`.
+- Add provider replacements under `src/app/core/overrides` and return them from `register-client-overrides.ts`.
+- Aggregate client providers through `provideClientTemplateProviders()` in the app bootstrap.
+- Use public package exports; do not deep-import or patch shared package internals.
+
+Keep runtime API URLs, tenant settings, branding, and feature flags in client configuration. Test a clean build after registration changes.

package/skills/chillsharp_i18n/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: chillsharp_i18n
+description: Configure ChillSharp localized text storage, culture-aware schema labels, and i18n client lookups.
+---
+
+# ChillSharp Internationalization
+
+Use this skill when a host needs persisted localized text or culture-aware schema metadata.
+
+## Backend setup
+
+The host `DbContext` must implement `IChillI18nDbContext` and call `modelBuilder.AddChillI18nModel()` from `OnModelCreating`. Register the API with `builder.Services.AddChillI18nApi<TContext>()`; the standard endpoints are `GET /api/chill-i18n/text/{labelGuid}/{cultureName}` and `PUT /api/chill-i18n/text`.
+
+Keep primary and secondary culture names on `IChillContext`. `PrimaryLanguageLabel` and `SecondaryLanguageLabel` are schema fallbacks; they are not a replacement for persisted localized text.
+
+## Client behavior
+
+Use the generated or `ChillSharp.Client` i18n contract to request the desired culture explicitly. Treat a missing translation as a normal fallback case and keep the fallback order consistent with the host context.
+
+## Checks
+
+- Verify the context interface, EF model extension, service registration, and migration are all present.
+- Do not put secrets or tenant-specific state in static localization caches.
+- Test both primary and secondary cultures, plus an unsupported culture fallback.

package/skills/chillsharp_mcp/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: chillsharp_mcp
+description: Guidance on configuring, enabling, and designing models for ChillSharp Model Context Protocol (MCP) servers.
+---
+
+# ChillSharp MCP Integration
+
+This skill guides you on setting up the Model Context Protocol (`ChillSharp.Mcp`) module, enabling MCP on models, and optimizing database models for AI agent consumption.
+
+## 1. Registration in ASP.NET Core
+
+The MCP module is registered automatically with `AddChillApi()` if `options.EnableMcpApi` is not disabled. 
+
+Alternatively, register it directly in `Program.cs`:
+```csharp
+using ChillSharp.Mcp.Api;
+
+builder.Services.AddChillMcpApi<AppDbContext>(options =>
+{
+    options.Enabled = true;
+    options.RoutePattern = "/api/chill-mcp"; // Default endpoint for MCP clients
+});
+```
+
+Context Requirements:
+- DbContext must implement `IChillContext` and `IChillSchemaDbContext`.
+- Include `modelBuilder.AddChillSchemaModel()` in `OnModelCreating`.
+
+## 2. Exposing Schemas to MCP
+
+To expose an entity or query schema to MCP, set `EnableMCP = true` in `[ChillEntity]`:
+```csharp
+[ChillEntity(
+    UniquePropertyKeyString: "4E16F6C0-6B95-4D67-98BC-9F4D0D63EAF1",
+    PrimaryLanguageLabel: "Invoice",
+    SecondaryLanguageLabel: "Fattura",
+    EnableMCP = true,
+    MCPDescription = "Customer invoice header. Use it to inspect invoice identity, customer, dates, totals, and payment state.")]
+public class Invoice : ChillEntity
+{
+    // ...
+}
+```
+
+A query DTO is visible and executable through MCP only when its target returned entity has `EnableMCP = true`.
+
+## 3. Best Practices for AI/Agent Optimization
+
+- **MCPDescription**: Write detailed descriptions at both the entity and property levels (`MCPDescription` attribute property). Agents rely on this to build correct payloads and query filters.
+- **Explain Filters**: In query property descriptions, explicitly describe search behaviors (e.g. contains-style text search, range boundary, exact match). If unspecified, agents assume exact matches.
+- **Reference Types**: Declare relationships clearly using `ReferenceChillTypeQuery` and descriptions.
+- **Keep Queries Focused**: Prefer specialized query types (e.g., `Query.OpenInvoicesQuery`) rather than general catch-all queries with dozens of optional inputs.
+- **OAuth & Auth**: When using protected APIs, MCP endpoints expect bearer authorization (`Authorization: Bearer <access-token>`). The Identity auth module includes built-in OAuth PKCE flow support for ChatGPT/MCP clients.

package/skills/chillsharp_model_preparation/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: chillsharp_model_preparation
+description: Guidance on preparing and writing EF Core model/entity classes for ChillSharp including attributes, lifecycle hooks, and DbContext setups.
+---
+
+# ChillSharp Model Preparation
+
+This skill guides you on preparing a domain model for ChillSharp, mapping CLR classes to Chill entities, implementing `IChillContext` on the DbContext, using lifecycle hooks, and annotating properties.
+
+## 1. Implement `IChillContext`
+
+The `DbContext` must implement `IChillContext` to declare prefixes, culture fallback preferences, and audit tracking usernames.
+
+```csharp
+public class AppDbContext : DbContext, IChillContext
+{
+    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
+
+    public string GetChillTypePrefix() => "MyCompany.MyProduct.Data";
+    public string GetPrimaryCultureName() => "en-US";
+    public string GetSecondaryCultureName() => "it-IT";
+    public string GetCurrentUserName() => Environment.UserName; // Replace with user principal resolved name if using auth
+}
+```
+
+## 2. ChillEntity Definition & Property Annotation
+
+- Always inherit from `ChillSharp.EF.ChillEntity` for exposed entities.
+- Decorate class with `[ChillEntity]` and assign a stable UUID string for `UniquePropertyKeyString`.
+- Decorate exposed properties with `[ChillProperty]` using a stable UUID string.
+- Override `GetLabel(IChillContext)` to return a user-friendly string (e.g. Title, Name, etc.).
+
+```csharp
+using ChillSharp.Annotations;
+using ChillSharp.EF;
+using System.ComponentModel.DataAnnotations;
+
+[ChillEntity(
+    UniquePropertyKeyString: "4E16F6C0-6B95-4D67-98BC-9F4D0D63EAF1",
+    PrimaryLanguageLabel: "Blog",
+    SecondaryLanguageLabel: "Blog")]
+public class Blog : ChillEntity
+{
+    [Key]
+    public override Guid Guid { get; set; }
+
+    [ChillProperty(
+        UniquePropertyKeyString: "50B1BB6C-D794-41E4-A85C-D4F9D7A6FA7E",
+        PrimaryLanguageLabel: "Blog title",
+        SecondaryLanguageLabel: "Titolo del blog")]
+    public string Title { get; set; } = string.Empty;
+
+    public override string GetLabel(IChillContext context) => Title;
+}
+```
+
+## 3. Lifecycle Hooks
+
+Provide lifecycle hooks inside the entity by overriding virtual methods:
+- `OnCreate(context)`: Called before first save.
+- `OnUpdate(context)`: Called on create and update flows before save.
+- `OnAfterUpdate(context)`: Called after audit fields are updated and saved, safe to override since base is implemented explicitly.
+- `OnDelete(context)`: Called before entity is deleted.
+- `OnAfterDelete(context)`: Called after entity is deleted from DB.
+- `OnSelect(context)`: Called during retrieval.
+- `OnInflate(context)`: Called when rebuilding relation values.
+- `OnAutocomplete(context)`: Override for search suggestion behavior.
+
+## 4. Metadata Schema & Audit Fields
+
+- Audit fields: `Checksum`, `LastUpdateUser`, `LastUpdate`, `LastUpdateUtcOffset` are managed automatically.
+- Ensure context implements additional DB interfaces like `IChillSchemaDbContext`, `IChillAuthDbContext`, or `IChillI18nDbContext` and registers them via `modelBuilder.AddChillSchemaModel()`, etc. in `OnModelCreating`.
+
+## 5. Check A Reference Without Loading It
+
+For a dependent-side reference navigation backed by an EF Core foreign-key mapping, use `Exist()` on its `ReferenceEntry` when code only needs to know whether the dependent currently has FK values:
+
+```csharp
+var customerExists = context.Entry(order)
+    .Reference(x => x.Customer)
+    .Exist();
+```
+
+`Exist()` is intentionally singular (not `Exists`). With its default `false` argument it does not load the related entity. `Exist(true)` loads it only when every FK component has a value. This works when the database does not enforce a physical FK constraint, provided EF Core still has a configured relationship and FK properties. It is a presence check for FK values, not proof that a principal row exists: an orphaned value still returns `true`.
+
+Read [the reference-existence guide](../../../doc/ReferenceExistence.md) before using this for composite keys, shadow FKs, or legacy databases.

package/skills/chillsharp_permissions/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: chillsharp_permissions
+description: Guidance on using, evaluating, and managing the authorization and permission model in ChillSharp.
+---
+
+# ChillSharp Permissions & Authorization
+
+This skill explains how ChillSharp's default-deny, hierarchical permission model works and how to utilize the Auth API.
+
+## 1. Subjects and Precedence
+
+Permissions can be assigned to **Users** or **Roles**. The precedence of resolution is:
+1. User property rules
+2. User entity rules
+3. User module rules
+4. Role property rules
+5. Role entity rules
+6. Role module rules
+7. Default Deny
+
+## 2. Resource Hierarchy and Actions
+
+The resource hierarchy is evaluated as:
+`Module -> Entity -> Property`
+
+- **Entity Actions**: `Query`, `Create`, `Update`, `Delete`.
+- **Property Actions**: `See`, `Modify`.
+  - Property rules refine an allowed entity operation; they do not replace them.
+  - To edit a property, you need entity `Create`/`Update` and property `Modify`.
+  - To see a property, you need entity `Query` and property `See`.
+
+## 3. Configuration & Enforcement
+
+- The system uses a **default-deny** posture. If no rule allows access, it is blocked.
+- Define permission rules via `AuthPermissionRule` entries.
+- Server-side validation automatically executes authorization rules during CRUD actions.
+- Clients can fetch user permissions via `/api/chill-auth/get-permissions` and evaluate access rules locally.
+
+## 4. API Endpoints
+
+Privileged users with `CanManagePermissions` can manage ACL/auth settings via:
+- `GET chill-auth/get-user-list`
+- `GET chill-auth/get-user`
+- `POST chill-auth/set-user` (updates roles & user-specific permissions incrementally)
+- `GET chill-auth/get-role-list`
+- `GET chill-auth/get-role`
+- `POST chill-auth/set-role` (updates role permissions & user-role assignments incrementally)

package/skills/chillsharp_plugin_development/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: chillsharp_plugin_development
+description: Develop client-owned ChillSharp UI plugins and overrides while keeping shared UI behavior upgradeable.
+---
+
+# ChillSharp UI Plugin Development
+
+Use this skill for Angular client features that extend a ChillSharp UI client. Keep application-owned code in the client repository and shared behavior in `@chill-sharp/ui-core`.
+
+## Extension boundaries
+
+- Add feature routes and route-owned components under `src/app/core/plugins`.
+- Register them from `register-client-plugins.ts`.
+- Add provider replacements under `src/app/core/overrides` and return them from `register-client-overrides.ts`.
+- Aggregate client providers through `provideClientTemplateProviders()` in the app bootstrap.
+
+Plugins should consume public exports from `@chill-sharp/ui-core`; do not deep-import package internals or edit copied shared implementation.
+
+## Plugin checklist
+
+- Define a stable route and lazy-load large features where appropriate.
+- Keep branding, feature flags, runtime API URLs, and tenant settings in the client-owned config layer.
+- Add a focused README when a plugin has registration, permission, or deployment assumptions.
+- Test a clean build after changing routes/providers and verify the plugin works with the current local package archives.

package/skills/chillsharp_registration/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: chillsharp_registration
+description: Guidance on registering ChillSharp API, DbContext modules, schema services, auth, and i18n configurations in an ASP.NET Core application.
+---
+
+# Registering a ChillSharp Context
+
+This skill describes how to register and configure ChillSharp modules in an ASP.NET Core application.
+
+## 1. DbContext Configuration
+
+In your `DbContext` class:
+- Implement `IChillContext` (and optionally `IChillSchemaDbContext`, `IChillAuthDbContext`, `IChillI18nDbContext`).
+- Register internal ChillSharp models in `OnModelCreating(ModelBuilder modelBuilder)` using extension methods:
+  - `modelBuilder.AddChillSchemaModel()`
+  - `modelBuilder.AddChillAuthModel()`
+  - `modelBuilder.AddChillI18nModel()`
+
+## 2. Core API Registration
+
+In `Program.cs`:
+```csharp
+using ChillSharp.Api;
+using Microsoft.EntityFrameworkCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddDbContext<AppDbContext>(options =>
+    options.UseSqlite("Data Source=app.db"));
+
+// Register Core Chill API
+builder.Services.AddChillApi<AppDbContext>();
+
+var app = builder.Build();
+app.MapChillApi();
+app.Run();
+```
+
+## 3. Protecting the API
+
+If using auth:
+```csharp
+builder.Services.AddChillApi<AppDbContext>(options =>
+{
+    options.ProtectedApi = true;
+});
+
+// Middleware setup
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapChillApi();
+```
+
+## 4. Registering Modules
+
+- **Schema Services**:
+  ```csharp
+  using ChillSharp.Schema;
+  builder.Services.AddChillSchema<AppDbContext>();
+  ```
+- **Auth Services**:
+  ```csharp
+  using ChillSharp.Auth.Api;
+  builder.Services.AddChillAuthApi<AppDbContext>();
+  ```
+- **ASP.NET Core Identity Integration**:
+  ```csharp
+  using ChillSharp.Auth;
+  using ChillSharp.Auth.Api;
+  using Microsoft.AspNetCore.Identity;
+
+  builder.Services.AddIdentityCore<IdentityUser>()
+      .AddEntityFrameworkStores<AppDbContext>()
+      .AddSignInManager()
+      .AddDefaultTokenProviders();
+
+  builder.Services.AddAuthentication(ChillAuthIdentityDefaults.AuthenticationScheme)
+      .AddChillAuthBearer();
+  builder.Services.AddAuthorization();
+
+  // Combined registration
+  builder.Services.AddChillApi<AppDbContext, IdentityUser>();
+  ```
+- **I18n Localized Text Services**:
+  ```csharp
+  using ChillSharp.I18n.Api;
+  builder.Services.AddChillI18nApi<AppDbContext>();
+  ```
+
+## 5. Startup Order Flow
+1. Register DbContext.
+2. Register Identity, Authentication, and Authorization.
+3. Register Chill API (`AddChillApi`).
+4. Register optional ChillSharp modules (Schema, Auth, I18n).
+5. Build application, apply middleware (`UseAuthentication`, `UseAuthorization`).
+6. Call `MapChillApi()`.
+7. Configure OpenAPI/Swagger for client generation if required.