# Onboarding assistito di un remote docs

Usa questo playbook quando un utente chiede di aggiungere un remote `docs-node`
attraverso un agente e `docs_remote`.

## Contratto e sicurezza

- Raccogli l'endpoint HTTP(S) obbligatorio e un nome facoltativo. Se il nome
  manca, proponi un identificatore breve e univoco derivato dall'host o
  dall'ambiente, poi rendilo esplicito prima di salvarlo.
- Proponi un `auth_profile` stabile in maiuscolo, ad esempio
  `DOCS_REMOTE_SOPHIA_DEV01_TOKEN`.
- Non chiedere, stampare, registrare nei documenti o includere nei payload MCP
  il valore del bearer token. Il DB registra solo il nome `auth_profile`.
- Non assumere un file, un sistema operativo o una sintassi di configurazione
  specifica del client.

## Procedura portabile

1. Chiedi all'utente di configurare il valore del token esclusivamente nel
   secret store o nell'ambiente ereditato dal processo MCP del proprio client.
   Se il client e' noto, usa la sua documentazione o configurazione locale; se
   non lo e', chiedi dove riceve le variabili d'ambiente e indica solo nome e
   valore atteso della variabile.
2. Richiedi il riavvio del client o del processo MCP: l'ambiente di un processo
   gia' avviato non viene ricaricato a caldo.
3. Dopo il riavvio, chiama `docs_remote configure_remote` con `name`,
   `base_url` e il solo nome `auth_profile`.
4. Chiama `docs_remote list_remotes`: devono risultare `auth_configured: true`
   e `auth_env_present: true`.
5. Chiama `docs_remote list_remote_shelves` come test end-to-end.
6. Riporta che il DB locale non e' stato alterato e proponi
   `list_remote_tags` e `search_remote` per consultazione read-through.
   Proponi `subscribe_shelf` soltanto se servono offline o sync incrementale.

## Gestione di errori e configurazioni host-specifiche

Se `auth_env_present` e' `false`, non provare il token ne' richiederlo in chat:
spiega che il processo MCP deve ereditare la variabile e ripeti soltanto le
verifiche dopo il riavvio.

Un agente puo' modificare una configurazione del client solo con autorizzazione
esplicita dell'utente e senza riecheggiare il segreto. Le istruzioni
host-specifiche appartengono alla guida locale del client, non a questa skill
portabile.