docs: publish bilingual manual standalone installation guides

.gitignore

@@ -46,6 +46,7 @@ deploy/secrets/*
 # Per-installation configuration generated by `tht setup` (examples stay tracked).
 deploy/*/thothii-installation.yaml
 deploy/*/operator.env
+deploy/*/auth/
 deploy/*/generated/
 deploy/*/secrets/*
 !deploy/*/secrets/.gitkeep

CONTEXT.md

@@ -627,3 +627,17 @@ durante una ripresa, anche se la UI locale corrente cambia.
 **Administrative Page Family** — L'insieme delle cinque Administration Page che condividono shell,
 navigazione, tipografia e regole responsive, pur mantenendo contenuti e operazioni specifici:
 Workspace, Evidence, Memory, Database e Pi.
+
+## Installazione
+
+**Manual standalone installation** — Una copia di ThothII predisposta per l'uso autonomo da una
+persona che possiede il computer, con una Full Thoth Shell e servizi applicativi locali. La
+procedura non implica che DWH o provider LLM siano locali o disponibili offline.
+
+**Installation bootstrap** — L'insieme delle attività iniziali che rende disponibile una
+installazione manuale: verifica dell'host, generazione della configurazione, predisposizione
+delle credenziali protette e avvio dei servizi. Non è un installer dell'applicazione.
+
+**Platform acceptance** — La verifica che una Manual standalone installation possa essere
+predisposta e avviata su una specifica combinazione di sistema operativo, architettura e runtime,
+distinta dalla verifica funzionale del collegamento a DWH e provider LLM.

README.md

@@ -21,6 +21,10 @@ authentication is established by the trusted server proxy. See the
 [upstream integration](docs/install/authentication-upstream.md), and
 [manual acceptance matrix](docs/testing/authentication-manual-acceptance.md).
 
+For the clone-based manual standalone installation test on macOS, Windows, and Linux, use the
+[Italian procedure](docs/install/standalone-manual-it.md) or the
+[English procedure](docs/install/standalone-manual-en.md).
+
 ## Docker Compose: local startup
 
 Requirements: Docker Engine with Compose v2. The mandatory stack is `frontend`, `core`,
