@smartsoft001/pro-claude-plugins 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartsoft001/pro-claude-plugins",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "publishConfig": {
     "access": "public"
   },

package/plugins/flow/skills/impl/SKILL.md

@@ -383,8 +383,8 @@ The agent will:
 
 1. **Check for existing `orchestration.md` attachment** on the task via `mcp__linear__get_issue` (the response includes an `attachments` array).
    - If one exists, delete it via `mcp__linear__delete_attachment({ id: oldAttachmentId })`. Linear hosts the file natively, so nothing else needs cleanup.
-2. **Write locally**: use `Write` to save the orchestration markdown to `/tmp/claude-plans/<taskId>-orchestration.md`.
-3. **Base64-encode**: `b64=$(base64 -i /tmp/claude-plans/<taskId>-orchestration.md)`.
+2. **Write locally**: ensure `.ai/tasks/` is gitignored (idempotent — `.ai/tasks` must NOT be synced to git): `grep -qxF '.ai/tasks/' .gitignore 2>/dev/null || echo '.ai/tasks/' >> .gitignore`. Then `mkdir -p .ai/tasks/<taskId>` and use `Write` to save the orchestration markdown to `.ai/tasks/<taskId>/orchestration.md` (sibling of `plan.md`).
+3. **Base64-encode**: `b64=$(base64 -i .ai/tasks/<taskId>/orchestration.md)`.
 4. **Create Linear attachment** via `mcp__linear__create_attachment`:
    - `issue`: the task/subtask ID
    - `filename`: `orchestration.md`
@@ -392,7 +392,7 @@ The agent will:
    - `title`: `orchestration.md` (exact — used for detection/replacement on the next `/impl` run)
    - `subtitle`: `Plan orkiestracji wygenerowany przez Claude Code`
    - `base64Content`: the base64 string from step 3
-5. **Clean up** the local `/tmp/claude-plans/<taskId>-orchestration.md` file after a successful attachment.
+5. **Keep the local file**: do NOT delete `.ai/tasks/<taskId>/orchestration.md` — it persists as a gitignored local artifact.
 6. **Follow the plan** — execute agents in the defined order.
 7. **Use TDD strictly** — `shared-tdd-developer` is MANDATORY for ALL code implementation.
 
@@ -915,6 +915,7 @@ When verification fails, delegate to appropriate fix agent:
 19. **Capture before screenshots in background**: Launch `screenshot-reporter` agent with `run_in_background: true` BEFORE implementing UI changes to capture "before" state while implementation proceeds
 20. **Capture after screenshots + post to Linear**: After implementation, launch `screenshot-reporter` agent to capture "after" screenshots, generate comparison report, post to Linear, and cleanup
 21. **Document translations changes**: If `apps/web/public/translations.json` was modified, include a table with added/changed translation keys and their PL/EN values in the Implementation Report
+21a. **⚠️ MANDATORY: Translation completeness before completion**: No hardcoded UI strings — every static label, heading, button, aria-label, meta/SEO text goes through a translation key. Before marking a subtask complete, verify that EVERY key referenced in the changed templates/TS exists in `apps/web/public/translations.json` in BOTH `pl` and `en` (a raw `GROUP.key` rendered in the UI is a defect), and that the touched groups are complete against the design/mockup — every visible text on the mockup has its key. When a reference project is available, diff the touched groups against it and fill the gaps
 22. **Capture screenshots in both modes**: Agent captures screenshots in BOTH normal mode and dark mode (high contrast) for complete visual documentation
 23. **Ask before collecting feedback for agent evolution**: When user provides corrections or suggestions during implementation, **explicitly ask** if they want to create a Linear issue for the improvement. Only user-confirmed feedback (answered "Yes") should be processed at evolution checkpoints (Step 3g-evolve, Step 4a) via `shared-agent-evolver` agent.
 24. **Never modify agent files directly during implementation**: The `shared-agent-evolver` agent files all proposals as Linear issues for manual review — it does NOT modify agent, command, or skill files directly.

