baldart 3.6.2

package/framework/.claude/skills/doc-writing-for-rag/references/before-after-examples.md

@@ -0,0 +1,291 @@
+# Before/After Examples — Wave 1+2+3 Compression
+
+Casi concreti validati sul corpus reale. Per ogni esempio: prima, dopo, tecnica applicata.
+
+## Example 1 — API Endpoint (booking.md)
+
+### Before (Wave 0) — 150+ linee per endpoint
+
+```markdown
+#### POST /api/v1/merchant/booking/rooms
+
+Create a new booking room. This endpoint creates a new room in the store's
+booking system. The room will be used to group tables together.
+
+**Authentication**: This endpoint requires authentication via `withAuthNoParams`.
+The session must have a valid merchantUserId with MERCHANT role. ADMIN users
+can also access this endpoint on behalf of any merchant.
+
+**Store Access Control**: The request must include a `storeId` query parameter
+that identifies the target store. The system verifies that the authenticated
+user has access to this store. Admin users have access to all stores.
+Merchant users only have access to stores belonging to their merchant.
+
+**Request Body**:
+```json
+{
+  "storeId": "uuid-string",
+  "name": "Sala Principale",
+  "capacity": 50,
+  "order": 1
+}
+```
+
+**Request Body Fields**:
+- `storeId` (string, required): The UUID of the store
+- `name` (string, required): The display name, max 80 characters
+- `capacity` (number, required): Maximum capacity, must be positive
+- `order` (number, optional): Display order
+
+**Response 201 Created**:
+```json
+{
+  "id": "room-uuid",
+  "storeId": "store-uuid",
+  "name": "Sala Principale",
+  "capacity": 50,
+  "order": 1,
+  "createdAt": "2026-04-05T10:30:00Z",
+  "updatedAt": "2026-04-05T10:30:00Z"
+}
+```
+
+**Response Fields**:
+[Field list repeated...]
+
+**Errors**:
+- 400 "Nome sala obbligatorio" — if name is empty
+- 400 "Capacità non valida" — if capacity < 1
+- 409 "Sala duplicata" — if name exists
+[etc]
+```
+
+### After (Wave 1) — 12 linee per endpoint
+
+```markdown
+### POST /api/v1/merchant/booking/rooms
+
+**Auth**: withAuthNoParams  |  **Access**: ADMIN + MERCHANT (see §Store Access Control)
+
+**Body**:
+| Field | Type | Required | Desc |
+|-------|------|----------|------|
+| storeId | string | yes | Store UUID |
+| name | string | yes | 1-80 chars |
+| capacity | number | yes | >0 |
+| order | number | no | Display sort |
+
+**Returns**: [BookingRoom](./schemas.md#bookingroom)
+**Errors**: NAME_REQUIRED, INVALID_CAPACITY, ROOM_DUPLICATE ([errors.md](../errors.md#booking---rooms))
+```
+
+**Saving**: 138 linee per endpoint × 26 endpoints = ~3600 linee. Total booking.md: 4201→1833 (-56%).
+
+### Tecniche applicate
+
+1. Store Access Control spiegato UNA VOLTA in intro, poi `see §Store Access Control`
+2. Request body: tabella compatta invece di narrative + JSON example
+3. Response: link a schema invece di JSON inline
+4. Errors: codes invece di stringhe italiane + link alla sezione errors.md
+
+## Example 2 — UI Reference (ui/merchant.md)
+
+### Before — repetizioni su ogni pagina
+
+```markdown
+### /merchant/bookings/planner
+
+**Purpose**: Drag-drop table reservations planner
+**Protection**: This page requires authentication. Session must have
+merchantUserId with MERCHANT role. ADMIN users can access any merchant's
+pages by impersonating the merchant.
+**Layout**: Uses MerchantResponsiveLayout which provides the standard
+sidebar navigation, top bar with store switcher, and responsive container.
+**Store switching**: Supports CT-0067 multi-store. When merchant has
+multiple stores, user can switch via top bar dropdown. Current store
+persisted in sessionStorage with Safari ITP fallback.
+**Styling**: Neo-Brutalism design system (bold borders, amber accents,
+Press Start 2P titles). Follows ui-guidelines.md §3.
+**Disabled modules**: If merchant's license doesn't include this module,
+the page is completely hidden from navigation.
+
+[Content per planner...]
+```
+
+### After — Conventions block top + minimal per-page
+
+```markdown
+## Conventions (apply to all pages below)
+
+- **Auth**: merchantUserId + MERCHANT role (ADMIN via impersonation)
+- **Layout**: MerchantResponsiveLayout
+- **Store switching**: CT-0067 multi-store, sessionStorage persist
+- **Styling**: Neo-Brutalism (see ui-guidelines.md §3)
+- **License gating**: disabled modules hidden from navigation
+
+---
+
+### /merchant/bookings/planner
+
+**Purpose**: Drag-drop table reservations planner
+
+[Content per planner...]
+```
+
+**Saving**: ~200 linee duplicate × 1 block = eliminate una volta = ~200 linee risparmio. Total merchant.md: 2780→1265 (-54%).
+
+### Tecnica
+
+Tutte le convenzioni che valgono per OGNI pagina → blocco Conventions all'inizio. Ogni pagina elenca SOLO cosa è specifico.
+
+## Example 3 — Schema Reuse (menu.md)
+
+### Before — schema inline per ogni endpoint
+
+```markdown
+#### POST /api/v1/merchant/menu/items
+
+**Response**:
+```json
+{
+  "id": "item-uuid",
+  "categoryId": "cat-uuid",
+  "name": "Margherita",
+  "description": "Pizza tradizionale...",
+  "basePrice": 9.50,
+  "imageUrl": "https://...",
+  "allergens": ["gluten", "dairy"],
+  "nutritionalInfo": {
+    "calories": 800,
+    "carbs": 90,
+    "protein": 30,
+    "fat": 25
+  },
+  "variants": [...],
+  "createdAt": "...",
+  "updatedAt": "..."
+}
+```
+
+#### GET /api/v1/merchant/menu/items/[id]
+
+**Response**:
+```json
+{
+  "id": "item-uuid",
+  "categoryId": "cat-uuid",
+  [same structure repeated]
+}
+```
+
+[repeat 10x for each item endpoint]
+```
+
+### After — schema centrale + references
+
+In `schemas.md`:
+```markdown
+## MenuItem
+| Field | Type | Notes |
+|-------|------|-------|
+| id | string | UUID |
+| categoryId | string | FK MenuCategory |
+| name | string | 1-120 chars |
+| description | string | 0-500 chars |
+| basePrice | number | €, 2 decimals |
+| imageUrl | string \| null | |
+| allergens | string[] | CEE 1169/2011 list |
+| nutritionalInfo | NutritionalInfo | nested |
+| variants | MenuVariant[] | |
+
+## NutritionalInfo
+| Field | Type | Notes |
+|-------|------|-------|
+| calories | number | kcal per serving |
+| carbs | number | g |
+| protein | number | g |
+| fat | number | g |
+```
+
+In `menu.md`:
+```markdown
+### POST /api/v1/merchant/menu/items
+
+**Returns**: [MenuItem](./schemas.md#menuitem)
+
+### GET /api/v1/merchant/menu/items/[id]
+
+**Returns**: [MenuItem](./schemas.md#menuitem)
+```
+
+**Saving**: 20-30 linee JSON per endpoint × 10 endpoints = 250+ linee eliminate. Total menu.md: 1910→719 (-62%).
+
+### Tecnica
+
+Schemi riusati 2+ volte → sposta in `schemas.md`. Ogni endpoint linka invece di ripetere.
+
+## Example 4 — Error Codes Enum (generic)
+
+### Before — stringhe italiane hardcoded
+
+```markdown
+**Errors**:
+- 400 "Nome sala obbligatorio"
+- 400 "La capacità deve essere maggiore di zero"
+- 404 "Sala non trovata"
+- 409 "Esiste già una sala con questo nome"
+- 403 "Non hai i permessi per questa operazione"
+```
+
+### After — error codes + central enum
+
+In `errors.md`:
+```markdown
+## Booking — Rooms
+
+| Code | HTTP | IT Message | Context |
+|------|------|------------|---------|
+| NAME_REQUIRED | 400 | Nome sala obbligatorio | POST/PATCH |
+| INVALID_CAPACITY | 400 | Capacità non valida (deve essere >0) | POST/PATCH |
+| ROOM_NOT_FOUND | 404 | Sala non trovata | GET/PATCH/DELETE |
+| ROOM_DUPLICATE | 409 | Sala già esistente (nome duplicato) | POST/PATCH |
+| FORBIDDEN | 403 | Permessi insufficienti | Any |
+```
+
+In `booking.md`:
+```markdown
+**Errors**: NAME_REQUIRED, INVALID_CAPACITY, ROOM_NOT_FOUND, ROOM_DUPLICATE, FORBIDDEN
+```
+
+### Tecnica
+
+Error codes enum centralizzato + IT message → endpoint usa solo i codes. Vantaggi:
+1. API consumers parsano codes stabili, non stringhe traducibili
+2. Docs rimangono concise
+3. Refactor error messages in UN SOLO POSTO
+
+## Example 5 — PRD Compression (PRD-closedtable.md)
+
+### Pattern: tabelle > narrative per requisiti
+
+**Before**: "The system shall allow merchants to create booking rooms. Rooms represent physical areas of the restaurant. Each room has a name, capacity, and display order. The name must be unique within the store. The capacity must be positive..."
+
+**After**:
+```markdown
+## Functional Requirements
+
+| ID | Component | Requirement |
+|----|-----------|-------------|
+| FR-01 | BookingRoom | Merchant può creare room con name, capacity, order |
+| FR-02 | BookingRoom | name unique per store |
+| FR-03 | BookingRoom | capacity must be >0 |
+```
+
+Saving: 3-5 linee narrative → 1 linea tabella per requirement.
+
+## Quando NON comprimere
+
+- Sezioni con logic critica (es. state machine transitions, race condition handling): meglio prose che tabelle
+- Esempi UX con dialog flow: tabella non rende
+- Discussion Log / decision rationale: se compresso perde contesto
+- Codice critico in code blocks: mantieni verbatim