@@ -37,7 +41,7 @@ cp deploy/env/local.env.example deploy/env/local.env
 ./scripts/run-stack.sh
 ```
 
-The launcher builds the core, starts `catalog-db`, runs the explicit one-shot Kysely migrations,
+The low-level stack script builds the core, starts `catalog-db`, runs the explicit one-shot Kysely migrations,
 then runs the base+local stack in the foreground. Migrations never run implicitly in backend
 startup. The core image contains its Pi runtime; no host `pi` executable is used. For a server
 installation, build the image, start the catalog, and run the same migration service before the

docs/index.md

@@ -8,6 +8,7 @@ Start with the path that matches the work you need to do:
 | I need to… | Start here |
 | --- | --- |
 | Install or operate one instance | [Install and first start](install/first-start.md) |
+| Clone and manually install on macOS, Windows, or Linux | [Italian procedure](install/standalone-manual-it.md) · [English procedure](install/standalone-manual-en.md) |
 | Upgrade the server and integrate Omics Portal | [Codex server handoff](operations/server-codex-handoff.md) |
 | Choose full/embedded and configure the shell | [Shell and localization](operations/shell-and-localization.md) |
 | Reuse an authenticated server portal without a second login | [Upstream authentication](install/authentication-upstream.md) |

docs/install/first-start.md

@@ -1,5 +1,9 @@
 # Install and first start
 
+For the ordered clone-to-start procedure on Mac, Windows WSL2 and Linux, use the
+[Italian manual guide](standalone-manual-it.md) or [English manual guide](standalone-manual-en.md),
+including protected credentials and the explicit initial catalog migration.
+
 This is the supported local installation path. It creates an installation-local configuration and
 starts the Compose stack; it does not create a workspace repository or a database catalog entry.
 

docs/install/standalone-manual-en.md

@@ -0,0 +1,324 @@
+# Manual standalone installation
+
+[Versione italiana](standalone-manual-it.md)
+
+This is the verification procedure for preparing THothII as a standalone application in `full`
+mode on macOS, Windows, and Linux.
+
+In this document, “standalone” means that the user does not need to install Node.js, Python or Pi
+on the host: the application services and local semantic
+services run through Docker. DWH and LLM providers remain external endpoints configured by the
+installation; this is not an offline package.
+
+This path uses no graphical installer, native launcher, or Docker Hub image. It starts from a Gitea
+clone and uses explicit terminal commands. Publishing pre-built images is a later step.
+
+## Verification matrix
+
+| System | Recommended terminal | Runtime | Test architecture |
+| --- | --- | --- | --- |
+| macOS supported by the installed Docker Desktop version | Bash in Terminal | Docker Desktop | Apple Silicon (`arm64`) |
+| Windows 11 | Ubuntu inside WSL2 | Docker Desktop with WSL2 integration | x64 (`amd64`) |
+| Ubuntu Linux 22.04 or 24.04 | Bash | Docker Engine + Compose v2 | x64 (`amd64`) |
+
+Intel macOS is excluded from the first verification campaign. ARM Linux may be tested when the
+machine’s Docker runtime reports `arm64`, but it is not part of the minimum matrix.
+
+Documentation and Mac prerequisite checks have passed. Complete fresh installations on all three
+systems remain pending; this matrix describes the tests to perform, not completed certification.
+
+## Before you start
+
+You need:
+
+- access to the THothII Gitea repository and the workspace Git repository;
+- Git;
+- Docker Desktop on macOS and Windows, or Docker Engine with the Compose v2 plugin on Linux;
+- Bash, `curl`, OpenSSL and `shasum` (Ubuntu package: `libdigest-sha-perl`);
+- enough disk space to build the images and download the embedding model;
+- the DWH and LLM endpoints, plus the credentials required by the installation.
+
+On Linux, the current user must be able to run Docker. If the system requires `sudo`, add the user
+to the Docker group according to local policy and open a new session before continuing.
+
+On Windows, run every command in this guide from Ubuntu under WSL2. In Docker Desktop, enable WSL2
+integration for that distribution. Clone the project inside the WSL2 Linux filesystem, for example
+under `~/src`, rather than under `/mnt/c`: this avoids slow builds and path/line-ending issues. Pi
+does not need to be installed on the host.
+
+Check the runtime before or immediately after cloning:
+
+```sh
+docker version
+docker compose version
+docker version --format '{{.Server.Arch}}'
+```
+
+The last command must return `amd64`, `x86_64`, `arm64`, or `aarch64`.
+
+## 1. Clone a project revision
+
+Use the project repository on Gitea:
+
+```sh
+mkdir -p "$HOME/src"
+cd "$HOME/src"
+git clone https://git.tylconsulting.it/mptyl/ThothII.git
+cd ThothII
+git rev-parse --short HEAD
+```
+
+For an SSH clone, when the key is already authorized on Gitea:
+
+```sh
+git clone git@git.tylconsulting.it:mptyl/ThothII.git
+```
+
+Record the hash printed by `git rev-parse` for a repeatable test. In a later campaign, use the
+maintainer-approved revision/tag rather than implicitly following a mutable `main` branch.
+
+## 2. Check prerequisites and install the operator command
+
+From the clone root:
+
+```sh
+bash scripts/check-standalone-prerequisites.sh
+export PATH="$HOME/.local/bin:$PATH"
+THT_INSTALL_DIRECTORY="$HOME/.local/bin" bash scripts/install-tht.sh
+tht version
+```
+
+`install-tht.sh` bootstraps only the native `tht` operator command; it does not install a desktop
+version of THothII. It uses the repository’s Docker builder, installs the binary for the current
+terminal environment, and installs it in the user directory. Persist `$HOME/.local/bin` in your
+shell PATH for new terminals too. An existing `tht` in this directory will be updated.
+
+On Windows, run these commands inside WSL2. The installed `tht` binary is the Linux binary inside
+WSL2; the application runtime remains Docker Desktop. Do not use `scripts/install-tht.ps1` as the
+primary path for this test.
+
+## 3. Configure and start the local installation
+
+Run the remaining blocks in one Bash session from the physical clone root (`pwd -P`).
+First create two distinct catalog passwords, preserving any existing files:
+
+```bash
+umask 077
+mkdir -p deploy/local/secrets
+for name in catalog-runtime-password catalog-migrator-password; do
+  target="deploy/local/secrets/$name"
+  if [ ! -e "$target" ]; then
+    (set -C; openssl rand -hex 32 > "$target") || exit 1
+  fi
+done
+export THT_CATALOG_RUNTIME_PASSWORD_SOURCE="$(pwd -P)/deploy/local/secrets/catalog-runtime-password"
+export THT_CATALOG_MIGRATOR_PASSWORD_SOURCE="$(pwd -P)/deploy/local/secrets/catalog-migrator-password"
+```
+
+Do not regenerate passwords for an initialized catalog. Configure without starting services:
+
+```sh
+tht setup --profile local --shell-mode full --shell-default-locale en --configure-only
+```
+
+Answer the prompts as follows:
+
+| Prompt | Value or rule |
+| --- | --- |
+| Installation ID | `local`, unless one clone hosts multiple installations |
+| Deployment profile | `local` |
+| DWH API endpoint | An `http(s)` URL without user, password, query, or fragment; may be empty for a smoke-only test |
+| LLM API endpoint | An `http(s)` URL without credentials; may be empty for a smoke-only test |
+| Workspace repository URL | The workspace repository URL, not the THothII source clone |
+| Workspace branch | Normally `main` |
+| Workspace access | `ssh` with a deploy key, or `https` with a protected credential file |
+| File paths | Accept the default paths under `deploy/local/secrets/` for the first test |
+| Secret templates | Answer `yes` when protected files do not exist yet |
+| Authentication | Configure the local login required by the installation; never put passwords on a command line |
+
+The generated configuration is local and ignored by Git:
+
+```text
+deploy/local/thothii-installation.yaml
+deploy/local/operator.env
+deploy/local/auth/
+deploy/local/secrets/
+```
+
+Edit secrets only in protected local files; never commit them. `deploy/env/local.env.example` is a tracked reference; the
+generated path `deploy/local/operator.env` is the active path for this installation.
+
+### Complete protected files
+
+If setup created blank templates, enter the values with a local editor:
+
+```sh
+chmod 600 deploy/local/secrets/*
+"${EDITOR:-vi}" deploy/local/secrets/thothii.secrets
+```
+
+The bundle must contain only `KEY=VALUE` lines for credentials actually used by `modelCatalog`. The
+allowed names and credential boundary are documented in the local file
+`deploy/secrets/README.md`. Do not put tokens in URLs, the YAML
+descriptor, the Git repository, or commands copied into the shell.
+
+For SSH workspace access, also provide the private key and `known_hosts` file requested by setup.
+For HTTPS access, provide the Git credential file and any required CA. Both must remain protected
+and outside version control.
+
+Before starting, complete these additional configuration steps:
+
+1. Add `THT_CATALOG_RUNTIME_PASSWORD_SOURCE` and `THT_CATALOG_MIGRATOR_PASSWORD_SOURCE` to
+   `deploy/local/operator.env`, with the same absolute paths exported above. Setup does not persist
+   these two variables. Store paths, not passwords.
+2. Replace the descriptor's generic `modelCatalog` with the approved provider/model configuration.
+   The generated defaults do not replicate the existing Mac. See [Pi/model configuration](../general/pi-configuration.md)
+   and the local example `deploy/psd/thothii-installation.yaml.example`.
+3. Populate the keys referenced by `authentication.apiKeyEnv` in `thothii.secrets`. Providers using
+   `pi_auth` need valid credentials at `PI_AUTH_FILE`; the `{}` template is not authentication.
+4. Complete the workspace Git files. SSH requires an authorized deploy key and verified known-hosts;
+   HTTPS requires the credential file and CA bundle expected by the overlay. Blank templates cannot
+   provide repository access.
+
+After editing generated configuration, do not rerun setup: it rejects different existing content.
+Generate the projections and run the explicit migration below. Use `THT_GIT_ACCESS=https` if that
+was selected during setup. This block targets the fresh `local` descriptor with only the Git overlay;
+custom installations must include their extra descriptor overlays in the same order.
+
+```bash
+INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
+tht --installation "$INSTALLATION" installation generate
+THT_PROJECT="thothii-$(printf '%s' "$INSTALLATION" | shasum -a 256 | cut -c 1-12)"
+THT_GIT_ACCESS=ssh
+compose=(
+  docker compose --project-name "$THT_PROJECT" --project-directory "$(pwd -P)"
+  --env-file "$(pwd -P)/deploy/local/operator.env"
+  -f compose.yaml -f deploy/compose.local.yaml
+  -f "deploy/compose.git-$THT_GIT_ACCESS.yaml"
+  -f deploy/local/generated/compose.models.yaml
+)
+"${compose[@]}" config --quiet
+"${compose[@]}" build core frontend
+"${compose[@]}" up -d catalog-db
+"${compose[@]}" run --rm catalog-migrate
+tht --installation "$INSTALLATION" start
+```
+
+Stop if a command fails. The project name matches the hash used by `tht`, preserving volume
+identity. `catalog-migrate` applies Catalog and Memory migrations; `tht start` does not run it
+automatically. Initial embedding-model download may take time. Use this installation-specific
+sequence, not `run-stack.sh` with a different environment/project name.
+
+## 4. Verify the installation
+
+The descriptor generated for the default ID is:
+
+```sh
+INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
+test -f "$INSTALLATION"
+bash scripts/verify-standalone-install.sh "$INSTALLATION"
+```
+
+The verifier is read-only: it runs `tht doctor --json` and `tht status` without restarting the
+stack, regenerating configuration, or printing secret contents.
+
+### Gate A — platform smoke test on all three computers
+
+Record the following for each machine:
+
+```sh
+uname -a
+docker version --format '{{.Server.Version}} {{.Server.Arch}}'
+tht version
+bash scripts/check-standalone-prerequisites.sh
+bash scripts/verify-standalone-install.sh "$INSTALLATION"
+```
+
+The gate passes when the clone is intact, Docker and Compose are reachable, `tht doctor` is OK, the
+stack is running, and the frontend responds at the default local URL `http://127.0.0.1:8080`.
+Doctor also checks workspace and Pi: record their failures separately rather than labeling every
+failure as a platform problem. Check HTTP readiness with:
+
+```sh
+curl --fail --silent --show-error http://127.0.0.1:8080/health
+```
+
+### Gate B — functional verification
+
+Run this on at least one machine with available endpoints and credentials:
+
+First follow [Workspace operations](../operations/workspaces.md) to import/prepare the workspace
+and configure the Database and local binding. The source clone does not transfer catalog data,
+secrets or sessions from the Mac. Connect any VPN required by DWH/model endpoints and verify
+that their names are reachable from containers too.
+
+1. open `http://127.0.0.1:8080`;
+2. sign in with the configured local account;
+3. verify that the configured workspace is readable;
+4. start a real question and complete the review gates through final SQL;
+5. stop and restart the installation, then run `verify-standalone-install.sh` again.
+
+A Gate B failure involving DWH, the LLM provider, workspace Git, or credentials does not by itself
+prove a Docker portability problem: record the failed endpoint or component separately.
+
+## Daily lifecycle
+
+Use the explicit descriptor when more than one installation may be discoverable:
+
+```sh
+INSTALLATION="$PWD/deploy/local/thothii-installation.yaml"
+
+tht --installation "$INSTALLATION" status
+tht --installation "$INSTALLATION" start
+tht --installation "$INSTALLATION" start --build
+tht --installation "$INSTALLATION" logs
+tht --installation "$INSTALLATION" doctor --json
+tht --installation "$INSTALLATION" stop
+```
+
+Use `start --build` after source changes or to rebuild images from the current checkout. `stop`
+preserves volumes, sessions, the catalog, Pi state, Qdrant data, and the embedding model. Do not
+use `docker compose down --volumes` during a normal test: it is destructive and removes local data.
+For upgrades requiring migrations, follow the release runbook before starting the new application.
+
+## Quick diagnosis
+
+| Symptom | Check |
+| --- | --- |
+| `Docker Engine is not reachable` | start Docker Desktop or the Docker service and rerun `docker info` |
+| Windows sees Docker but Bash fails | run the guide inside Ubuntu WSL2 and enable that distribution in Docker Desktop |
+| `tht: command not found` | open a new shell and check `command -v tht`; rerun the bootstrap if needed |
+| line-ending or executable-script errors | use a clone in the WSL2/Linux filesystem and rerun `bash scripts/...` |
+| unsupported architecture | check `docker version --format '{{.Server.Arch}}'`; the test requires `amd64` or `arm64` |
+| missing descriptor or env file | use `deploy/local/...` generated by `tht setup`, not an arbitrary copied file |
+| healthy stack but workflow failure | check external URLs, the credential bundle, workspace Git, and authentication separately |
+| data appears missing | check that `down --volumes` was not used; `stop` does not remove volumes |
+
+## Acceptance checklist
+
+- [ ] The clone comes from the expected Gitea repository and the revision is recorded.
+- [ ] Docker Desktop/Engine and Compose v2 are available.
+- [ ] The runtime reports an allowed architecture.
+- [ ] `tht` was built from the repository and responds to `tht version`.
+- [ ] Setup uses `profile: local`, `shell.mode: full`, and `shell.defaultLocale: en`.
+- [ ] The descriptor, `operator.env`, authentication, and secrets exist only under `deploy/local/`.
+- [ ] No secret appears in Git, URLs, public YAML, or recorded commands.
+- [ ] Gate A passes on Apple Silicon macOS, x64 Windows WSL2, and x64 Linux.
+- [ ] Gate B runs on at least one machine with DWH and LLM available.
+- [ ] Stop/start and final verification complete without deleting volumes.
+
+## Out of scope for this release
+
+The following remain future work:
+
+- publishing pre-built images on Docker Hub;
+- reducing prompts through a dedicated non-interactive configuration;
+- creating DMG, MSI/EXE, AppImage, or other native installers;
+- providing an offline runtime or bundling a local DWH/LLM into the application.
+
+## Related documents
+
+- [Install and first start](first-start.md)
+- [Shell and localization](../operations/shell-and-localization.md)
+- [Workspace operations](../operations/workspaces.md)
+- `deploy/secrets/README.md` (runtime secrets)

docs/install/standalone-manual-it.md

@@ -0,0 +1,329 @@
+# Installazione manuale standalone
+
+[English version](standalone-manual-en.md)
+
+Questa è la procedura di prova per predisporre THothII come applicazione autonoma in modalità
+`full` su macOS, Windows e Linux.
+
+In questo documento “autonoma” significa che l’utente non deve installare Node.js, Python o Pi
+sull'host: i servizi applicativi e i servizi semantici
+locali vengono eseguiti con Docker. DWH e provider LLM restano endpoint esterni configurati
+dall’installazione; questa procedura non è un pacchetto offline.
+
+Il percorso non usa installer grafici, launcher nativi o immagini Docker Hub. Si parte da un clone
+Gitea e si usano comandi espliciti da terminale. La pubblicazione di immagini pre-costruite è una
+fase successiva.
+
+## Matrice di verifica
+
+| Sistema | Terminale raccomandato | Runtime | Architettura della prova |
+| --- | --- | --- | --- |
+| macOS supportato dalla versione Docker Desktop installata | Bash nel Terminale | Docker Desktop | Apple Silicon (`arm64`) |
+| Windows 11 | Ubuntu dentro WSL2 | Docker Desktop con integrazione WSL2 | x64 (`amd64`) |
+| Linux Ubuntu 22.04 o 24.04 | Bash | Docker Engine + Compose v2 | x64 (`amd64`) |
+
+Intel macOS non fa parte della prima campagna di verifica. ARM Linux può essere provato quando il
+runtime Docker della macchina restituisce `arm64`, ma non è un requisito della matrice minima.
+
+Le verifiche documentali e dei prerequisiti Mac sono passate. Le installazioni complete da zero
+sui tre sistemi restano da eseguire: la matrice indica le prove previste, non una certificazione.
+
+## Cosa serve prima di iniziare
+
+Servono:
+
+- accesso al repository Gitea di THothII e al repository Git dei workspace;
+- Git;
+- Docker Desktop su macOS e Windows, oppure Docker Engine con il plugin Compose v2 su Linux;
+- Bash, `curl`, OpenSSL e `shasum` (su Ubuntu, pacchetto `libdigest-sha-perl`);
+- spazio disco sufficiente per compilare le immagini e scaricare il modello di embedding;
+- gli endpoint DWH e LLM, più le credenziali che l’installazione deve usare.
+
+Su Linux l’utente corrente deve poter eseguire Docker. Se il sistema richiede `sudo`, aggiungere
+l’utente al gruppo Docker secondo la policy locale e aprire una nuova sessione prima di continuare.
+
+Su Windows usare Ubuntu in WSL2 per tutti i comandi di questa guida. In Docker Desktop attivare
+l’integrazione WSL2 per quella distribuzione. Clonare il progetto nel filesystem Linux di WSL2,
+per esempio sotto `~/src`, e non sotto `/mnt/c`: si evitano rallentamenti e problemi di permessi o
+line ending. Non è necessario installare Pi sull’host.
+
+Verificare il runtime prima del clone o subito dopo:
+
+```sh
+docker version
+docker compose version
+docker version --format '{{.Server.Arch}}'
+```
+
+L’ultima istruzione deve restituire `amd64`, `x86_64`, `arm64` o `aarch64`.
+
+## 1. Clonare una revisione del progetto
+
+Usare il repository di progetto su Gitea:
+
+```sh
+mkdir -p "$HOME/src"
+cd "$HOME/src"
+git clone https://git.tylconsulting.it/mptyl/ThothII.git
+cd ThothII
+git rev-parse --short HEAD
+```
+
+Per un clone SSH usare, se la chiave è già autorizzata su Gitea:
+
+```sh
+git clone git@git.tylconsulting.it:mptyl/ThothII.git
+```
+
+Per una prova ripetibile annotare l’hash stampato da `git rev-parse`. In una campagna successiva
+usare la revisione/tag approvata dal maintainer invece di seguire implicitamente una `main` che
+può cambiare.
+
+## 2. Verificare i prerequisiti e installare il comando operatore
+
+Dal root del clone:
+
+```sh
+bash scripts/check-standalone-prerequisites.sh
+export PATH="$HOME/.local/bin:$PATH"
+THT_INSTALL_DIRECTORY="$HOME/.local/bin" bash scripts/install-tht.sh
+tht version
+```
+
+`install-tht.sh` è un bootstrap del solo comando operatore nativo `tht`; non installa una versione
+desktop di THothII. Usa il builder Docker del repository, installa il binario adatto all’ambiente
+del terminale e lo installa nella directory utente. Aggiungere `$HOME/.local/bin` al PATH della
+shell anche per i terminali successivi. Un `tht` già presente in quella directory viene aggiornato.
+
+Su Windows, eseguire questi comandi dentro WSL2. Il binario `tht` installato è quello Linux di WSL2;
+il runtime dell’applicazione rimane Docker Desktop. Non usare `scripts/install-tht.ps1` come percorso
+principale di questa prova.
+
+## 3. Configurare e avviare l’installazione locale
+
+Eseguire i blocchi successivi nella stessa sessione Bash dal root fisico del clone (`pwd -P`).
+Creare prima le due password distinte del catalogo, conservando eventuali file già esistenti:
+
+```bash
+umask 077
+mkdir -p deploy/local/secrets
+for name in catalog-runtime-password catalog-migrator-password; do
+  target="deploy/local/secrets/$name"
+  if [ ! -e "$target" ]; then
+    (set -C; openssl rand -hex 32 > "$target") || exit 1
+  fi
+done
+export THT_CATALOG_RUNTIME_PASSWORD_SOURCE="$(pwd -P)/deploy/local/secrets/catalog-runtime-password"
+export THT_CATALOG_MIGRATOR_PASSWORD_SOURCE="$(pwd -P)/deploy/local/secrets/catalog-migrator-password"
+```
+
+Non rigenerare le password di un catalogo già inizializzato. Configurare senza avviare i servizi:
+
+```sh
+tht setup --profile local --shell-mode full --shell-default-locale en --configure-only
+```
+
+Rispondere ai prompt nel seguente modo:
+
+| Prompt | Valore o regola |
+| --- | --- |
+| Installation ID | `local`, salvo necessità di più installazioni nello stesso clone |
+| Deployment profile | `local` |
+| DWH API endpoint | URL `http(s)` senza user, password, query o fragment; può restare vuoto per il solo smoke test |
+| LLM API endpoint | URL `http(s)` senza credenziali; può restare vuoto per il solo smoke test |
+| Workspace repository URL | URL del repository dei workspace, non il clone sorgente di THothII |
+| Workspace branch | normalmente `main` |
+| Workspace access | `ssh` se si usa una chiave deploy; altrimenti `https` con credential file protetto |
+| Percorsi dei file | accettare i percorsi predefiniti sotto `deploy/local/secrets/` nella prima prova |
+| Secret templates | rispondere `yes` quando i file protetti non esistono ancora |
+| Autenticazione | configurare il login locale richiesto dall’installazione; non inserire password in una riga di comando |
+
+La configurazione generata è locale e ignorata da Git:
+
+```text
+deploy/local/thothii-installation.yaml
+deploy/local/operator.env
+deploy/local/auth/
+deploy/local/secrets/
+```
+
+Modificare i segreti solo nei file locali protetti; non committarli. Il file `deploy/env/local.env.example` è un riferimento
+tracciato; il percorso generato da `tht setup`, `deploy/local/operator.env`, è quello da usare per
+questa installazione.
+
+### Completare i file protetti
+
+Se il setup ha creato template vuoti, inserire i valori con un editor locale:
+
+```sh
+chmod 600 deploy/local/secrets/*
+"${EDITOR:-vi}" deploy/local/secrets/thothii.secrets
+```
+
+Il bundle deve contenere solo righe `KEY=VALUE` per le credenziali effettivamente usate dal
+`modelCatalog`. I nomi ammessi e il confine delle credenziali sono descritti nel file locale
+`deploy/secrets/README.md`. Non mettere token nelle URL, nel
+descriptor YAML, nel repository Git o nei comandi copiati nella shell.
+
+Per accesso workspace SSH, predisporre anche la chiave privata e il file `known_hosts` indicati dal
+setup. Per accesso HTTPS, predisporre il credential file Git e l’eventuale CA. Entrambi devono
+restare protetti e fuori dal controllo versione.
+
+Prima dell'avvio completare anche questi passaggi:
+
+1. Aggiungere `THT_CATALOG_RUNTIME_PASSWORD_SOURCE` e `THT_CATALOG_MIGRATOR_PASSWORD_SOURCE` a
+   `deploy/local/operator.env`, con gli stessi percorsi assoluti esportati sopra. Il setup non salva
+   queste due variabili. Inserire i percorsi, non le password.
+2. Sostituire il `modelCatalog` generico nel descriptor con la configurazione provider/modelli
+   approvata. I default generati non replicano il Mac esistente. Vedere [configurazione Pi/modelli](../general/pi-configuration.md)
+   e l'esempio locale `deploy/psd/thothii-installation.yaml.example`.
+3. Inserire in `thothii.secrets` le chiavi referenziate da `authentication.apiKeyEnv`. I provider
+   `pi_auth` richiedono credenziali valide nel file `PI_AUTH_FILE`; il template `{}` non autentica.
+4. Completare i file Git del workspace. SSH richiede una chiave deploy autorizzata e known-hosts
+   verificato; HTTPS richiede il credential file e il bundle CA previsti dall'overlay. I template
+   vuoti non consentono l'accesso al repository.
+
+Dopo aver modificato la configurazione generata, non rilanciare setup: rifiuta file esistenti con
+contenuti diversi. Generare le proiezioni ed eseguire la migrazione esplicita indicata sotto.
+Impostare `THT_GIT_ACCESS=https` se scelto nel setup. Il blocco usa il nuovo descriptor `local`
+con il solo overlay Git; per installazioni personalizzate includere gli overlay aggiuntivi
+nello stesso ordine del descriptor.
+
+```bash
+INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
+tht --installation "$INSTALLATION" installation generate
+THT_PROJECT="thothii-$(printf '%s' "$INSTALLATION" | shasum -a 256 | cut -c 1-12)"
+THT_GIT_ACCESS=ssh
+compose=(
+  docker compose --project-name "$THT_PROJECT" --project-directory "$(pwd -P)"
+  --env-file "$(pwd -P)/deploy/local/operator.env"
+  -f compose.yaml -f deploy/compose.local.yaml
+  -f "deploy/compose.git-$THT_GIT_ACCESS.yaml"
+  -f deploy/local/generated/compose.models.yaml
+)
+"${compose[@]}" config --quiet
+"${compose[@]}" build core frontend
+"${compose[@]}" up -d catalog-db
+"${compose[@]}" run --rm catalog-migrate
+tht --installation "$INSTALLATION" start
+```
+
+Fermarsi se un comando fallisce. Il nome progetto coincide con l'hash usato da `tht`, preservando
+l'identità dei volumi. `catalog-migrate` applica le migrazioni Catalog e Memory; `tht start` non
+lo esegue automaticamente. Il primo download del modello embedding può richiedere tempo.
+Usare questa sequenza legata all'installazione, non `run-stack.sh` con env/progetto diversi.
+
+## 4. Verificare l’installazione
+
+Il descriptor generato per l’ID predefinito è:
+
+```sh
+INSTALLATION="$(pwd -P)/deploy/local/thothii-installation.yaml"
+test -f "$INSTALLATION"
+bash scripts/verify-standalone-install.sh "$INSTALLATION"
+```
+
+Il verificatore è read-only: esegue `tht doctor --json` e `tht status`, senza ristartare lo stack,
+rigenerare la configurazione o stampare il contenuto dei segreti.
+
+### Gate A — smoke di piattaforma, su tutti e tre i computer
+
+Registrare per ogni macchina:
+
+```sh
+uname -a
+docker version --format '{{.Server.Version}} {{.Server.Arch}}'
+tht version
+bash scripts/check-standalone-prerequisites.sh
+bash scripts/verify-standalone-install.sh "$INSTALLATION"
+```
+
+Il gate passa quando il clone è integro, Docker e Compose sono raggiungibili, `tht doctor` è OK,
+lo stack è avviato e il frontend risponde sulla porta locale predefinita `http://127.0.0.1:8080`.
+Il doctor controlla anche workspace e Pi: registrare separatamente i loro errori senza attribuire
+ogni fallimento alla piattaforma. Verificare la disponibilità HTTP con:
+
+```sh
+curl --fail --silent --show-error http://127.0.0.1:8080/health
+```
+
+### Gate B — verifica funzionale
+
+Eseguire almeno su una macchina con endpoint e credenziali disponibili:
+
+Seguire prima [Workspace operations](../operations/workspaces.md) per importare/preparare il
+workspace e configurare Database e binding locale. Il clone sorgente non trasferisce catalogo,
+segreti o sessioni del Mac. Connettere l'eventuale VPN richiesta da DWH/modelli e verificare
+che i relativi nomi siano raggiungibili anche dai container.
+
+1. aprire `http://127.0.0.1:8080`;
+2. autenticarsi con l’account locale configurato;
+3. verificare che il workspace configurato sia leggibile;
+4. avviare una domanda reale e completare i gate di revisione fino alla SQL finale;
+5. fermare e riavviare l’installazione, poi ripetere `verify-standalone-install.sh`.
+
+Un fallimento del Gate B per DWH, provider LLM, Git workspace o credenziali non dimostra da solo un
+problema di portabilità Docker: registrare separatamente l’endpoint o il componente fallito.
+
+## Ciclo di vita quotidiano
+
+Usare il descriptor esplicito quando più installazioni possono essere scoperte:
+
+```sh
+INSTALLATION="$PWD/deploy/local/thothii-installation.yaml"
+
+tht --installation "$INSTALLATION" status
+tht --installation "$INSTALLATION" start
+tht --installation "$INSTALLATION" start --build
+tht --installation "$INSTALLATION" logs
+tht --installation "$INSTALLATION" doctor --json
+tht --installation "$INSTALLATION" stop
+```
+
+`start --build` è necessario dopo una modifica al codice o per ricostruire le immagini dal clone
+corrente. `stop` conserva volumi, sessioni, catalogo, stato Pi, dati Qdrant e modello embedding.
+Non usare `docker compose down --volumes` durante una prova normale: è un’operazione distruttiva
+che cancella i dati locali.
+Per aggiornamenti che richiedono migrazioni, seguire il runbook della release prima dell'avvio.
+
+## Diagnosi rapida
+
+| Sintomo | Controllo |
+| --- | --- |
+| `Docker Engine is not reachable` | avviare Docker Desktop oppure il servizio Docker e ripetere `docker info` |
+| Windows vede Docker ma Bash fallisce | eseguire la guida dentro Ubuntu WSL2 e abilitare l’integrazione della distribuzione in Docker Desktop |
+| `tht: command not found` | aprire una nuova shell e verificare `command -v tht`; se necessario ripetere il bootstrap |
+| line ending o script non eseguibile | usare un clone nel filesystem WSL2/Linux e rieseguire `bash scripts/...` |
+| architettura non supportata | verificare `docker version --format '{{.Server.Arch}}'`; la prova richiede `amd64` o `arm64` |
+| descriptor o env file mancanti | usare il percorso `deploy/local/...` generato da `tht setup`, non un file copiato casualmente |
+| stack sano ma workflow fallisce | controllare separatamente URL, credential bundle, workspace Git e autenticazione |
+| dati apparentemente persi | verificare che non sia stato usato `down --volumes`; `stop` non rimuove i volumi |
+
+## Checklist di accettazione
+
+- [ ] Il clone proviene dal repository Gitea atteso e la revisione è stata annotata.
+- [ ] Docker Desktop/Engine e Compose v2 sono disponibili.
+- [ ] Il runtime restituisce un’architettura ammessa.
+- [ ] `tht` è stato costruito dal repository e risponde a `tht version`.
+- [ ] Il setup usa `profile: local`, `shell.mode: full` e `shell.defaultLocale: en`.
+- [ ] Descriptor, `operator.env`, autenticazione e segreti sono presenti solo in `deploy/local/`.
+- [ ] Nessun segreto compare in Git, URL, YAML pubblico o comandi registrati.
+- [ ] Gate A superato su macOS Apple Silicon, Windows WSL2/x64 e Linux x64.
+- [ ] Gate B eseguito almeno su una macchina con DWH e LLM disponibili.
+- [ ] Stop/start e verifica finale completati senza cancellare i volumi.
+
+## Fuori perimetro di questa release
+
+Restano attività successive:
+
+- pubblicare immagini pre-costruite su Docker Hub;
+- ridurre ulteriormente i prompt tramite una configurazione non interattiva dedicata;
+- creare pacchetti DMG, MSI/EXE, AppImage o altri installer nativi;
+- fornire un runtime offline o un DWH/LLM locale incluso nell’applicazione.
+
+## Documenti collegati
+
+- [Install and first start](first-start.md)
+- [Shell and localization](../operations/shell-and-localization.md)
+- [Workspace operations](../operations/workspaces.md)
+- `deploy/secrets/README.md` (runtime secrets)

docs/plans/2026-09-14-manual-standalone-installation.md

@@ -0,0 +1,99 @@
+# Piano per l’installazione manuale standalone
+
+**Stato:** design concordato con grill-with-docs il 2026-09-14. Questo worktree definisce e rende
+verificabile il percorso manuale; non introduce pacchetti nativi.
+
+## Obiettivo
+
+Permettere di predisporre una copia di THothII su macOS, Windows e Linux partendo dal clone del
+repository Gitea, con una configurazione locale breve e una sequenza di comandi espliciti da
+terminale.
+
+“Standalone” indica una Full Thoth Shell con servizi applicativi e semantici locali eseguiti da
+Docker. DWH e provider LLM restano configurazioni esterne dell’installazione. Non si promette un
+runtime offline.
+
+## Decisioni concordate
+
+| Decisione | Scelta |
+| --- | --- |
+| Distribuzione | clone del repository Gitea |
+| Esperienza di installazione | comandi manuali, senza installer grafico, launcher o wrapper nativo |
+| Runtime applicativo | Docker Compose del repository |
+| Bootstrap host | `scripts/install-tht.sh` installa soltanto il comando operatore `tht` |
+| Configurazione | setup locale interattivo, con percorsi predefiniti e file protetti separati |
+| Modalità shell | `full`, locale, con `defaultLocale: en` |
+| Windows | Ubuntu in WSL2 con integrazione Docker Desktop |
+| Architetture iniziali | macOS Apple Silicon, Windows x64, Linux x64 |
+| Immagini pre-costruite | Docker Hub in uno step successivo |
+| Verifica | Gate A di piattaforma su tre host; Gate B funzionale su almeno un host |
+| Documentazione | due guide sincronizzate, italiano e inglese |
+
+## Sequenza operativa canonica
+
+1. Installare Git, Docker Desktop oppure Docker Engine + Compose v2 e Bash.
+2. Su Windows, predisporre WSL2 Ubuntu e abilitarne l’integrazione in Docker Desktop.
+3. Clonare `https://git.tylconsulting.it/mptyl/ThothII.git` e annotare la revisione.
+4. Eseguire `scripts/check-standalone-prerequisites.sh`.
+5. Eseguire `scripts/install-tht.sh` e verificare `tht version`.
+6. Preparare le due password catalogo ed eseguire `tht setup --profile local --shell-mode full --shell-default-locale en --configure-only`.
+7. Completare file protetti, percorsi password in `operator.env` e catalogo modelli; generare le
+   proiezioni, costruire le immagini, avviare `catalog-db`, eseguire `catalog-migrate` e `tht start`
+   sullo stesso progetto Compose (sequenza completa nelle due guide).
+8. Eseguire `scripts/verify-standalone-install.sh` passando il descriptor generato.
+9. Registrare separatamente il risultato del Gate A e del Gate B.
+
+`tht setup` genera `deploy/local/thothii-installation.yaml` e `deploy/local/operator.env`, prepara
+le proiezioni runtime e valida Compose; `--configure-only` rimanda build e avvio fino al
+completamento della configurazione e della migrazione. Il file tracciato
+`deploy/env/local.env.example` resta un riferimento; non è il descriptor attivo della procedura
+generata.
+
+## Contratti di sicurezza
+
+- I segreti non entrano nel clone, nel descriptor YAML, nelle URL, nei log o negli argomenti della
+  shell.
+- I file in `deploy/local/` sono ignorati da Git e restano sotto il controllo dell’operatore.
+- Il bundle `thothii.secrets` usa righe `KEY=VALUE` e contiene solo le credenziali richieste dai
+  provider selezionati.
+- L’accesso Git del workspace usa un file credential protetto oppure una chiave SSH e `known_hosts`;
+  il clone sorgente e il repository workspace restano distinti.
+- `stop`, `start` e `doctor` sono operazioni di lifecycle; `down --volumes` è distruttivo e non fa
+  parte della prova normale.
+
+## Matrice di accettazione
+
+| Gate | Host | Esito richiesto |
+| --- | --- | --- |
+| A | macOS Apple Silicon | clone, Docker/Compose, build, setup, doctor e frontend locali OK |
+| A | Windows 11 x64 + WSL2 | stessi controlli eseguiti dalla shell Ubuntu WSL2 |
+| A | Ubuntu Linux x64 | stessi controlli con Docker Engine + Compose v2 |
+| B | almeno uno dei tre host | login, workspace leggibile, domanda reale fino alla SQL finale, stop/start OK |
+
+Un errore del DWH, del provider LLM, del repository workspace o delle credenziali viene registrato
+come errore funzionale/configurativo distinto dal risultato di portabilità Docker.
+
+## Artefatti del worktree
+
+- `docs/install/standalone-manual-it.md`: procedura italiana utilizzabile durante l’installazione;
+- `docs/install/standalone-manual-en.md`: versione inglese sincronizzata;
+- `scripts/check-standalone-prerequisites.sh`: controllo read-only dell’host;
+- `scripts/verify-standalone-install.sh`: controllo read-only dell’installazione avviata;
+- aggiornamento di navigazione e contratto documentale;
+- questo piano come riferimento per il successivo lavoro di packaging.
+
+## Evoluzioni escluse
+
+Non fanno parte di questa fase DMG, MSI/EXE, AppImage, wrapper nativi, installazione automatica di
+Docker, immagini Docker Hub, configurazione non interattiva completa, DWH locale o LLM locale.
+
+La prossima evoluzione consigliata è pubblicare immagini versionate e ripetere la stessa matrice
+senza build dal sorgente. Solo dopo una prova riuscita sui tre host sarà opportuno valutare una
+configurazione ridotta e, separatamente, eventuali pacchetti nativi.
+
+## Revisione per pubblicazione — 2026-09-15
+
+Le guide separano configurazione e avvio, includono password e migrazioni Catalog/Memory,
+richiedono di completare il catalogo modelli e distinguono la verifica del doctor dalle dipendenze
+esterne. Le directory di autenticazione locali sono escluse da Git. Le prove complete da clone
+sui tre sistemi restano pendenti; il controllo documentale non le sostituisce.

mkdocs.yml

@@ -46,6 +46,8 @@ nav:
 - Home: index.md
 - Install and operate:
   - Install and first start: install/first-start.md
+  - Manual standalone installation (Italian): install/standalone-manual-it.md
+  - Manual standalone installation (English): install/standalone-manual-en.md
   - Server upgrade from legacy release: operations/server-upgrade-gitea-workspace-v2.md
   - Preprocessing-complete server handoff: operations/server-handoff-260906-preprocessing-complete.md
   - Local authentication: install/authentication-local.md

scripts/check-standalone-prerequisites.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# Check the host prerequisites for the manual standalone installation path.
+set -euo pipefail
+
+fail() {
+  echo "check-standalone-prerequisites.sh: $*" >&2
+  exit 1
+}
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || fail "required command is missing: $1"
+}
+
+require_command git
+require_command docker
+require_command bash
+require_command curl
+require_command openssl
+require_command shasum
+
+docker info >/dev/null 2>&1 || fail "Docker Engine is not reachable; start Docker Desktop or the Docker service"
+
+compose_version=$(docker compose version --short 2>/dev/null) || {
+  fail "Docker Compose v2 is not available as 'docker compose'"
+}
+[[ -n "$compose_version" ]] || fail "Docker Compose returned no version"
+
+server_arch=$(docker version --format '{{.Server.Arch}}' 2>/dev/null) || {
+  fail "could not determine the Docker server architecture"
+}
+server_arch_lower=$(printf '%s' "$server_arch" | tr '[:upper:]' '[:lower:]')
+case "$server_arch_lower" in
+  amd64|x86_64|arm64|aarch64) ;;
+  *) fail "unsupported Docker server architecture: $server_arch (expected amd64 or arm64)" ;;
+esac
+
+printf 'Manual standalone prerequisites passed.\n'
+printf '  Docker Compose: %s\n' "$compose_version"
+printf '  Docker architecture: %s\n' "$server_arch"
+printf '  Host shell: %s\n' "$(uname -s)/$(uname -m)"
+
+if command -v tht >/dev/null 2>&1; then
+  printf '  tht: %s\n' "$(command -v tht)"
+else
+  printf '  tht: not installed yet (run bash scripts/install-tht.sh next)\n'
+fi

scripts/verify-standalone-install.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Verify an already configured and running manual standalone installation.
+set -euo pipefail
+
+fail() {
+  echo "verify-standalone-install.sh: $*" >&2
+  exit 1
+}
+
+[[ $# -eq 1 ]] || fail "usage: $0 /absolute/path/to/thothii-installation.yaml"
+installation=$1
+[[ "$installation" = /* ]] || fail "installation path must be absolute"
+[[ -f "$installation" ]] || fail "installation descriptor not found: $installation"
+
+command -v tht >/dev/null 2>&1 || fail "tht is not on PATH; run bash scripts/install-tht.sh first"
+
+printf '%s\n' 'Running read-only installation doctor...'
+tht --installation "$installation" doctor --json
+printf '%s\n' 'Installation status:'
+tht --installation "$installation" status
+printf '%s\n' 'Manual standalone installation verification passed.'

scripts/verify-workspace-install-docs.sh

@@ -59,6 +59,8 @@ verify_navigation() {
   local path
   for path in \
     install/first-start.md \
+    install/standalone-manual-it.md \
+    install/standalone-manual-en.md \
     operations/workspaces.md \
     operations/database-management.md \
     guida-utente.md \
@@ -70,6 +72,26 @@ verify_navigation() {
   echo "Current documentation navigation contract passed"
 }
 
+verify_standalone_installation_guides() {
+  for guide in docs/install/standalone-manual-it.md docs/install/standalone-manual-en.md; do
+    require_file "$guide"
+    for text in \
+      'git clone https://git.tylconsulting.it/mptyl/ThothII.git' \
+      'scripts/check-standalone-prerequisites.sh' \
+      'scripts/install-tht.sh' \
+      'tht setup --profile local --shell-mode full --shell-default-locale en' \
+      'scripts/verify-standalone-install.sh' \
+      'Docker Hub' \
+      'Gate A' \
+      'Gate B'; do
+      require_text "$guide" "$text"
+    done
+  done
+  require_file scripts/check-standalone-prerequisites.sh
+  require_file scripts/verify-standalone-install.sh
+  echo "Manual standalone installation guides contract passed"
+}
+
 verify_install_and_workspace_guides() {
   local install='docs/install/first-start.md'
   local workspace='docs/operations/workspaces.md'
@@ -134,6 +156,7 @@ PY
 verify_all() {
   verify_compose_topology
   verify_navigation
+  verify_standalone_installation_guides
   verify_install_and_workspace_guides
   verify_examples
 }