package/plugins/flow/skills/plan/SKILL.md

@@ -679,7 +679,18 @@ When using `--deep` flag and the Planning Team has completed its analysis, appen
 
 **MANDATORY.** Before any Linear write (deletion of old `plan.md`, creation of new `plan.md`, label apply), the user MUST approve the generated plan content. This is the gate FRA-126 added.
 
-**`--auto` mode**: Skip this entire step. The plan is auto-approved. Record the auto-approval in the final Linear audit comment (e.g. `Plan zaakceptowany automatycznie (--auto)`). Proceed to Step 9.
+**Persist the plan locally first (both modes).** For each task/subtask that needs planning:
+
+- Ensure `.ai/tasks/` is gitignored (idempotent — `.ai/tasks` must NOT be synced to git):
+  ```bash
+  grep -qxF '.ai/tasks/' .gitignore 2>/dev/null || echo '.ai/tasks/' >> .gitignore
+  ```
+- `mkdir -p .ai/tasks/<taskId>`
+- Use the `Write` tool to save the Step 8 plan markdown to `.ai/tasks/<taskId>/plan.md`.
+
+This file is the source for the Linear attachment in Step 9a and is NOT deleted — it persists as a gitignored local artifact. On regeneration (below) the `Write` overwrites it with the new plan.
+
+**`--auto` mode**: Skip the approval prompt below — the plan is auto-approved and already persisted above. Record the auto-approval in the final Linear audit comment (e.g. `Plan zaakceptowany automatycznie (--auto)`). Proceed to Step 9.
 
 **Default mode** (interactive):
 
@@ -749,20 +760,14 @@ Use `AskUserQuestion` tool with options:
 
 For each task that needs planning, upload the plan content directly to Linear via `mcp__linear__create_attachment` — Linear hosts the file itself, no intermediate storage.
 
-#### 9a.1 — Prepare plan content
-
-The plan content is exactly the markdown produced in Step 8 (the same block that would previously have been posted as a comment). Write it to the temp file:
-
-```bash
-mkdir -p /tmp/claude-plans
-```
+#### 9a.1 — Locate plan content
 
-Use the `Write` tool to save the plan markdown to `/tmp/claude-plans/<taskId>-plan.md`.
+The plan content was already written to `.ai/tasks/<taskId>/plan.md` in Step 8a (before acceptance). No temp file is needed — that persistent, gitignored file is the source for the attachment below.
 
 #### 9a.2 — Base64-encode the content
 
 ```bash
-b64=$(base64 -i /tmp/claude-plans/<taskId>-plan.md)
+b64=$(base64 -i .ai/tasks/<taskId>/plan.md)
 ```
 
 On macOS `base64 -i <file>` outputs without line-wrapping (which is what the Linear MCP expects). If you ever switch to GNU coreutils, pipe through `tr -d '\n'` to strip wraps.
@@ -780,9 +785,9 @@ Call `mcp__linear__create_attachment` with:
 
 Linear stores the file on its own infrastructure and surfaces it in the issue's Attachments pane.
 
-#### 9a.4 — Clean up local file
+#### 9a.4 — Keep the local file
 
-Delete `/tmp/claude-plans/<taskId>-plan.md` after the attachment is created successfully. `/push` leaves Linear attachments in place — they stay on the issue as permanent artifacts.
+Do NOT delete `.ai/tasks/<taskId>/plan.md` — it is intentionally kept as a gitignored local artifact. `/push` leaves Linear attachments in place — they stay on the issue as permanent artifacts.
 
 #### Scope rule
 
@@ -1030,4 +1035,4 @@ _Plan generated by Claude Code_
 - **Default mode**: Before saving the plans as attachments, show them to the user for review and approval.
 - **`--auto` mode**: Skip the review step; proceed directly to saving the attachments.
 