package/framework/.claude/skills/doc-writing-for-rag/references/compact-templates.md

@@ -0,0 +1,183 @@
+# Compact Templates
+
+Template validati su 45 file in 3 wave di compressione. Ogni template include: before/after, line count, note critiche.
+
+## API Endpoint Template
+
+### Standard (80% dei casi)
+
+```markdown
+### POST /api/v1/domain/resource
+
+**Auth**: withAuthNoParams  |  **Access**: ADMIN + MERCHANT
+
+**Body**:
+| Field | Type | Required | Desc |
+|-------|------|----------|------|
+| storeId | string | yes | Store UUID |
+| name | string | yes | Display name, 1-120 chars |
+
+**Returns**: [ResourceResponse](./schemas.md#resourceresponse)
+**Errors**: NAME_REQUIRED, STORE_NOT_FOUND ([errors.md](../errors.md#domain-domain))
+```
+
+**Dimensione**: 10-15 linee per endpoint. Target: 30+ endpoint = ~400 linee totali.
+
+### Varianti
+
+**GET con query params**:
+```markdown
+**Query**:
+| Param | Type | Required | Desc |
+|-------|------|----------|------|
+| storeId | string | yes | FK Store |
+| limit | number | no | Default 50, max 200 |
+```
+
+**Path params embedded**:
+```markdown
+### PATCH /api/v1/domain/resource/[resourceId]
+```
+Non serve tabella separata per path param (è nell'URL pattern).
+
+**Public endpoint (no auth)**:
+```markdown
+**Auth**: public  |  **Access**: anonymous
+```
+
+**Cron endpoint**:
+```markdown
+**Auth**: cron secret  |  **Schedule**: daily 03:00 UTC
+```
+
+### Cosa NON includere
+
+- ❌ JSON response inline (vai a schemas.md)
+- ❌ Stringhe errore italiane hardcoded (usa error codes → errors.md)
+- ❌ "Store Access Control" spiegato per ogni endpoint (vedi §Cross-reference)
+- ❌ Esempi curl/fetch ridondanti (1 per dominio è sufficiente)
+
+## PRD Template
+
+### Struttura compatta
+
+```markdown
+---
+doc_type: prd
+domain: booking
+canonicality: canonical-source
+status: in_progress
+last_updated: 2026-04-05
+---
+
+# PRD — Feature Name
+
+## Context & Problem
+[3-5 paragrafi focalizzati]
+
+## User Stories
+| ID | Story | Priority |
+|----|-------|----------|
+| MS-01 | As merchant I can... | P0 |
+
+## Functional Requirements
+| ID | Requirement | Component |
+|----|-------------|-----------|
+| FR-01 | System must... | booking-service |
+
+## Acceptance Criteria
+| ID | Given | When | Then |
+|----|-------|------|------|
+| AC-01 | ... | ... | ... |
+
+## Data Model
+[reference to schemas or inline if new]
+
+## API Surface
+[link a endpoint docs esistenti o nuovi]
+
+## Edge Cases
+| ID | Case | Handling |
+|----|------|----------|
+| EC-01 | ... | ... |
+```
+
+**Dimensione target**: max 1500 linee. Se supera, split in sub-PRD per capitolo.
+
+### Cosa comprimere rispetto a PRD verbosi
+
+- ASCII tree/box diagrams → tabelle o prosa compatta
+- Code blocks TypeScript long-form → prosa descrittiva (preserva logica)
+- Esempi JSON multipli → 1 esempio + schema reference
+- "Discussion Log" 200 linee → key bullets per decisione
+- Validation rules narrative → tabella | Field | Rule | Error code |
+
+## UI Reference Template
+
+### Pattern "Conventions block + Pages"
+
+```markdown
+---
+doc_type: reference
+domain: ui
+canonicality: canonical-source
+last_updated: 2026-04-05
+---
+
+# Merchant UI Reference
+
+## Conventions (applies to all pages below)
+
+- **Auth**: merchantUserId + MERCHANT role
+- **Layout**: MerchantResponsiveLayout
+- **Store switching**: CT-0067 multi-store support
+- **Styling**: Neo-Brutalism design system
+- **Hidden modules**: disabled via license gating
+
+## License Gating System (FEAT-0128)
+
+| Module | License tier | Gated route | Behavior |
+|--------|--------------|-------------|----------|
+| booking | Pro | /merchant/bookings/* | 302 → /merchant/dashboard |
+| crm | Starter | /merchant/crm/* | 404 |
+
+## Pages
+
+### /merchant/bookings/planner
+
+**Purpose**: Drag-drop table reservations
+**Auth**: MERCHANT
+**Key features**: [concise bullet list]
+**Data sources**: GET /api/v1/merchant/booking/reservations
+```
+
+**Dimensione**: 15-25 linee per pagina. Target: 30 pagine = ~600 linee.
+
+## Collections / Data Model Template
+
+```markdown
+## Collection: bookingRooms
+
+Path: `merchants/{mid}/stores/{sid}/bookingRooms/{rid}`
+
+**Fields**:
+| Field | Type | Req | Notes |
+|-------|------|-----|-------|
+| name | string | yes | 1-80 chars, unique per store |
+| capacity | number | yes | >0 |
+| order | number | no | Display sort |
+
+**Composite indexes**:
+| Fields | Query |
+|--------|-------|
+| storeId + order | Sort rooms by display order |
+```
+
+Bullet lists SHORT se preferibile a tabelle per collezioni con pochi campi.
+
+## Rules of thumb
+
+1. **Prima scegli la struttura**, poi scrivi (outline first)
+2. **Grep before write**: verifica se schema/error code/concept esiste già
+3. **Test mentale**: se un lettore AI riesce a rispondere al 100% delle domande legittime con le info date, è completo
+4. **Dense ≠ criptico**: comprimi verbosità, non chiarezza

package/framework/.claude/skills/doc-writing-for-rag/references/frontmatter-minimal.md

@@ -0,0 +1,112 @@
+# Frontmatter Minimal — 4-Field Standard
+
+Protocollo frontmatter validato su 45 file riscritti. **Solo 4 campi obbligatori**; tutto il resto è derivabile da git / tooling.
+
+## Standard template
+
+```yaml
+---
+doc_type: reference
+domain: booking
+canonicality: canonical-source
+last_updated: 2026-04-05
+---
+```
+
+## Campi obbligatori (4)
+
+| Campo | Valori ammessi | Esempi |
+|-------|----------------|--------|
+| `doc_type` | `reference`, `adr`, `prd`, `guide`, `spec`, `runbook`, `index` | `reference` |
+| `domain` | dominio funzionale (snake-case) | `booking`, `menu`, `dio`, `customer`, `admin` |
+| `canonicality` | `canonical-source`, `derived`, `index`, `deprecated` | `canonical-source` |
+| `last_updated` | ISO date YYYY-MM-DD | `2026-04-05` |
+
+## Campi OPZIONALI (solo se servono)
+
+| Campo | Quando usare |
+|-------|--------------|
+| `status` | Solo per PRD: `draft`, `in_progress`, `approved`, `done` |
+| `related_code_paths` | Solo se drift-detection hook lo richiede |
+| `last_verified_from_code` | Solo se c'è automated verification |
+
+## Campi DA RIMUOVERE (dal legacy frontmatter)
+
+Questi erano presenti nei file pre-compressione ma **NON servono**:
+
+| Campo | Perché rimuovere |
+|-------|------------------|
+| `owner` | Derivabile da git blame |
+| `audit_notes` | Drift tracking dinamico → git commits |
+| `freshness_status` | Calcolabile da last_updated vs oggi |
+| `stale_since` | Legacy drift marker, dinamico |
+| `stale_triggered_by` | Legacy drift marker, dinamico |
+| `stale_reason` | Legacy drift marker, dinamico |
+| `diataxis_type` | Derivabile da doc_type |
+| `hub_role` | Legacy, non usato da tooling attivo |
+| `verification_scope` | Legacy |
+
+## Esempi per doc_type
+
+### Reference doc (API, UI, data-model)
+```yaml
+---
+doc_type: reference
+domain: booking
+canonicality: canonical-source
+last_updated: 2026-04-05
+---
+```
+
+### PRD
+```yaml
+---
+doc_type: prd
+domain: booking
+canonicality: canonical-source
+status: in_progress
+last_updated: 2026-04-05
+---
+```
+
+### ADR
+```yaml
+---
+doc_type: adr
+domain: booking
+canonicality: canonical-source
+last_updated: 2026-04-05
+---
+```
+
+### Index/registry
+```yaml
+---
+doc_type: index
+domain: platform
+canonicality: index
+last_updated: 2026-04-05
+---
+```
+
+## Perché 4 campi e basta
+
+**Signal/noise**: ogni campo frontmatter costa token al reindex LLM. Un frontmatter da 17 linee su 200 linee di doc = **8.5% overhead**. Con 4 linee → **2%**.
+
+**Derivabilità**: `owner`, `last_verified_*`, `stale_*` sono **dinamici**. Salvati nel file diventano immediatamente stale. Meglio calcolarli on-demand da git.
+
+**Chiarezza**: un frontmatter breve è facilmente leggibile. Quello lungo nasconde le info importanti.
+
+## Se devo aggiungere nuovi campi
+
+**STOP** e chiediti:
+1. È davvero canonico o è derivabile?
+2. Verrà mai aggiornato manualmente?
+3. Serve a un tool esistente (quale?)?
+
+Se le risposte sono "derivabile" o "no" → **non aggiungerlo**.
+
+Se serve davvero a un tool:
+- Documenta il tool nel frontmatter-guide
+- Aggiungi il campo solo ai file che quel tool scansiona
+- Non propagarlo a tutti i file

package/framework/.claude/skills/doc-writing-for-rag/references/line-count-targets.md

@@ -0,0 +1,110 @@
+# Line Count Targets — Dense Documentation Sizing
+
+Soglie validate su 45 file riscritti. Obiettivo: mantenere chunks LightRAG gestibili e signal/noise alto.
+
+> File path examples below (`docs/references/api/booking.md`, ecc.) are taken
+> from a sample project (multi-merchant fidelity platform) and are kept as
+> concrete illustrations. Sostituisci con le tue path effettive
+> (`${paths.references_dir}/...`) e i tuoi domini. Le soglie numeriche e le
+> regole di split valgono indipendentemente dal dominio.
+
+## Target per doc type
+
+| Doc type | Max linee | Sweet spot | Azione se supera |
+|----------|-----------|------------|------------------|
+| **API ref singolo** | 1500 | 400-900 | Split in sub-files per sub-domain |
+| **PRD** | 1500 | 600-1200 | Split per capitoli/fasi |
+| **UI ref** | 1500 | 500-1000 | Split per area applicativa |
+| **Collections doc** | 1000 | 400-700 | Split per collection family |
+| **ADR** | 200 | 60-150 | NON superare; se serve più, crea follow-up ADR |
+| **Index/registry** | 500 | 100-300 | Solo pointer+summary, niente contenuto sostanziale |
+| **Guide/runbook** | 800 | 200-500 | Split per workflow/fase |
+
+## Motivazioni tecniche
+
+### LightRAG chunking
+- Chunk size: 100-6000 caratteri (~150-1000 token)
+- File >1500 linee producono 30+ chunks → dilution semantic similarity
+- Chunk boundary su heading boundaries → struttura gerarchica chiara aiuta
+
+### Token budget per LLM entity extraction
+- Ogni chunk × ~2-5 chiamate LLM (entity+relationship extraction)
+- File gigante = molti chunk = costi esponenziali durante reindex
+- File 1500 linee × 30 chunk × 3 LLM calls = 90 calls (gestibile)
+- File 4000 linee × 80 chunk × 3 LLM calls = 240 calls (lento)
+
+### Signal/noise
+- File piccoli (<500 linee) hanno tipicamente S/N >80%
+- File medi (500-1500) S/N 70-80%
+- File grandi (>1500) S/N 50-65% — verbosità cumulativa
+- Target generale: **>75% S/N ratio**
+
+## Regola empirica scanning
+
+Se un reviewer umano scorre velocemente il file:
+- **<1500 linee**: può tenere il contesto in mente
+- **1500-2500**: serve TOC o grep mirato
+- **>2500**: si perde, va splittato
+
+Stessa cosa per LLM context window utility.
+
+## Quando splittare
+
+### Criterio 1: linee supera soglia
+File >1500 linee (reference/PRD/UI) → candidate per split.
+
+### Criterio 2: multiple sub-domains
+Un file `api/booking.md` che contiene:
+- Rooms CRUD
+- Tables CRUD
+- Reservations
+- Availability
+- Tags
+- ...
+
+→ Split in `api/booking/rooms-tables-combos.md`, `api/booking/reservations.md`, etc.
+
+### Criterio 3: differente audience
+Se parte del file è per MERCHANT e parte per ADMIN → considerare split.
+
+## Struttura post-split
+
+### Option A: sub-folder + parent index
+
+```
+docs/references/api/booking.md           # parent/index, ~500 linee
+docs/references/api/booking/
+  ├── rooms-tables-combos.md              # detail
+  ├── reservations.md                     # detail
+  └── policies-availability.md            # detail
+```
+
+Parent `booking.md` ha solo: intro dominio + index per sub-files + endpoint shared (ping, health).
+
+### Option B: sibling files
+
+```
+docs/references/api/booking-rooms.md
+docs/references/api/booking-reservations.md
+docs/references/api/booking-tags.md
+```
+
+Meno gerarchico, più semplice per navigazione.
+
+## Anti-pattern
+
+❌ **Split forzato** di file ben bilanciati (<1500 linee) solo per rispettare target.
+❌ **Eliminare contenuto semantico** per rispettare target → preferire split.
+❌ **Tabelle mega-width** (>8 colonne) — si comprimere orizzontalmente ma illeggibile.
+❌ **Micro-file** (<100 linee) per ogni endpoint — overhead metadata + chunk sovrapposizione.
+
+## Quick check durante scrittura
+
+```bash
+wc -l docs/references/api/my-new-file.md
+```
+
+- >1500 linee → pianifica split PRIMA di finire
+- 1000-1500 → è al limite, verifica se c'è compressione possibile
+- 400-900 → dimensione ottimale
+- <300 → considera merge con file correlato se ha poco contenuto