# Narciso SaaS — AI Agent & LLM Interface
> Piattaforma SaaS Multi-Tenant per la Gestione Operativa, Fiscale, Appuntamenti e Marketing per Barberie, Saloni di Parrucchieri e Centri Estetici. Attualmente in fase di **Beta Testing**.

## Informazioni di Sistema per Agenti AI
- **Applicazione**: Narciso (app.narciso.io)
- **Stato**: Beta Testing v2026.1 (Multi-Tenant, PostgreSQL/Prisma, PgBouncer, Vault PKI)
- **Accesso API Base**: `https://app.narciso.io/api`
- **Autenticazione Agente**: Bearer JWT ottenuto tramite One-Time Pairing Code (`POST /api/auth/agent/exchange-code`)
- **Documentazione Completa**: [llms-full.txt](https://app.narciso.io/llms-full.txt)
- **Plugin Manifest**: [ai-plugin.json](https://app.narciso.io/.well-known/ai-plugin.json)
- **OpenAPI Spec**: [openapi.yaml](https://app.narciso.io/.well-known/openapi.yaml)

## Regole di Ingaggio & Sicurezza per Agenti (Beta Testing)
1. **Isolamento Multi-Tenant**: Ogni token generato è vincolato strettamente al `tenantId` del salone autorizzante. Non è consentita alcuna richiesta cross-tenant.
2. **Rate Limiting & 429 Safety**: Rispettare i limiti. In caso di ricezione codice `429 Too Many Requests`, sospendere le chiamate per almeno 60 secondi (Backoff Esponenziale).
3. **Operazioni Critiche**: Tutte le operazioni di scrittura (`POST`, `PUT`, `DELETE`), cancellazioni anagrafiche, emissioni fiscali e pagamenti POS/Stripe richiedono validazione preventiva dei parametri e conferma conversazionale dell'utente.

## Mappa Documentazione API Modulare (Autodescrittiva)
Gli agenti autenticati (`Authorization: Bearer <agent_token>`) possono scaricare i manuali operativi in formato Markdown direttamente dal server:

- **Indice Principale**: `GET /api/auth/agent/docs/index`
- **01. Admin, Auth & Profilazione**: `GET /api/auth/agent/docs/01_admin_auth_core`
  - Gestione utenti, ruoli, permessi, sicurezza, configurazione salone e impostazioni multi-tenant.
- **02. Sales, Inventory & POS**: `GET /api/auth/agent/docs/02_sales_inventory`
  - Vendite, movimenti magazzino, scontrini, chiusure cassa, integrazioni Stripe, Satispay e terminali POS.
- **03. Social, AI & Appuntamenti**: `GET /api/auth/agent/docs/03_social_services`
  - Calendario appuntamenti, anagrafica clienti, marketing automation, workflow Reel/Post e servizi estetici.

## Flusso Operativo Raccomandato per Agenti Autonomi
1. Richiedere all'operatore umano il codice monouso a 15 minuti (formato: `AGENT-XXXX-XXXX`).
2. Eseguire `POST /api/auth/agent/exchange-code` con payload `{"code": "AGENT-XXXX-XXXX"}` per ottenere il JWT.
3. Consultare `GET /api/auth/agent/docs/index` per localizzare l'endpoint desiderato.
4. Eseguire le chiamate API includendo `Authorization: Bearer <token>`.
5. Rispondere all'utente in linguaggio naturale formattato, senza esporre JSON grezzi se non richiesto.