-The plan content is written to `/tmp/claude-plans/<taskId>-plan.md`, base64-encoded, and uploaded as a native Linear attachment via `mcp__linear__create_attachment`. After that, the `AI Plan` label is applied to the invoked issue.
+The plan content is written to `.ai/tasks/<taskId>/plan.md` (before acceptance, gitignored), base64-encoded, and uploaded as a native Linear attachment via `mcp__linear__create_attachment`. After that, the `AI Plan` label is applied to the invoked issue.

package/plugins/flow-external/skills/impl/SKILL.md

@@ -133,8 +133,8 @@ Use `shared-impl-orchestrator` agent to generate a `🎭 Agent Orchestration Pla
 Then save it as an `orchestration.md` attachment on the task (not as a comment):
 
 1. **Replace existing orchestration**: use `mcp__linear__get_issue` to list attachments; if one titled `orchestration.md` exists, delete it via `mcp__linear__delete_attachment({ id: oldAttachmentId })`. Linear hosts the file natively, so nothing else needs cleanup.
-2. **Write locally**: `Write` the orchestration markdown to `/tmp/claude-plans/<taskId>-orchestration.md`.
-3. **Base64-encode**: `b64=$(base64 -i /tmp/claude-plans/<taskId>-orchestration.md)`.
+2. **Write locally**: ensure `.ai/tasks/` is gitignored (idempotent — `.ai/tasks` must NOT be synced to git): `grep -qxF '.ai/tasks/' .gitignore 2>/dev/null || echo '.ai/tasks/' >> .gitignore`. Then `mkdir -p .ai/tasks/<taskId>` and `Write` the orchestration markdown to `.ai/tasks/<taskId>/orchestration.md` (sibling of `plan.md`).
+3. **Base64-encode**: `b64=$(base64 -i .ai/tasks/<taskId>/orchestration.md)`.
 4. **Create Linear attachment** via `mcp__linear__create_attachment`:
    - `issue`: the task ID
    - `filename`: `orchestration.md`
@@ -142,7 +142,7 @@ Then save it as an `orchestration.md` attachment on the task (not as a comment):
    - `title`: `orchestration.md` (exact)
    - `subtitle`: `Plan orkiestracji wygenerowany przez Claude Code (external)`
    - `base64Content`: the base64 string from step 3
-5. **Clean up** local `/tmp/claude-plans/<taskId>-orchestration.md` file after the attachment is created.
+5. **Keep the local file**: do NOT delete `.ai/tasks/<taskId>/orchestration.md` — it persists as a gitignored local artifact.
 
 ### Step 4: Implement Each Step
 

package/plugins/flow-external/skills/plan/SKILL.md

@@ -177,7 +177,18 @@ Structure the plan as follows:
 
 **MANDATORY.** Before any Linear write (subtask creation, attachment delete, attachment create, label apply), the user MUST approve the generated plan content. This is the gate FRA-126 added.
 
-**`--auto` mode**: Skip this entire step. The plan is auto-approved. Record the auto-approval in the final Linear audit comment (e.g. `Plan zaakceptowany automatycznie (--auto)`). Proceed to Step 5.
+**Persist the plan locally first (both modes — this is the "przed akceptacją" save).**
+
+- Ensure `.ai/tasks/` is gitignored (idempotent — `.ai/tasks` must NOT be synced to git):
+  ```bash
+  grep -qxF '.ai/tasks/' .gitignore 2>/dev/null || echo '.ai/tasks/' >> .gitignore
+  ```
+- `mkdir -p .ai/tasks/<taskId>`
+- Use the `Write` tool to save the Step 4 plan markdown to `.ai/tasks/<taskId>/plan.md`.
+
+This file is the source for the Linear attachment in Step 6 and is NOT deleted — it persists as a gitignored local artifact. On regeneration (below) the `Write` overwrites it with the new plan.
+
+**`--auto` mode**: Skip the approval prompt below — the plan is auto-approved and already persisted above. Record the auto-approval in the final Linear audit comment (e.g. `Plan zaakceptowany automatycznie (--auto)`). Proceed to Step 5.
 
 **Default mode** (interactive):
 
@@ -233,20 +244,14 @@ If a `plan.md` attachment is being replaced:
 
 - **`--auto` mode**: skip the prompt; delete the old Linear attachment via `mcp__linear__delete_attachment({ id: oldAttachmentId })` automatically and proceed.
 
-#### 6.2 — Write `plan.md` locally
-
-The plan content is exactly the markdown produced in Step 4. Write it to the temp file:
-
-```bash
-mkdir -p /tmp/claude-plans
-```
+#### 6.2 — Locate plan content
 
-Use `Write` to save the plan content to `/tmp/claude-plans/<taskId>-plan.md`.
+The plan content was already written to `.ai/tasks/<taskId>/plan.md` in Step 4a (before acceptance). No temp file is needed — that persistent, gitignored file is the source for the attachment below.
 
 #### 6.3 — Base64-encode
 
 ```bash
