# Quickstart tenant

Provisioning e bootstrap di un progetto tenant (es. `progetto-x`) con il kit harness.

Due servizi distinti:

| Variabile | Servizio | Uso | Autenticazione |
|---|---|---|---|
| `HARNESS_URL` | canale di distribuzione statico (hs-harness) | `/harness/latest`, `/harness/bundle`, `/harness/bootstrap.sh` | nessuna |
| `KB_URL` | mc2-embed | playbook (PRD) e knowledge base (KRD) | header `X-API-Key` |

La chiave API NON viaggia MAI verso `HARNESS_URL`.

---

## Flusso

```
[1. Amministratore]
    ├── genera la chiave API del tenant (mc2-embed)
    ├── pubblica tenant, playbook e KB (job Jenkins tenant-publish)
    └── consegna TENANT_ID + KB_URL + HARNESS_URL + KB_API_KEY
           │
           ▼
[2. Progetto tenant (progetto-x/)]
    ├── vars.yaml (variabili) e .env (chiave)
    ├── curl ${HARNESS_URL}/harness/bootstrap.sh && bash bootstrap.sh
    │      ├── scarica ${HARNESS_URL}/harness/bundle, verifica ZIP e checksum
    │      ├── materializza release/ (release.zip, bin/wrapper.sh, overrides/, addons/)
    │      ├── scrive release/.version
    │      └── si autocancella (tranne con --local-zip)
    └── cd cwd && <agente>
```

---

## Step 1 — Provisioning (amministratore)

1. Generare la chiave del tenant con lo strumento di mc2-embed:

   ```bash
   # dal repository mc2-embed
   python3 src/mc2_embed/tools/new_api_key.py --name harness-progetto-x --tenant progetto-x
   ```

   Stampa la chiave (mostrata una sola volta) e la voce YAML con il solo SHA-256.
2. Aggiungere la voce al segreto Doppler `MC2_EMBED_API_KEYS` e applicarla con il
   job Jenkins `hs-secrets-sync` (`RECREATE=services/mc2-embed`).
3. Creare il tenant e pubblicarne playbook e KB con il job `tenant-publish`.

Risultato da consegnare:

- `TENANT_ID`: `progetto-x`
- `KB_URL`: `https://embed.oci.mcsquared.it` (oppure `http://127.0.0.1:8080` locale).
- `HARNESS_URL`: `https://harness.oci.mcsquared.it`
- `KB_API_KEY`: la chiave generata

---

## Le tre cartelle

| Cartella | Contenuto | Uso |
|---|---|---|
| Radice | `vars.yaml`, `.env`, `release/` | installazione e aggiornamento del kit; NON è un repository |
| cwd (`<radice>/cwd`) | direttive e script di accesso a mc2-embed; playbook e KB restano su mc2-embed | avvio dell'agente; ricreata a ogni `setup`/`upgrade` |
| Sorgenti (`source_dirs`) | i repository del progetto | autorizzati all'avvio dell'agente (`claude --add-dir <cartella>`) |

---

## Step 2 — `vars.yaml` e `.env`

Nella radice:

```yaml
# vars.yaml — variabili di istanza, iniettate nel contesto di sessione
tenant_id: "progetto-x"
harness_root_dir: "/home/max/projects/progetto-x"            # la radice
kb_url: "https://embed.oci.mcsquared.it"
harness_url: "https://harness.oci.mcsquared.it"
source_dirs:                       # repository sorgenti, fuori dalla radice
  - "/home/max/projects/progetto-x/sources/backend"
```

```env
# .env — segreti, MAI caricati in sessione
KB_API_KEY="<chiave>"
```

---

## Step 3 — Bootstrap

```bash
curl -fsSL "https://harness.oci.mcsquared.it/harness/bootstrap.sh" -o bootstrap.sh
bash bootstrap.sh
```

Offline: `bash bootstrap.sh --local-zip <percorso-release.zip>`.

`bootstrap.sh`:

1. legge `TENANT_ID`, `KB_URL`, `HARNESS_URL` da `vars.yaml` e `KB_API_KEY` da `.env`;
2. scarica `${HARNESS_URL}/harness/bundle` (o usa l'archivio locale);
3. verifica che la risposta sia uno ZIP (magic `PK`) e ne prova l'estrazione;
4. materializza `release/release.zip`, `release/bin/wrapper.sh`, `release/overrides/`, `release/addons/`;
5. registra versione e checksum da `${HARNESS_URL}/harness/latest` in `release/.version`;
6. esegue `./release/bin/wrapper.sh setup` e si autocancella.

---

## Step 4 — Esecuzione

```bash
./release/bin/wrapper.sh setup      # ricostruzione atomica di cwd/
cd cwd && claude --add-dir /home/max/projects/progetto-x/sources/backend
```

---

## Step 5 — Personalizzazioni

- **Override**: `release/overrides/<rel_path>` sostituisce integralmente il file in `cwd/`.
- **Addon**: `release/addons/<rel_path>` si accoda al file in `cwd/`.

`wrapper.sh` rifiuta percorsi con path-traversal.

---

## Step 6 — Aggiornamenti

```bash
./release/bin/wrapper.sh upgrade            # chiede conferma se esiste una release piu' recente
MC2_ASSUME_YES=1 ./release/bin/wrapper.sh upgrade
./release/bin/wrapper.sh upgrade --force    # reinstalla la release pubblicata
```

La release pubblicata e' `${HARNESS_URL}/harness/latest`: versione YYYYMMDD-BUILDNUM
generata da Jenkins (file `VERSION` del repository mc2-harness) con il checksum del bundle. Il bundle
scaricato con checksum diverso NON si installa.