-b64=$(base64 -i /tmp/claude-plans/<taskId>-plan.md)
+b64=$(base64 -i .ai/tasks/<taskId>/plan.md)
 ```
 
 #### 6.4 — Create Linear attachment
@@ -260,9 +265,9 @@ Call `mcp__linear__create_attachment` with:
 - `subtitle`: `Plan wygenerowany przez Claude Code (external)`
 - `base64Content`: the base64 string from 6.3
 
-#### 6.5 — Clean up local file
+#### 6.5 — Keep the local file
 
-Delete `/tmp/claude-plans/<taskId>-plan.md` after the attachment is created. `/push` leaves the Linear attachment in place.
+Do NOT delete `.ai/tasks/<taskId>/plan.md` — it is intentionally kept as a gitignored local artifact. `/push` leaves the Linear attachment in place.
 
 ### Step 7: Add "AI Plan" Label
 

package/plugins/flow-legacy/skills/impl/SKILL.md

@@ -352,8 +352,8 @@ The agent will:
 
 1. **Check for existing `orchestration.md` attachment** on the task via `mcp__linear__get_issue` (response includes `attachments`).
    - If one exists, delete it via `mcp__linear__delete_attachment({ id: oldAttachmentId })`. Linear hosts the file natively, so nothing else needs cleanup.
-2. **Write locally**: `Write` the orchestration markdown to `/tmp/claude-plans/<taskId>-orchestration.md`.
-3. **Base64-encode**: `b64=$(base64 -i /tmp/claude-plans/<taskId>-orchestration.md)`.
+2. **Write locally**: ensure `.ai/tasks/` is gitignored (idempotent — `.ai/tasks` must NOT be synced to git): `grep -qxF '.ai/tasks/' .gitignore 2>/dev/null || echo '.ai/tasks/' >> .gitignore`. Then `mkdir -p .ai/tasks/<taskId>` and `Write` the orchestration markdown to `.ai/tasks/<taskId>/orchestration.md` (sibling of `plan.md`).
+3. **Base64-encode**: `b64=$(base64 -i .ai/tasks/<taskId>/orchestration.md)`.
 4. **Create Linear attachment** via `mcp__linear__create_attachment`:
    - `issue`: the task/subtask ID
    - `filename`: `orchestration.md`
@@ -361,7 +361,7 @@ The agent will:
    - `title`: `orchestration.md` (exact — used for detection/replacement on the next `/impl` run)
    - `subtitle`: `Plan orkiestracji wygenerowany przez Claude Code (legacy)`
    - `base64Content`: the base64 string from step 3
-5. **Clean up** local `/tmp/claude-plans/<taskId>-orchestration.md`.
+5. **Keep the local file**: do NOT delete `.ai/tasks/<taskId>/orchestration.md` — it persists as a gitignored local artifact.
 6. **Follow the plan** — execute agents in the defined order.
 7. **Use TDD strictly** — `shared-tdd-developer` is MANDATORY for ALL code implementation.
 

package/plugins/flow-legacy/skills/plan/SKILL.md

@@ -550,7 +550,18 @@ _Plan generated by Claude Code (flow-legacy)_
 
 **MANDATORY.** Before any Linear write (deletion of old `plan.md`, creation of new `plan.md`, label apply), the user MUST approve the generated plan content. This is the gate FRA-126 added.
 
-**`--auto` mode**: Skip this entire step. The plan is auto-approved. Record the auto-approval in the final Linear audit comment (e.g. `Plan zaakceptowany automatycznie (--auto)`). Proceed to Step 9.
+**Persist the plan locally first (both modes — this is the "przed akceptacją" save).** For each task/subtask that needs planning:
+
+- Ensure `.ai/tasks/` is gitignored (idempotent — `.ai/tasks` must NOT be synced to git):
+  ```bash
+  grep -qxF '.ai/tasks/' .gitignore 2>/dev/null || echo '.ai/tasks/' >> .gitignore
+  ```
+- `mkdir -p .ai/tasks/<taskId>`
+- Use the `Write` tool to save the Step 8 plan markdown to `.ai/tasks/<taskId>/plan.md`.
+
+This file is the source for the Linear attachment in Step 9a and is NOT deleted — it persists as a gitignored local artifact. On regeneration (below) the `Write` overwrites it with the new plan.
+
+**`--auto` mode**: Skip the approval prompt below — the plan is auto-approved and already persisted above. Record the auto-approval in the final Linear audit comment (e.g. `Plan zaakceptowany automatycznie (--auto)`). Proceed to Step 9.
 
 **Default mode** (interactive):
 
@@ -618,20 +629,14 @@ Use `AskUserQuestion` with options:
 
 For each task that needs planning, upload the plan content directly to Linear (no external storage).
 
-#### 9a.1 — Write `plan.md` locally
-
-The plan content is exactly the markdown produced in Step 8. Write it to the temp file:
-
-```bash
-mkdir -p /tmp/claude-plans
-```
+#### 9a.1 — Locate plan content
 
-Use `Write` to save the plan content to `/tmp/claude-plans/<taskId>-plan.md`.
+The plan content was already written to `.ai/tasks/<taskId>/plan.md` in Step 8a (before acceptance). No temp file is needed — that persistent, gitignored file is the source for the attachment below.
 
 #### 9a.2 — Base64-encode
 
 ```bash
-b64=$(base64 -i /tmp/claude-plans/<taskId>-plan.md)
+b64=$(base64 -i .ai/tasks/<taskId>/plan.md)
 ```
 
 On macOS `base64 -i <file>` outputs without line-wrapping. On Linux, pipe through `tr -d '\n'` if needed.
@@ -649,9 +654,9 @@ Call `mcp__linear__create_attachment` with:
 
 Linear hosts the file on its own infrastructure.
 
-#### 9a.4 — Clean up local file
+#### 9a.4 — Keep the local file
 
-Delete `/tmp/claude-plans/<taskId>-plan.md` after the attachment is created. `/push` does NOT delete Linear attachments — they stay on the issue.
+Do NOT delete `.ai/tasks/<taskId>/plan.md` — it is intentionally kept as a gitignored local artifact. `/push` does NOT delete Linear attachments — they stay on the issue.
 
 #### Scope rule
 
@@ -739,4 +744,4 @@ After saving:
 - **Default mode**: Before saving the plans as attachments, show them to the user for review and approval.
 - **`--auto` mode**: Skip the review step; proceed directly to saving the attachments.
 
-The plan content is written to `/tmp/claude-plans/<taskId>-plan.md`, base64-encoded, and uploaded as a native Linear attachment via `mcp__linear__create_attachment`. After that, the `AI Plan` label is applied to the invoked issue.
+The plan content is written to `.ai/tasks/<taskId>/plan.md` (before acceptance, gitignored), base64-encoded, and uploaded as a native Linear attachment via `mcp__linear__create_attachment`. After that, the `AI Plan` label is applied to the invoked issue.

package/plugins/smart-pro/skills/angular-components-crud/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: angular-components-crud
+description: Pro CRUD shell for @smartsoft001/pro-crud-shell-angular — ProCrudModule.forFeature wiring, 6 smartpro-* components with inputs/selectors, DYNAMIC_COMPONENTS_STORE override mechanism, cssClass/variant styling surface, known routed-wrapper projection limitation, and [class]-not-[class.smart:X] Tailwind rule.
+user-invocable: false
+---
+
+# Pro CRUD Shell (`@smartsoft001/pro-crud-shell-angular`)
+
+This package is the pro UI tier of the CRUD engine. It inherits all logic from
+`@smartsoft001/crud-shell-angular` (config-driven routing, NgRx facades,
+filter/sort/export/multiselect) and replaces the rendering layer with
+`smartpro-*` components styled with the `smart:` Tailwind prefix.
+
+## When to Use This Skill
+
+- Developer wants to wire a CRUD feature with pro Tailwind UI → show `ProCrudModule.forFeature` setup
+- Developer asks which pro CRUD components exist → show the component table below
+- Developer asks how the engine selects the pro page over the free one → explain `DYNAMIC_COMPONENTS_STORE`
+- Developer asks how to style the CRUD pages → show `cssClass` / `variant` on `CrudFullConfig`
+- Developer gets a blank page despite the override being registered → point to the known routed-wrapper limitation
+- Developer tries to use `[class.smart:X]` → apply the Tailwind rule
+
+## Module Setup
+
+### `ProCrudModule.forFeature`
+
+```typescript
+import { NgModule } from '@angular/core';
+import { ProCrudModule } from '@smartsoft001/pro-crud-shell-angular';
+
+@NgModule({
+  imports: [
+    ProCrudModule.forFeature({
+      routing: true, // true -> ProCrudModule (routed pages); false -> ProCrudCoreModule (no routes)
+      config: userConfig, // CrudFullConfig<T>
+      // socket: true,    // opt-in realtime provider (inert stub today)
+    }),
+  ],
+})
+export class UserModule {}
+```
+
+`forFeature` delegates to the engine's `CrudModule.forFeature` for all engine
+providers, then additionally provides `ProCrudListPageComponent` and
+`ProCrudItemPageComponent` into `DYNAMIC_COMPONENTS_STORE`.
+
+### `ProCrudCoreModule`
+
+When `routing: false`, `forFeature` returns `ProCrudCoreModule`, which wraps
+the engine's `CrudCoreModule` (logic without routed pages). Use this when you
+manage routing yourself or compose the pro components manually.
+
+## CrudFullConfig — Relevant Fields
+
+Declare `CrudFullConfig<T>` from `@smartsoft001/crud-shell-angular`. The fields
+below are the ones the pro layer reads directly; the full reference is in the
+engine's README.
+
+```typescript
+import { CrudFullConfig } from '@smartsoft001/crud-shell-angular';
+import { ListMode, PaginationMode } from '@smartsoft001/angular';
+
+export const userConfig: CrudFullConfig<User> = {
+  apiUrl: 'https://api.example.com',
+  entity: 'user',
+  type: User,
+
+  title: 'Users',
+  details: true,
+  edit: true,
+  add: true,
+  remove: true,
+  search: true,
+  export: true,
+  pagination: { limit: 25 },
+  sort: { default: 'lastName', defaultDesc: false },
+  list: {
+    mode: ListMode.desktop,
+    paginationMode: PaginationMode.singlePage,
+    groups: [], // optional — activates the group accordion
+  },
+  inputComponents: {}, // per-field input overrides keyed by field name
+
+  // Pro styling surface (tier 2)
+  cssClass: 'smart:bg-gray-50', // forwarded as [class] to page host
+  variant: 'with-actions', // picks the smartpro-page-* variant
+};
+```
+
+## DYNAMIC_COMPONENTS_STORE Override Mechanism
+
+The engine resolves `'crud-list-page'` and `'crud-item-page'` dynamic slots
+against `DYNAMIC_COMPONENTS_STORE`. Each pro page component carries a static
+`smartType` field that matches those keys:
+
+```typescript
+// Pro list page
+ProCrudListPageComponent.smartType = 'crud-list-page';
+
+// Pro item page
+ProCrudItemPageComponent.smartType = 'crud-item-page';
+```
+
+`ProCrudModule.forFeature` registers both into the token:
+
+```typescript
+{
+  provide: DYNAMIC_COMPONENTS_STORE,
+  useValue: [ProCrudListPageComponent, ProCrudItemPageComponent],
+}
+```
+
+The engine's dynamic-component resolver checks `DYNAMIC_COMPONENTS_STORE` first
+and selects the pro variant over the free standard variant for those two slots.
+
+## Component Reference
+
+All six components are `ChangeDetectionStrategy.OnPush` and extend an engine
+base class that provides all facade wiring.
+
+| Selector                    | Class                         | Extends                     | Purpose                                                                                                                                                   |
+| --------------------------- | ----------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `smartpro-crud-list-page`   | `ProCrudListPageComponent`    | `CrudListPageBaseComponent` | List page: `smart-crud-filters-config` + `smartpro-list`; shows group accordion when `config.list.groups` is set; hides flat list during search           |
+| `smartpro-crud-item-page`   | `ProCrudItemPageComponent`    | `CrudItemPageBaseComponent` | Item page: `smartpro-details` in details mode; `smart-form` with `config.inputComponents` in add/update mode                                              |
+| `smartpro-crud-filters`     | `ProCrudFiltersComponent`     | `FiltersBaseComponent`      | Filters panel: Tailwind header with close button; individual filter controls via engine `smart-crud-filter`                                               |
+| `smartpro-crud-group`       | `ProCrudGroupComponent`       | `GroupBaseComponent`        | Group accordion: accessible `button`/region with `aria-expanded`, rotating chevron; recursive child group support; embeds `smartpro-list` for leaf groups |
+| `smartpro-crud-multiselect` | `ProCrudMultiselectComponent` | `MultiselectBaseComponent`  | Multiselect panel: count header with close; optional `config.list.components.multi` outlet; multi-update `smart-form` + `smartpro-button` submit          |
+| `smartpro-crud-export`      | `ProCrudExportComponent`      | `ExportBaseComponent`       | Export popover: CSV and XLSX triggers via `smartpro-button`; `config.cssClass` forwarded to wrapper                                                       |
+
+### Key inputs (inherited from engine base classes)
+
+| Component                   | Signal/Input                                         | Source                      | Description                                                          |
+| --------------------------- | ---------------------------------------------------- | --------------------------- | -------------------------------------------------------------------- |
+| `smartpro-crud-list-page`   | `listOptions()`                                      | `CrudListPageBaseComponent` | `IListOptionsPro<T>` fed to `smartpro-list`                          |
+| `smartpro-crud-list-page`   | `config`                                             | `inject(CrudFullConfig)`    | Full config (groups, cssClass, variant)                              |
+| `smartpro-crud-item-page`   | `mode()`                                             | `CrudItemPageBaseComponent` | `'details' \| 'add' \| 'update'`                                     |
+| `smartpro-crud-item-page`   | `detailsOptions()`                                   | `CrudItemPageBaseComponent` | Options fed to `smartpro-details`                                    |
+| `smartpro-crud-item-page`   | `selected()`                                         | `CrudItemPageBaseComponent` | Current entity fed to `smart-form`                                   |
+| `smartpro-crud-filters`     | `list()`                                             | `FiltersBaseComponent`      | Array of filter items; each rendered by `smart-crud-filter`          |
+| `smartpro-crud-filters`     | `hideMenu()`                                         | `FiltersBaseComponent`      | Hides the header row when `true`                                     |
+| `smartpro-crud-group`       | `groups()`                                           | `GroupBaseComponent`        | Array of group nodes with `key`, `text`, `show`, optional `children` |
+| `smartpro-crud-group`       | `listOptions()`                                      | `GroupBaseComponent`        | `IListOptionsPro<T>` for leaf group `smartpro-list`                  |
+| `smartpro-crud-multiselect` | `list()`                                             | `MultiselectBaseComponent`  | Array of selected entities                                           |
+| `smartpro-crud-export`      | `buttonExportCsvOptions` / `buttonExportXlsxOptions` | `ExportBaseComponent`       | `IButtonOptions` for each trigger                                    |
+
+## Styling Rules
+
+### Tier-2 surface: `cssClass` and `variant`
+
+```typescript
+// In CrudFullConfig
+cssClass: 'smart:bg-gray-50 smart:rounded-xl',
+variant: 'with-actions',   // any SmartPageVariant from @smartsoft001/pro-angular
+```
+
+- `cssClass` is bound as `[class]` on the page host element of the list and item pages, and on the export wrapper.
+- `variant` is threaded into `pageOptions().variant`, which `SmartProComponentsModule` resolves to the matching `smartpro-page-*` component via `PAGE_VARIANT_COMPONENTS_TOKEN`.
+
+### Tailwind `smart:` prefix — no `[class.smart:X]` shorthand
+
+Angular's `[class.X]` shorthand treats the full string `smart:X` as the class
+name, which breaks the Tailwind `smart:` prefix during JIT purging.
+
+```html
+<!-- WRONG -->
+<div [class.smart:font-semibold]="isActive"></div>
+
+<!-- CORRECT -->
+<div [class]="isActive ? 'smart:font-semibold' : ''"></div>
+```
+
+All pro CRUD components follow this rule. Enforce it in any customization.
+
+## Known Limitation — Routed Wrappers Do Not Project the Pro Page
+
+The engine's free routed wrappers (`smart-crud-list-page` /
+`smart-crud-item-page`) use `CreateDynamicComponent` to mount the override
+found in `DYNAMIC_COMPONENTS_STORE`. The wrapper templates currently do not
+include `DynamicContentDirective` in their `imports` array, so the pro component
+is instantiated but not inserted into the DOM — the page renders blank.
+
+**This is an engine-side fix pending in `@smartsoft001/crud-shell-angular`.**
+
+Until the fix lands, mount the pro pages directly instead of relying on the
+routed wrappers:
+
+```html
+<smartpro-crud-list-page></smartpro-crud-list-page>
+<smartpro-crud-item-page></smartpro-crud-item-page>
+```
+
+Or compose the components manually inside your own page shell.
+
+## Usage Example
+
+```typescript
+// user.module.ts
+import { NgModule } from '@angular/core';
+import { ProCrudModule } from '@smartsoft001/pro-crud-shell-angular';
+import { userConfig } from './user.config';
+
+@NgModule({
+  imports: [ProCrudModule.forFeature({ routing: true, config: userConfig })],
+})
+export class UserModule {}
+```
+
+```html
+<!-- user-list.page.html — direct mount (recommended until engine fix) -->
+<smartpro-crud-list-page></smartpro-crud-list-page>
+```
+
+```html
+<!-- user-item.page.html -->
+<smartpro-crud-item-page></smartpro-crud-item-page>
+```
+
+Compositional use — embed only the filters panel in a custom page shell:
+
+```html
+<aside class="smart:w-72">
+  <smartpro-crud-filters></smartpro-crud-filters>
+</aside>
+<main>
+  <!-- your own content -->
+</main>
+```
+
+## File Locations
+
+- Package: `packages/crud/shell/pro-angular/`
+- Module: `packages/crud/shell/pro-angular/src/lib/pro-crud.module.ts`
+- Pages: `packages/crud/shell/pro-angular/src/lib/pages/{list,item}/`
+- Components: `packages/crud/shell/pro-angular/src/lib/components/{filters,group,multiselect,export}/`
+- Barrel: `packages/crud/shell/pro-angular/src/index.ts`
+- README: `packages/crud/shell/pro-angular/README.md`